Autenticação
Como autenticar requisições com Bearer API key, gerenciar escopos e rotacionar chaves.
Toda chamada à API requer o header Authorization: Bearer <api-key>. Sem header válido, o servidor responde 401 Unauthorized.
Formato do header
Authorization: Bearer crm_live_a1b2c3d4e5f6_AbCdEfGhIjKlMnOpQrStUvWxYz012345A chave começa com prefixo crm_live_ (produção), seguido de 12 caracteres hexadecimais que identificam visualmente a chave (prefixo público) e um segredo aleatório opaco de no mínimo 32 caracteres.
Nunca coloque a chave em código-fonte, logs, URLs ou parâmetros de query. Use variáveis de ambiente ou um cofre de segredos (AWS Secrets Manager, Vercel env vars, etc).
Escopos
Cada chave tem um conjunto de escopos. Sem o escopo necessário, a requisição falha com 403 Forbidden.
| Escopo | O que permite |
|---|---|
contacts:read | Listar e detalhar contatos |
contacts:write | Criar e editar contatos (em desenvolvimento) |
messages:read | Ler mensagens e conversas |
messages:write | Enviar mensagens (em desenvolvimento) |
webhooks:manage | Configurar webhooks de entrada (planejado) |
Veja Escopos mínimos para o princípio do menor privilégio.
Rotação
Rotacione a chave em qualquer suspeita de comprometimento ou conforme política interna da sua empresa (recomendado: a cada 90 dias).
- Crie uma nova API key em Configurações → API, com os mesmos escopos
- Atualize sua integração para usar a nova chave (deploy + smoke test)
- Após confirmar que está funcionando, revogue a chave antiga
Esse fluxo permite zero downtime durante a troca.
Se a chave vazou em log público, repo Git ou similar:
- Revogue imediatamente em Configurações → API → [chave] → Revogar
- Crie uma nova chave
- Atualize a integração
Aceite o downtime — vazamento confirmado é grave.
Erros de autenticação
A API retorna formato flat: { "error": string, "code"?: string }.
| Código HTTP | code | Significado |
|---|---|---|
| 401 | missing_api_key | Header Authorization ausente ou vazio |
| 401 | invalid_api_key | Chave malformada ou nunca existiu |
| 401 | revoked_api_key | Chave foi revogada manualmente |
| 401 | expired_api_key | Chave passou da data de expiração |
| 403 | missing_scope | Chave válida, mas sem o escopo necessário para a operação |
| 403 | forbidden | Acesso ao recurso negado (ex: organization_id de outra org) |
Exemplo de tratamento
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (!res.ok) {
const body = await res.json();
switch (body.code) {
case "revoked_api_key":
case "expired_api_key":
throw new Error("API key precisa ser substituída");
case "missing_scope":
throw new Error(`Falta escopo para esta operação: ${body.error}`);
default:
throw new Error(`API error ${res.status}: ${body.error}`);
}
}
const data = await res.json();Próximos passos
- Escopos mínimos — qual conjunto sua integração realmente precisa
- Erros e retry — estratégia completa de tratamento
- Referência: autenticação — security scheme detalhado