Faça a primeira requisição

1. Crie uma chave de API

Quem cria a chave é um usuário com a permissão CADASTRAR_CHAVE_API, em Configurações → Chaves de API do MSP Desk. Escolha os escopos e a validade e copie o segredo: ele aparece uma única vez. Se você perder, crie outra chave. Detalhes em Chaves de API.

Para este exemplo, marque o escopo settings:read, que a listagem de tags exige. Os escopos podem ser editados depois; se a API da empresa estiver desabilitada, só os escopos liberados por concessão aparecem disponíveis.

2. Chame a API

Envie a chave no cabeçalho Authorization, no formato Bearer:

curl -H "Authorization: Bearer mspd_live_…" \
  https://public-api.mspdesk.com.br/v1/tags

O resultado tem este formato:

{
  "data": [
    {
      "color": "RED",
      "createdAt": "2026-01-10T15:00:00Z",
      "id": 1,
      "name": "urgente",
      "updatedAt": "2026-01-10T15:00:00Z"
    }
  ],
  "nextCursor": null
}

3. Guarde o `X-Request-Id`

Toda resposta traz o cabeçalho X-Request-Id. Ele identifica aquela requisição no MSP Desk: registre-o nos seus logs e informe-o ao suporte quando precisar de ajuda com uma chamada específica. Os erros repetem esse valor no campo requestId.

4. Entenda `401` e `403`

401: o problema é a chave (ausente, inválida, expirada, revogada ou inativa).

{
  "code": "invalid_api_key",
  "detail": "A chave de API apresentada é inválida, desconhecida ou está ausente.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 401,
  "title": "Chave de API inválida",
  "type": "https://developers.mspdesk.com.br/erros/#invalid_api_key"
}

403: a chave foi reconhecida, mas a empresa ou o escopo não permite a chamada.

{
  "code": "public_api_disabled",
  "detail": "A API pública não está habilitada para esta empresa. Fale com a MSP Works para habilitá-la. As chaves de API existentes continuam guardadas e voltam a funcionar quando ela for habilitada.",
  "requestId": "7f3c2a9e-1b4d-4c8e-9a51-2e6f0d8b3c47",
  "status": 403,
  "title": "API pública desabilitada",
  "type": "https://developers.mspdesk.com.br/erros/#public_api_disabled"
}

A tabela “recebi X, faço Y” está em Sua empresa está habilitada?.