Skip to main content
A autenticação na API da Timely.ai é feita via API key enviada em todas as requisições no header x-api-key. Não há OAuth, não há sessões — só a chave.

​
Enviando a chave

GET /v1/agents HTTP/1.1
Host: api.timelyai.com.br
x-api-key: tly_live_xxxxxxxxxxxxxxxxxxxxxxxx
Em variáveis de ambiente, sempre armazene a chave como TIMELY_API_KEY e referencie via process.env (Node), os.environ (Python) ou os.Getenv (Go). Nunca hardcode.

​
Criando uma API key

  1. Acesse app.timelyai.com.br
  2. Vá em Configurações → API Keys → Nova chave
  3. Dê um nome que identifique o uso (ex: crm-integracao, n8n-automacoes)
  4. Selecione os escopos necessários (princípio do menor privilégio)
  5. Copie a chave — ela aparece uma única vez
Se perder a chave, não é possível recuperá-la. Você precisará revogar e criar uma nova. Planeje o rollout antes de revogar chaves em produção.

​
Escopos disponíveis

Cada API key tem um conjunto de escopos que define o que ela pode fazer. Conceda apenas o que o serviço precisa.
EscopoPermissão
agents:readListar e visualizar agentes
agents:writeCriar, editar e excluir agentes
EscopoPermissão
conversations:readListar e ler conversas
conversations:writeCriar, atualizar e encerrar conversas
messages:sendEnviar mensagens via agente
chats:manageGerenciar threads de chat, incluindo histórico
EscopoPermissão
contacts:readListar e buscar contatos
contacts:writeCriar, editar e excluir contatos
custom-fields:manageGerenciar campos customizados do CRM
EscopoPermissão
channels:readListar canais conectados
channels:writeConfigurar e desconectar canais
EscopoPermissão
training:readVisualizar base de conhecimento
training:writeAdicionar e remover documentos do treinamento
EscopoPermissão
workspaces:readVisualizar workspaces
workspaces:writeCriar e configurar workspaces
EscopoPermissão
webhooks:manageCriar, listar e excluir endpoints de webhook
followups:manageGerenciar regras de follow-up automático
EscopoPermissão
appointments:readVisualizar agendamentos
appointments:writeCriar e cancelar agendamentos
EscopoPermissão
mcp-servers:manageRegistrar e remover MCP servers externos

​
Boas práticas de segurança

Use uma chave por serviço. Se um serviço for comprometido, você revoga só a chave dele sem afetar o restante. Escopos mínimos. Um job que só lê conversas não precisa de agents:write. Quanto menor o escopo, menor o raio de impacto de um vazamento. Rotação periódica. Troque as chaves a cada 90 dias ou sempre que um membro do time que tinha acesso às credenciais sair. Monitore o uso. Em Configurações → API Keys, você vê o volume de requisições por chave. Picos inesperados podem indicar uso não autorizado.

​
Rotacionando uma chave

1

Crie a nova chave

Em Configurações → API Keys → Nova chave, crie a substituta com os mesmos escopos da chave atual.
2

Atualize os serviços

Atualize a variável de ambiente em todos os serviços que usam a chave antiga. Faça o deploy ou reinicie os serviços.
3

Revogue a chave antiga

Após confirmar que os serviços estão operacionais com a nova chave, clique em Revogar na chave antiga. A revogação é imediata — qualquer requisição com a chave antiga retorna 401.

​
Erros comuns de autenticação

StatusCausaSolução
401 UnauthorizedChave ausente, inválida ou revogadaVerifique o header x-api-key
403 ForbiddenChave válida, mas sem o escopo necessárioAdicione o escopo faltante na chave
API keys são isoladas por workspace. Uma chave criada no workspace “Suporte” não acessa dados do workspace “Vendas”.