Chaves de API

Formato e guarda

A chave tem o formato mspd_live_ seguido de 43 caracteres base64url. O MSP Desk guarda apenas o hash: o segredo aparece uma vez, na criação. Se você perdeu, crie outra chave. Envie-a sempre no cabeçalho:

Authorization: Bearer mspd_live_…

A chave só é aceita nesse cabeçalho. Enviada na URL (?api_key=… ou parecido), ela não autentica: a requisição responde 401 invalid_api_key. Não coloque a chave na URL — endereços ficam gravados em logs de proxy, histórico e ferramentas de monitoramento. Se isso acontecer por engano, revogue a chave e crie outra.

Cria a chave quem tem a permissão CADASTRAR_CHAVE_API, em Configurações → Chaves de API. Só é possível criar uma chave com escopos cujas permissões o próprio usuário tem.

Escopos de dados (tickets, clientes e outros dados da empresa) só podem ser concedidos por quem enxerga a empresa toda: um usuário com acesso restrito a alguns clientes, ou que não é agente de todos os grupos de serviço ativos, não consegue concedê-los. O perfil administrador da empresa não sofre a restrição de grupos de serviço na gestão de chaves; a restrição de clientes vale para ele também.

Enquanto a API pública da empresa estiver desabilitada, só é possível criar, duplicar ou editar uma chave com os escopos liberados por concessão. Veja Sua empresa está habilitada?.

Estados

Estado	Reversível?	Significado
Ativa	não se aplica	A chave autentica.
Inativa	sim	Desativada por alguém; responde 401 api_key_inactive e pode ser reativada.
Expirada	não	Passou da validade; responde 401 api_key_expired.
Revogada	não	Encerrada de vez; responde 401 api_key_revoked.

Validade

Escolha 30, 90, 180 ou 365 dias, ou sem validade. O padrão pré-marcado é 90 dias. O MSP Desk avisa por e-mail o criador e quem tem a permissão de cadastrar chaves de API 15 dias antes da expiração.

Limites e regras

• Até 20 chaves ativas por empresa.
• A chave pertence à empresa: continua valendo se quem a criou sair.
• A lista de IPs permitidos da empresa não se aplica às chaves de API.

Editar os escopos

Os escopos de uma chave podem ser alterados depois da criação, em Editar na tela da chave (é preciso a permissão EDITAR_CHAVE_API); o segredo não muda.

• Só os escopos adicionados passam pelas regras da criação: o usuário precisa poder concedê-los e, com a API desabilitada, eles precisam estar entre os liberados por concessão.
• Remover um escopo é sempre permitido, mas a chave precisa ficar com pelo menos um. Enquanto a chave tiver o :write de um grupo, o :read desse grupo fica junto: o write inclui o read.
• A mudança vale a partir da próxima requisição feita com a chave.
• Se a chave ganhar um escopo de escrita (:write), quem tem a permissão EDITAR_SEGURANCA na empresa recebe um aviso por e-mail, como na criação de uma chave com escopo de escrita.
• Toda alteração de escopos fica registrada na auditoria de segurança.

Rotação sem indisponibilidade

1. Crie a chave nova, com os mesmos escopos.
2. Troque a chave no seu sistema.
3. Confira o último uso da chave antiga: ele deve parar de avançar.
4. Revogue a chave antiga.

Diagnóstico pela tela

A tela de cada chave mostra o último uso, o total de requisições e de respostas 429 nas últimas 24 horas e os últimos 50 erros, cada um com o requestId. Use esses dados para investigar uma falha. Veja também Escopos e Sua empresa está habilitada?.