Como funcionam as API Keys
Cada chave é gerada com um prefixotml_ seguido de uma string aleatória. A chave completa é exibida apenas no momento da criação — depois disso, apenas o prefixo mascarado fica visível na interface por segurança. Guarde a chave em um gerenciador de segredos imediatamente após criar.
As chaves são escopadas por workspace. Uma chave criada em um workspace não funciona em outros workspaces da mesma conta.
Criando uma API Key
Acesse Configurações > API Keys
No menu lateral, clique em Configurações e selecione a aba API Keys.
Nomeie a chave
Dê um nome descritivo que identifique o sistema que vai usar a chave (ex.: “Integração CRM Salesforce”, “Pipeline de dados”).
Defina os escopos
Selecione as permissões que a chave terá. Aplique o princípio de menor privilégio: conceda apenas os escopos necessários para a integração.
Configure a expiração (opcional)
Defina por quantos dias a chave ficará válida. Deixe em branco para uma chave sem expiração. Recomendamos sempre configurar expiração em ambientes de produção.
Escopos disponíveis
| Escopo | O que permite |
|---|---|
read | Leitura de dados (conversas, agentes, contatos, analytics) |
write | Criação e atualização de registros |
conversations | Acesso específico a conversas (envio de mensagens, encerramento) |
agents | Gerenciamento de agentes via API |
analytics | Acesso a métricas e exportações |
read é suficiente. Evite criar chaves com write em ambientes de produção a menos que a integração precise criar ou modificar registros.
Gerenciando chaves existentes
Na lista de API Keys, cada entrada mostra:- Nome da chave
- Prefixo mascarado (
tml_xxxx...) - Status (ativa / inativa)
- Último uso
- Data de expiração (quando configurada)
- Número de requisições realizadas
Ativar / Desativar uma chave
Ativar / Desativar uma chave
Clique no menu de opções da chave e selecione Ativar ou Desativar. Desativar uma chave bloqueia imediatamente qualquer requisição que a utilize, sem deletá-la. Útil para pausar uma integração temporariamente.
Editar nome e descrição
Editar nome e descrição
Clique em Editar no menu de opções para alterar o nome ou a descrição da chave. Escopos e expiração não podem ser alterados após a criação — nesse caso, delete e crie uma nova chave.
Ver estatísticas de uso
Ver estatísticas de uso
Clique em Ver uso para abrir o painel de estatísticas da chave: total de requisições, taxa de sucesso, endpoints mais acessados e atividade recente.
Deletar (revogar) uma chave
Deletar (revogar) uma chave
Clique em Deletar no menu de opções. A chave é revogada imediatamente e permanentemente. Qualquer sistema que a utilizava perde acesso na hora. Não é possível desfazer.
Rotação de chaves
Rotacionar uma chave significa criar uma nova com os mesmos escopos e deletar a antiga. Faça isso:- Periodicamente (boa prática de segurança, recomendado a cada 90 dias)
- Após suspeita de comprometimento
- Quando um colaborador que tinha acesso à chave deixa a empresa
- Crie uma nova chave com os mesmos escopos.
- Atualize a nova chave em todos os sistemas que usam a chave antiga.
- Teste para confirmar que os sistemas funcionam com a nova chave.
- Delete a chave antiga.
Segurança
- Chaves com escopos de
writedevem ter expiração configurada. - Mantenha uma chave por integração — nunca reutilize a mesma chave em múltiplos sistemas.
- Monitore o painel de uso regularmente para detectar uso anormal ou não esperado.