Autenticação
Como gerar, rotar e revogar API keys. Formato Bearer token, segurança e boas práticas de rotação.
Formato do token
Cada API key segue o formato:
cnh_live_<prefix>_<secret>cnh_live_— prefixo fixo de ambiente de produção.<prefix>— 12 caracteres públicos usados para lookup rápido; aparece na listagem de chaves.<secret>— segredo gerado aleatoriamente; exibido uma única vez na criação.
O token completo é enviado no header:
Authorization: Bearer cnh_live_abc123def456_<secret>Guarde o segredo na criação
O valor completo do token é exibido apenas uma vez. Se perder, revogue a chave e crie uma nova. Nunca armazene tokens em repositórios de código, use variáveis de ambiente ou um secret manager.
Gerar uma chave
Abrir Configurações → API
Na sua organização, vá para Configurações → API. A secção só aparece se o acesso estiver habilitado.
Criar nova chave
Clique em Nova chave, dê um nome descritivo (ex.: Produção — Sistema de Frota) e confirme.
Copiar e guardar
O token completo é exibido uma única vez. Copie-o para um secret manager antes de fechar o diálogo.
Revogar uma chave
Na listagem de chaves, clique em Revogar ao lado da chave que deseja desativar.
A revogação é imediata: chamadas com essa chave passam a receber 401 a partir desse instante.
Rotação segura
Para rodar uma chave sem interromper o serviço:
- Crie a nova chave e implante-a no seu sistema (sem remover a anterior).
- Confirme que o novo token está a funcionar verificando
lastUsedAtna listagem. - Revogue a chave antiga.
Configurar webhook (opcional mas recomendado)
Na mesma secção API, preencha a URL do webhook e gere um segredo de assinatura. O segredo é exibido uma única vez, guarde-o para verificar as assinaturas.
Para testar a conectividade, use o botão Enviar evento de teste.