Autenticação

Toda chamada à API do SquadOS é autenticada por um token de API enviado no header Authorization, no formato Bearer. O token tem o prefixo pk_ e é vinculado à sua organização — ele dá acesso aos agentes, conversas e bases daquela organização.

Authorization: Bearer pk_sua_chave_aqui

Gerando um token

Os tokens são gerados no painel admin, em Configurações → API.

1. No painel admin, abra Configurações e selecione a aba API.

2. Clique em Gerar Token API e dê um nome ao token (ex.: n8n produção, backend interno) para identificá-lo depois.

3. Copie o token na hora. Ele é exibido uma única vez, logo após a criação. Por segurança, o SquadOS guarda apenas um hash — não há como recuperar o valor completo depois. Se perder, gere um novo.

Cuidado

O token concede acesso total aos recursos da sua organização via API. Trate-o como uma senha: guarde-o server-side, em variável de ambiente ou cofre de segredos, e nunca o exponha no frontend, em repositórios públicos ou em logs.

Usando o token

Inclua o header Authorization em toda requisição. Em chamadas com corpo, envie também Content-Type: application/json:

curl https://api.squados.io/v1/agents \
  -H "Authorization: Bearer pk_sua_chave_aqui"

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Olá!", "sync": true }'

Gerenciando tokens

Na mesma aba API, a tabela lista todos os tokens da organização:

• Prefixo — os primeiros caracteres do token (ex.: pk_2d3d0e63...), para você identificar qual é qual sem ver o valor completo.
• Status — Ativo ou Revogado.
• Criado em e Último uso — quando foi gerado e quando foi usado pela última vez.
• Chamadas — quantas requisições já fez com aquele token.

Cada token tem duas ações:

• Revogar — desativa o token imediatamente. Chamadas com ele passam a retornar 401. O registro continua na tabela (marcado como revogado) para auditoria.
• Excluir — remove o token da tabela de vez.

Dica

Use um token por integração (um para o n8n, outro para o backend, etc.). Assim você revoga apenas o que vazou ou aposentou, sem derrubar as outras integrações, e a coluna Chamadas mostra o uso de cada uma separadamente.

Erros de autenticação

Quando o token está ausente, malformado, revogado ou inválido, a API responde 401:

{
  "error": "Invalid or missing API token",
  "code": "unauthorized"
}

Confira se o header está no formato exato Authorization: Bearer pk_... (com o espaço após Bearer) e se o token não foi revogado. Veja Erros para a lista completa de códigos.