Autenticação

Toda chamada à API usa um token de API no header Authorization, no formato Bearer. O token começa com pk_, pertence a uma organização, e o que ele alcança depende do escopo escolhido ao gerá-lo.

Authorization: Bearer pk_seu_token_aqui

Escopos

Ao gerar o token, você escolhe em O que este token pode fazer:

• Acesso total — usa toda a API pública da organização: chat, conversas, contatos, listas, agentes, bases, tags, métricas e envio de e-mail.
• Apenas enviar e-mails — só envia e consulta e-mails (E-mails), e só pelos remetentes marcados em Remetentes permitidos. Qualquer outro endpoint responde 403 forbidden com reason: "token_scope_email_only".

O escopo é definido na criação, e a interface não permite alterá-lo depois. Para trocar, gere outro token e revogue o anterior. A tabela de tokens mostra o escopo abaixo do nome: Acesso total ou Apenas e-mail, com a quantidade de remetentes.

Cuidado

Um token com Acesso total age como a organização inteira na API. Trate cada token como uma senha privilegiada: mantenha-o server-side e nunca o exponha em frontend, aplicativo móvel, repositório, log, conversa ou prompt. Quando a integração só envia e-mail, prefira Apenas enviar e-mails.

Gerar um token

Você precisa de Criar e rotacionar tokens de API. Administradores recebem essa capacidade por padrão, e funções personalizadas podem recebê-la separadamente.

1. Abra Configurações pelo menu do avatar e selecione Desenvolvedores → API. O endereço direto é /settings/api.

2. Na aba Tokens, clique em Gerar Token API.

3. Informe um Nome do Token, como n8n produção ou backend interno.

4. Em O que este token pode fazer, escolha Acesso total ou Apenas enviar e-mails. Para Apenas enviar e-mails, marque ao menos um remetente em Remetentes permitidos; a lista mostra os remetentes cadastrados em Configurações → E-mail e avisa quando o domínio ainda não foi verificado.

5. Clique em Gerar Token.

6. Em Token Gerado, copie o valor imediatamente. Ele é exibido uma única vez; o SquadOS armazena somente o hash e o prefixo.

Se fechar o diálogo ou perder o valor, não há recuperação. Gere outro token, atualize a integração e revogue o anterior.

Usar o token

A base de produção é https://api.squados.io/v1. Inclua o header em toda requisição e use Content-Type: application/json quando houver corpo:

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

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

O token determina a organização da chamada. IDs de outra organização não ficam acessíveis com essa credencial.

Gerenciar tokens

A tabela em API → Tokens mostra nome, prefixo, status, criação, último uso e quantidade de chamadas. O valor secreto completo nunca reaparece.

• Visualizar tokens de API permite abrir e consultar a tabela.
• Criar e rotacionar tokens de API permite gerar e revogar.
• Excluir tokens de API permite apagar definitivamente um registro.

Revogar token interrompe a autenticação e preserva a linha como Revogado. Excluir token remove a linha após confirmação. Tokens revogados não podem ser reativados.

Dica

Use um token por integração e ambiente. Para rotacionar sem interrupção, gere o novo, troque o segredo no consumidor, confirme uma chamada e só então revogue o antigo.

Erros de autenticação

Token ausente, malformado, inválido ou revogado retorna 401:

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

Confira o espaço depois de Bearer, o prefixo pk_ e se o token continua Ativo. A interface atual não configura expiração automática. Veja Erros para o contrato completo.

Interface em inglês

As notificações de criação, revogação e exclusão ainda aparecem em português mesmo quando a interface está em inglês. Isso não altera o resultado da operação.