API REST e Tokens

A API REST permite que um sistema externo converse com agentes e acesse os recursos publicados pela API da organização. Ela não reproduz todo o painel administrativo: a superfície atual cobre chat, agentes, conversas, bases de conhecimento, tags e listas de contatos.

Cada token pertence à organização selecionada no momento da criação e autoriza toda a superfície pública da API para essa organização. Os tokens atuais não têm escopos por endpoint; trate cada um como uma credencial privilegiada.

Abrir a configuração de API

No menu do seu avatar, abra Configurações.
Na categoria Desenvolvedores, selecione API.
Use a aba Tokens para administrar credenciais ou Documentação para abrir a referência técnica.

O endereço direto é /settings/api.

Permissões

O acesso é separado em três capacidades confirmadas na interface:

Visualizar tokens de API: abre a seção e lista nome, prefixo e uso;
Criar e rotacionar tokens de API: gera e revoga tokens;
Excluir tokens de API: remove definitivamente o registro.

Administradores recebem essas capacidades por padrão. Uma função personalizada pode recebê-las separadamente; portanto, a possibilidade de gerar tokens não depende apenas do nome do papel.

Gerar um token

Em API → Tokens, clique em Gerar Token API.
No diálogo Gerar Token API, informe um Nome do Token que identifique a integração, como n8n produção ou backend interno.
Clique em Gerar Token.
No estado Token Gerado, copie o valor e armazene-o imediatamente em um cofre de segredos ou variável de ambiente do servidor.

O token começa com pk_ e contém 64 caracteres hexadecimais depois do prefixo. O SquadOS exibe o valor completo apenas uma vez e guarda somente seu hash. Fechar o diálogo encerra a única oportunidade de copiar aquela credencial; se ela for perdida, gere outra e revogue a anterior.

Entender a tabela

A aba Tokens mostra:

Nome e Prefixo, usados para identificar a credencial sem revelar o segredo;
Status: Ativo ou Revogado;
Criado em e Último uso;
Chamadas, incrementado quando uma requisição autentica o token;
Ações, conforme suas permissões.

O valor completo nunca volta para a tabela. O prefixo exibido é pk_ mais os oito primeiros caracteres do segredo, seguido de reticências.

Revogar ou excluir

Revogar token desativa a credencial imediatamente, mas conserva nome, prefixo e histórico na tabela. Um token revogado não pode ser reativado.
Excluir token remove o registro definitivamente. A interface pede confirmação porque a ação é irreversível.

Em caso de suspeita de vazamento, revogue primeiro para interromper as chamadas. Exclua somente quando não precisar mais do registro para auditoria.

Usar o token

A base pública é:

https://api.squados.io/v1

Envie o token como Bearer em todas as requisições:

Authorization: Bearer pk_seu_token_aqui

Exemplo de leitura dos agentes da organização:

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

Exemplo síncrono de mensagem:

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}'

Token ausente, malformado, inválido ou revogado recebe 401 com o código unauthorized. Os tokens não possuem data de expiração automática na interface atual.

Recursos disponíveis

Consulte a Visão Geral da API para a base URL, formatos e catálogo atual. A referência está dividida em:

A aba Documentação da configuração abre essa referência. Para executar chamadas no navegador, use o Swagger interativo indicado na Visão Geral.

Proteção e rotação

Gere um token diferente por integração e ambiente para revogar um consumidor sem interromper os demais.
Nunca envie tokens ao navegador, aplicativo móvel, repositório, log, conversa ou prompt de agente.
Armazene-os apenas no servidor, em um gerenciador de segredos.
Compare Último uso e Chamadas antes de aposentar uma credencial.
Para rotacionar, gere o novo token, atualize o consumidor, confirme uma chamada e só então revogue o antigo.