Autenticação e chaves
Toda chamada à API leva o cabeçalho:
Authorization: Bearer <chave>
Token do projeto e chaves de API
Um projeto tem o token do projeto, criado junto com ele, e pode ter quantas chaves de API quiser. As duas autenticam do mesmo jeito e enxergam o mesmo projeto.
Crie uma chave por integração: ao revogar a do ambiente de testes, a de produção continua funcionando. Revogar uma chave faz quem a usa receber 401 na hora; as outras seguem valendo.
O token do projeto também é o segredo que assina os webhooks. Chaves de API não assinam nada: revogar uma chave não muda a assinatura que o seu sistema confere.
Escopos
Cada chave tem os escopos que você escolheu na criação:
| Escopo | Para quê |
|---|---|
send |
Enviar mensagens, cancelar, registrar e remover opt-out, assumir e devolver conversas |
read_logs |
Consultar o status de uma mensagem, a mídia recebida, a foto do contato e a lista de opt-outs |
manage_instances |
Criar, atualizar e desconectar números, e configurar a fonte de dados do agente |
O escopo que vale é a interseção entre o da chave e o teto do projeto, que o operador do gateway define: quem administra o projeto só consegue pedir menos que isso.
Erros de autenticação
| Resposta | Quando |
|---|---|
401 token ausente |
Faltou o cabeçalho Authorization |
401 token invalido |
Valor desconhecido, chave revogada ou projeto inativo |
403 token sem o escopo '...' |
A chave existe, mas não tem aquele escopo |
403 origem nao autorizada |
O projeto restringe os IPs de origem e este não está na lista |
Cuidados
- O valor da chave aparece uma vez, ao criar. No servidor fica só um hash: se perder, crie outra.
- Não coloque a chave em aplicativo de celular nem em página web. Ela é para o servidor do seu sistema.
- Se uma chave vazou, revogue-a no painel e crie outra.