Skip to main content
Um token da API dá acesso aos dados da empresa inteira, dentro das permissões marcadas nele. Não existe segundo fator nem confirmação por e-mail. Qualquer pessoa que tenha o token consegue usar a API em nome da empresa. Esta página reúne as práticas que limitam o estrago se um token vazar ou for mal usado. O melhor momento para decidir as permissões de um token é quando você o cria.

​
Um token por integração

O erro mais comum é criar um token “geral”, com todas as permissões, e usar o mesmo em vários sistemas. Se ele vazar, você não sabe por qual sistema vazou, e ao revogá-lo todas as integrações param de uma vez.
Com um token para cada sistema que usa a API, os dois problemas somem. O nome e o lastUsedAt mostram qual sistema usa cada token, e revogar um deles afeta só aquele sistema.

Nomeie pelo sistema que usa

Use nomes como Sincronização de contatos do ERP ou Relatórios noturnos do BI. Um nome como “token 1” não ajuda quando alguém precisar decidir se pode revogá-lo.

Escopo mínimo

Marque só o que a integração usa hoje. Ampliar as permissões depois leva uns 30 segundos no painel. Corrigir o estrago de um token com permissões demais dá muito mais trabalho.

​
O que merece atenção redobrada

Algumas permissões dão mais poder que outras. Duas pedem cuidado especial:
Com users: ["POST"], o token pode convidar pessoas para a empresa. Com users: ["PUT"], pode alterar o perfil de quem já está nela, inclusive promover alguém a administrador. Um administrador, por sua vez, pode criar novos tokens.Dê essas permissões só a integrações de RH ou de provisionamento de acessos que precisem delas de verdade. Se a rotina só precisa listar os usuários, dê apenas GET.
Exclusões pela API não pedem confirmação. Se uma sincronização com defeito chamar DELETE /contacts/{id} repetidamente, não há como desfazer.Se a integração precisa excluir dados, deixe essa parte em uma rotina separada, com um segundo token e log próprio.

​
Prazo e allowlist

1

Defina prazo sempre que fizer sentido

Tokens para um projeto com fim previsto, um teste de fornecedor ou uma prova de conceito devem ser criados já com data de validade. Um token sem prazo continua funcionando anos depois de o projeto acabar.Anote a data de validade junto da documentação da integração. Um token vencido recebe o mesmo 401 de qualquer token inválido, e sem essa anotação fica difícil descobrir por que a integração parou.
2

Restrinja o IP quando houver IP fixo

Com a lista de IPs permitidos (allowlist) preenchida, o token só funciona em chamadas que saem desses endereços. Mesmo que ele vaze, não pode ser usado de outro lugar.A lista aceita endereços IPv4 (200.150.10.20) e faixas CIDR (191.30.0.0/16), com até 50 entradas.
Antes de restringir, confirme o IP de saída real do sistema que usa o token. Serviços em nuvem costumam sair por um endereço diferente do que aparece no painel do provedor, e uma lista errada faz a integração parar na hora.
3

Rotacione periodicamente

Rotacionar gera um novo valor para o token e mantém o nome, as permissões e a allowlist. A configuração da integração continua igual e só a chave muda. O valor antigo deixa de funcionar na hora, então combine o momento da troca com quem cuida do sistema que usa o token.

​
Onde a chave pode ficar

Pode

Variável de ambiente, cofre de segredos (Vault, AWS Secrets Manager, Doppler), configuração cifrada do servidor.

Não pode

Repositório, front-end, aplicativo móvel, planilha, mensagem de chat, ticket de suporte, print de tela.
Nunca chame a API direto do navegador ou de um app móvel. Tudo o que chega ao aparelho do usuário pode ser lido por ele, e a chave ficaria exposta. Faça as chamadas por um serviço seu, que guarda o token e libera para o app só o que aquele usuário pode fazer.
Tome cuidado também com os logs. Registrar a requisição inteira em modo de depuração costuma gravar junto o header Authorization. Oculte esse campo antes de salvar o log.

​
Se uma chave vazou

Revogue ou rotacione agora

Faça isso no painel, em Configurações → Integrações → API. A revogação vale na hora, sem período de tolerância.Rotacione se a integração precisa continuar funcionando. Revogue se ela pode parar.

Veja o que aquele token alcançava

Abra o token e confira as permissões. Elas mostram exatamente o que pode ter sido feito com ele. Um token com reports: ["GET"], por exemplo, dava acesso aos relatórios, mas não permitia alterar nenhum contato.O lastUsedAt mostra quando ele foi usado pela última vez.

Corrija a origem

Se você só rotacionar, sem descobrir como a chave vazou, o problema pode se repetir. Verifique repositório, logs, prints e credenciais compartilhadas em chat, e corrija a causa antes de distribuir a chave nova.

​
Revisão periódica

Uma vez por trimestre, abra a lista de tokens e confira cada um:
Ainda existe uma integração usando este token? O lastUsedAt mostra.
As permissões ainda correspondem ao que a integração faz hoje, ou sobrou alguma de uma versão antiga?
O prazo de validade faz sentido, ou é um token sem prazo de um projeto que já acabou?
Quem criou o token ainda trabalha na empresa? O painel mostra quem criou e quem editou por último.