Autenticação

Como habilitar a API HTTP de um agente e autenticar suas requisições.

Chave por agente

A API HTTP é habilitada por agente, e cada agente tem a sua própria chave. Isso mantém o escopo pequeno: uma chave vazada afeta um agente, não o workspace inteiro.

ℹ️

A ativação da API e a geração da chave ainda não têm tela no painel — hoje são feitas pela API de administração (autenticada com a sessão do usuário) ou pelo suporte. Peça a habilitação informando o ID do agente.

Endpoints envolvidos (autenticados com a sessão do painel):

POST   /api/agents/{agent_id}/http-api-key   → gera (ou rotaciona) a chave
DELETE /api/agents/{agent_id}/http-api-key   → revoga a chave

⚠️

A chave é exibida uma única vez, no momento da geração — a plataforma guarda apenas o hash. Perdeu? Gere outra (a anterior deixa de funcionar na hora).

Usando a chave

Envie a chave no header Authorization:

curl -X POST https://api-agent.takesales.ai/api/agent/AGENT_ID/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"message":"Olá!"}'

JavaScript

const res = await fetch(
  `https://api-agent.takesales.ai/api/agent/${agentId}/messages`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TAKESALES_AGENT_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message: 'Olá!' }),
  },
);
 
const data = await res.json();

Python

import os, requests
 
res = requests.post(
    f"https://api-agent.takesales.ai/api/agent/{agent_id}/messages",
    headers={"Authorization": f"Bearer {os.environ['TAKESALES_AGENT_KEY']}"},
    json={"message": "Olá!"},
)
data = res.json()

Limites e erros

Erro	Causa	O que fazer
`401 Missing bearer token`	Header ausente ou sem o prefixo `Bearer`	Corrija o header
`401 Invalid bearer token`	Chave errada ou já rotacionada	Gere e distribua a nova chave
`401 HTTP API key not configured`	API habilitada, mas sem chave gerada	Gere a chave
`403 HTTP API disabled for this agent`	API não habilitada para esse agente	Peça a habilitação
`404 Agent not found`	ID inválido ou agente inativo	Confirme o ID e ative o agente
`402`	Franquia mensal de conversas ou tokens de texto esgotada, ou limite de uso atingido	Veja limites em Configurações → Preferências
`429 Rate limit exceeded`	Mais de 30 requisições por minuto por agente	Aplique backoff

ℹ️

A validação do corpo também é estrita: message é obrigatória e tem limite de 10.000 caracteres; clientVariables aceita no máximo 50 chaves, com valores de até 1.024 caracteres.

Rotação segura

Gere a nova chave (o endpoint rotaciona: a antiga para de valer imediatamente)
Atualize seus sistemas com a nova chave
Valide com uma requisição de teste

⚠️

Como a rotação invalida a chave anterior na hora, faça a troca numa janela combinada com quem consome a API.

Segurança

Nunca use a chave no navegador — ela é de servidor para servidor. Para o front, use o widget ou o SDK, que não exigem chave
Guarde em variável de ambiente, nunca no código-fonte
Uma chave por agente — não compartilhe a mesma integração entre ambientes
Revogue o que não está em uso

# .env (local)
TAKESALES_AGENT_KEY=...

Em Vercel, Railway, Render ou Docker, configure a mesma variável na seção de variáveis de ambiente do serviço.