Tokens de API
- O que são tokens de API públicos e quando você precisa deles
- Como criar, visualizar e gerenciar tokens
- Melhores práticas de segurança para lidar com tokens
Tokens de API Públicos permitem que aplicações externas, scripts e serviços se autentiquem com a API do AutoTalk. Você gerencia tokens na página Tokens de API em Integrações na barra lateral.
Quando você precisa de tokens de API
Você precisa de um token de API sempre que um sistema externo precisa se comunicar com o AutoTalk programaticamente. Cenários comuns incluem:
- Conectar um CRM ou helpdesk que envia ou busca dados do AutoTalk
- Construir uma integração personalizada que envia mensagens ou lê conversas pela API
- Configurar scripts de automação que criam contatos, atualizam registros ou disparam workflows
- Integrar plataformas não suportadas ou sistemas internos por meio de uma ponte personalizada, como um pipeline de notificações do Discord
Gerenciando tokens
Visualizando tokens existentes
Navegue até Integrações > Tokens de API. A página lista todos os seus tokens existentes. Você pode filtrar a lista, abrir um token para ver seus detalhes e excluir tokens; tokens não podem ser editados após a criação.
Criando um novo token
- Na página Tokens de API, clique no botão + (seu tooltip exibe "Add new public_api_tokens").
- Revise o alias gerado ou troque por um rótulo próprio.
- Escolha as permissões. Em Permissões, marque o que a integração precisa na grade de permissões, ou parta de um modelo (Somente leitura, Operador, Acesso total) e ajuste. Ao menos uma é obrigatória — um token que não concede nada não pode ser salvo. Permissões que você não marcou podem aparecer marcadas e travadas: uma mais forte que você marcou as carrega. Veja Permiss ões abaixo. As permissões não podem ser alteradas depois — um token que precise de outro conjunto tem de ser substituído.
- Escolha uma duração. Novos tokens usam 90 dias por padrão, com opções de 7, 30, 90, 365 dias ou nunca expirar.
- Salve o token.
- Copie imediatamente o token gerado ou o comando MCP para Codex / Claude Code. O token completo é exibido apenas uma vez.
Visualizando ou excluindo um token
- Clique em qualquer token na lista para visualizar detalhes, expiração e estatísticas de uso.
- Para revogar um token, exclua-o da lista. Qualquer sistema externo usando esse token perderá acesso imediatamente.
Usando tokens em requisições de API
Envie o token no cabeçalho x-api-key em cada requisição para a API pública do AutoTalk. As chaves sempre começam com sk-:
x-api-key: sk-YOUR_API_KEY
Exemplo mínimo com curl:
curl -H "x-api-key: sk-YOUR_API_KEY" https://api.autotalk.io/v1/self
Veja a Referência da API para o catálogo completo de endpoints.
Alternativa: x-jwt-token
A mesma API também aceita JWT de curta duração pelo cabeçalho x-jwt-token (ou pelo cabeçalho unificado x-auth-token, que detecta o prefixo sk- para rotear automaticamente). Os JWT são emitidos internamente pela ação de workflow de agente actions/security/auth/jwt/generate — destinam-se a agentes que chamam a API pública em nome da própria empresa. Integrações externas devem continuar usando x-api-key. Veja Autenticação para a especificação completa.
Melhores práticas de segurança
- Trate tokens como senhas. Nunca os compartilhe em repositórios de código públicos, mensagens de chat ou e-mails.
- Use nomes descritivos. Rotule cada token com a integração ou sistema ao qual pertence, para poder identificá-lo depois.
- Revogue tokens não utilizados. Se uma integração foi aposentada ou um token não é mais necessário, exclua-o imediatamente.
- Rotacione tokens periodicamente. Substitua tokens em um cronograma regular para reduzir o risco caso um seja acidentalmente exposto.
- Conceda o conjunto mais restrito que funcione. Ao menos uma permissão é obrigatória, e um token ainda concede tudo o que suas permissões implicam — "Executar workflows", por exemplo, carrega junto tudo o que os passos do workflow fazem. Use um token separado por integração para que a revogação seja direcionada, e trate um token vazado como o comprometimento de tudo o que suas permissões cobrem.
Permissões
As permissões formam uma pequena árvore: escolher uma mais forte carrega automaticamente as mais fracas abaixo dela, e o seletor as mostra já marcadas. Conceda o conjunto mais restrito de que a integração realmente precisa.
| Permissão | Nome na API | O que concede |
|---|---|---|
| Ler registros | data:read | Acesso somente leitura aos seus dados e esquemas |
| Criar, atualizar e excluir registros | data:write | Escritas nos seus dados, incluindo funções de documento. Carrega data:read |
| Exclusões em massa e em cascata | data:admin | Exclusões destrutivas e de alcance ilimitado. Carrega data:write |
| Enviar mensagens | messaging:send | Mensagens nos seus canais, além de excluir conversas e mensagens |
| Ler arquivos | storage:read | Ler e listar arquivos armazenados |
| Enviar arquivos | storage:write | Escrever no armazenamento. Carrega storage:read |
| Excluir arquivos | storage:admin | Excluir arquivos. Carrega storage:write e storage:share |
| Links de compartilhamento | storage:share | Criar URLs de download utilizáveis fora do AutoTalk. Carregada apenas por storage:admin — nunca por leitura ou escrita |
| Executar IA cobrada | ai:run | Geração por LLM e transcrição que custam dinheiro |
| Executar workflows salvos | workflows:run | Executa um workflow que esta conta já escreveu — incluindo os registros, mensagens, arquivos e IA que seus passos usam. Não cria, edita nem ativa um fluxo |
| Automação e código | automation:admin | Execução de código arbitrário. Também criar e ativar workflows, HTTP de saída, emitir tokens e ler segredos armazenados |
| Administração da conta | org:admin | Tudo nas dez áreas abaixo de uma vez |
| Equipe | org.team:admin | Convites e funcionários |
| Faturamento | org.billing:admin | Orçamento, créditos e assinaturas |
| Canais | org.channels:admin | Canais e integrações, incluindo ações de moderação na plataforma conectada |
| Tipos personalizados | org.types:admin | Criar e alterar tipos personalizados |
| Webhooks | org.webhooks:admin | Configuração de webhooks — e portanto egresso de saída configurado |
| Agentes e perfis | org.agents:admin | Agentes, perfis de transcrição e perfis de voz |
| Chaves de API | org.keys:admin | Reemitir o segredo de uma chave de API |
| Exportação de dados | org.export:admin | Transferência e exportação de dados |
| Onboarding | org.onboarding:admin | Fluxos de onboarding |
| Depuração do agente | org.debug:admin | Ferramentas de depuração do agente de IA |
| Acesso total | account:admin | Todas as permissões acima |
Duas consequências da árvore que vale dizer explicitamente:
- "Executar workflows salvos" carrega autoridade real. A execução de um workflow
exerce tudo o que seus passos fazem, então essa permissão carrega junto acesso
a dados, mensagens, arquivos e IA. O que ela não carrega é a autoria: criar,
editar ou ativar um workflow é
automation:admin. automation:adminé uma cerca. Nada a implica além do acesso total. Um workflow cujos passos executam código, chamam uma URL externa ou emitem um token é recusado por inteiro se a chave não a tiver.
Uma chamada que as permissões do token não cobrem é recusada com HTTP 403 e
o código de erro scope_denied. A resposta nomeia a permissão que faltou.
Se você suspeitar que um token foi comprometido, revogue-o imediatamente excluindo-o da lista de Tokens de API, depois crie um novo e atualize a integração afetada.
Próximos passos
- Referência da API — Navegue por todos os endpoints e schemas disponíveis da API (documentação interativa)
- Webhooks — Configure notificações de eventos de saída
- Adicionando uma integração — Passo a passo geral de configuração de canal