Tokens de API
Toda chamada à API do Dashboard Mágico leva um token: uma credencial que diz qual organização está chamando. Você o envia no header Authorization: Bearer <token> de cada requisição.
Onde criar o token
Os tokens são criados e gerenciados na Conta Kobana, não no Dashboard Mágico. A aba Tokens de API de Sistema › API (/dashboard/api) leva você até lá:
- Abra Sistema › API, aba Tokens de API.
- Clique em Seguir pra Criação de Token. A página de tokens da Conta Kobana abre em outra aba.
- Crie o token lá. Na mesma página você revisa e revoga os tokens que já existem.
O token vale para a organização inteira. Para dizer em qual workspace a chamada age, use o header X-Workspace-Id — veja API e webhooks.
Os detalhes técnicos (formato do token, ambientes, erros de autenticação) estão na referência de autenticação da API.
:::warning Sandbox e produção têm tokens diferentes Um token de sandbox não funciona em produção, e vice-versa. Crie um para cada ambiente. :::
Quando os tokens ficam no próprio Dashboard Mágico
Em algumas instalações, a aba Tokens de API mostra a lista de tokens e o botão Gerar Token em vez do atalho para a Conta Kobana. Nesse caso:
- Gerar — dê um nome, uma descrição, a data de validade (em branco, vale por 1 ano) e os e-mails que recebem o aviso de expiração. O token aparece uma única vez: copie e guarde em um cofre de segredos.
- Abrir um token — clique nele na lista para ver os detalhes: origem, validade, último uso e quem criou, alterou, desabilitou ou revogou.
| Ação | O que acontece |
|---|---|
| Desabilitar | O token para de autenticar até ser habilitado de novo. |
| Rotacionar | Gera um token novo, mostrado uma única vez. O antigo continua valendo por 7 dias e depois deixa de funcionar — atualize a integração nesse prazo. |
| Revogar | Encerra o token de vez. Não tem volta. |
| Excluir | Tira da lista um token já revogado. O histórico de auditoria continua lá. |
Os e-mails cadastrados (ou, sem eles, quem criou o token) recebem um aviso quando faltam 30 dias para a expiração.
Boas práticas
- Um token por aplicação. Assim você revoga um sem derrubar os outros sistemas.
- Troque de tempos em tempos. Crie o novo, atualize a aplicação e só então revogue o antigo.
- Nunca no código. Guarde o token em variáveis de ambiente ou num cofre de segredos.
As requisições respeitam os limites de Rate limiting.