Autenticação
Como autenticar chamadas à API com a chave da sua organização, onde gerá-la, como rotacioná-la e o que fazer se ela vazar.
Formato do token
Cada API key segue o formato:
cnh_<ambiente>_<prefix>_<secret><ambiente>—livepara chaves de produção,testpara a chave do ambiente de teste, que toda organização já tem.<prefix>— 12 caracteres públicos usados para lookup rápido; aparece na listagem de chaves.<secret>— segredo gerado aleatoriamente; numa chave de produção, exibido uma única vez na criação. A chave de teste continua visível em Configurações → API.
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.
Token OAuth do MCP não autentica esta API
O fluxo OAuth para clientes de IA desktop
autentica apenas o servidor MCP. Os endpoints REST (/api/v1/...) só aceitam uma API
key cnh_<ambiente>_<prefix>_<secret> no header Authorization — as duas superfícies não
compartilham credencial.
Gerar uma chave
Abrir Configurações → API
Na sua organização, vá para Configurações → API. A página existe para toda organização, com a chave de teste já pronta; as chaves de produção aparecem depois que o acesso à produção é liberado.
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 (até 5 por minuto). Só proprietários e administradores da organização alteram o webhook e enviam o evento de teste.