Autenticação

A API autentica por bearer token. Todo pedido leva o token no cabeçalho Authorization:

Authorization: Bearer <seu token>

Não há sessão, cookie ou passo de troca: o mesmo valor vale em toda chamada até expirar ou ser revogado.

Escopos

Um token só faz o que o escopo permite. Operação fora do escopo responde 403 com o código escopo_insuficiente e não gasta saldo.

Escopo	O que libera	Gasta saldo
consultas	Executar consultas do catálogo	Sim
verify	Criar e acompanhar verificações de identidade	Sim
analises	Criar e acompanhar análises	Sim
leitura	Catálogo, saldo e especificação da API	Não
webhooks	Trocar o destino dos eventos e girar o segredo	Não

O escopo webhooks nunca vem ligado por padrão. Ele redireciona para onde vão os eventos da sua conta, então dê esse poder só a um token de provisionamento, separado do token da integração.

O que mais dá para restringir

• Ambiente. Token de teste responde com dado simulado e não gasta saldo.
• Validade. O token pode nascer com prazo para expirar.
• Endereços permitidos. Restrinja de quais IPs ou faixas o token pode chamar. Fora deles, a resposta é 403.
• Teto de gasto. Limite quanto o token pode gastar. Ao atingir o teto, as chamadas dele respondem 429 com teto_excedido.

Trocar um token sem parar a integração

1. Crie o token novo, com os mesmos escopos do antigo.
2. Troque o valor na sua variável de ambiente e reinicie a aplicação.
3. Confirme no painel que o token novo está sendo usado.
4. Só então revogue o antigo.

Fazer na ordem inversa derruba a integração entre os passos 1 e 2.

Boas práticas

• Nunca no código, nem em repositório privado. Variável de ambiente ou cofre de segredos.
• Nunca no navegador. Token em JavaScript de página é token público. Chame a API a partir do seu servidor.
• Um token por ambiente e por finalidade. O de desenvolvimento não deve conseguir gastar o saldo de produção.