Visão geral e autenticação da API

A API pública da Flow2Agents permite conversar com agentes e consultar dados da organização programaticamente — de scripts, backends próprios ou ferramentas como n8n — sem depender do navegador.

Autenticação

Toda chamada usa um token no cabeçalho Authorization: Bearer f2a_live_..., gerado em Configurações → API (veja Gerando e revogando um token). Não é um JWT de usuário — é um valor opaco próprio da plataforma, específico para esta API.

Escopos

Cada token tem um ou mais escopos, definidos na criação:

• chat — enviar mensagens e ler conversas criadas por este token.
• agents:read — listar agentes da organização e consultar saldo/uso.
• widget — escopo mínimo usado internamente pelo widget incorporável; não crie um token com esse escopo manualmente para uso próprio.

Token completo vs. token de widget

Um token normal (chat e/ou agents:read) tem acesso à organização inteira — pode conversar com qualquer agente ativo e, com agents:read, listar todos e consultar uso. Um token de widget é vinculado a um único agente (agent_id fixo) e só pode conversar com esse agente específico — mesmo se, hipoteticamente, tivesse outros escopos, o vínculo a um agente único sempre prevalece. Isso é o que torna seguro reaproveitar o mesmo token de widget entre todos os visitantes anônimos de uma página pública: ele nunca alcança nada além daquele agente.

Versionamento

Todas as rotas usam o prefixo /v1/ (por exemplo, GET /v1/agents) — parte do contrato público, não uma duplicação acidental. Mudanças que quebrem compatibilidade chegarão em /v2/, mantendo /v1/ funcionando por um período de transição.