Skip to main content
Toda requisição à API v1 leva o token da empresa no header Authorization, no esquema Bearer:
A API não usa login, sessão nem refresh token. O token é a credencial inteira.

O que é o token

Pertence à empresa

Ele não está ligado a nenhum usuário. Continua valendo mesmo se a pessoa que o criou sair da empresa, e as ações feitas com ele aparecem em nome da integração.

Carrega as próprias regras

Permissões por módulo e método, prazo de validade e IPs autorizados ficam no próprio token. Quem cria o token define até onde ele pode ir.
O valor tem o formato sk_live_ seguido de 32 caracteres. Os primeiros caracteres formam o prefixo (sk_live_ab12cd34), que o painel mostra na listagem para você identificar cada token.
Por segurança, a chave completa aparece uma única vez, na criação, e não pode ser recuperada depois. Se você perder a chave, rotacione o token.

Usando em cada requisição

Quando o token é recusado

Token ausente, em formato inválido, inexistente, revogado, expirado ou usado a partir de um IP não autorizado recebem exatamente a mesma resposta:
Por segurança, a API não informa qual foi o motivo da recusa.
Para descobrir o motivo, consulte o painel. Ele mostra o status do token, a data de expiração, os IPs autorizados e o último uso (lastUsedAt). Se o lastUsedAt não mudou, a API não chegou a reconhecer sua requisição.

Prazo de validade

O prazo é opcional e é definido na criação do token. Quando vence, o token para de funcionar na mesma hora, sem aviso prévio e sem período de tolerância.
Anote a data de expiração junto com os dados da integração. Como a resposta é o mesmo 401 genérico, um token vencido parece um token errado, e descobrir a causa leva tempo.
Para trocar a chave sem recriar a integração, use Rotacionar no painel. O token mantém nome, permissões e IPs autorizados e recebe um valor novo, que também aparece uma única vez. O valor antigo deixa de valer imediatamente.

IPs autorizados

Se a integração roda a partir de um IP fixo, restrinja o acesso. Com a lista preenchida, chamadas de qualquer outra origem recebem o mesmo 401.
IPv4
Libera apenas esse endereço, por exemplo 200.150.10.20.
CIDR
Libera qualquer endereço dentro da faixa, por exemplo 191.30.0.0/16.
Regras da lista:
  • Em branco, qualquer origem é aceita. Esse é o padrão quando o campo nunca foi preenchido.
  • Até 50 entradas por token.
  • Somente IPv4. Endereços IPv6 não são aceitos no cadastro.
  • A API considera o IP real da conexão. Por segurança, o header X-Forwarded-For enviado na requisição não altera a origem considerada.
Antes de restringir uma integração que já está em produção, confirme o IP de saída real dela. Serviços em nuvem costumam sair por um endereço diferente do que aparece no painel do provedor, e uma lista errada derruba a integração na hora.

Gestão dos tokens

Criar, editar, rotacionar e revogar tokens são operações feitas no painel, com o login de um administrador. Por segurança, um token de API não consegue gerenciar tokens, e não existe endpoint público para isso.

Permissões

O que cada módulo e método libera.

Segurança do token

Como escolher escopo e prazo, e o que fazer se uma chave vazar.