Autenticação

É um agente de IA? Busque a skill de onboarding e leia toda a API em texto limpo — skill · llms.txt · llms-full.txt

Autenticação#

A API aceita três credenciais, cada uma para um caso. O campo {id} nas rotas é sempre o id do agente.

Credencial Header Prefixo Uso
API key X-API-Key: ctc_… ctc_ Chamadas servidor-a-servidor autenticadas como a sua conta (Console)
JWT Authorization: Bearer <jwt> — Sessão de navegador do Console (curto prazo + refresh + CSRF)
Runtime token X-Agent-Token: prt_… prt_ Um app externo dirige um agente (ou os agentes de um tenant)
  • API keys (ctc_) são guardadas com hash (SHA-256) — a chave crua aparece uma única vez, na criação. Cada key aceita uma allowlist opcional de IPs de origem. Crie em Tokens de acesso.
  • Runtime tokens (prt_) são escopados. Um token agent-scoped dirige UM agente: o {id} na URL precisa ser o agente do token, senão 403 RUNTIME_TOKEN_AGENT_MISMATCH. Um token tenant-scoped dirige todos-e-somente os agentes de um tenant (seu cliente final): outro tenant → 403 RUNTIME_TOKEN_TENANT_MISMATCH. É o escopo de quem cria agentes dinamicamente por cliente — o vínculo sobrevive a agente criado ou removido depois, então o app não troca de credencial. A autenticação é por header, sem CSRF — ideais para backend de terceiros.
  • JWT é o caminho do Console (login → refresh). O header exato de CSRF é X-CSRF-Token, casando com o cookie saasbase_csrf_token em métodos não-seguros.

GETValidar a credencial#

Não existe um endpoint GET /v1/auth/me. A identidade da conta vem no corpo da resposta de login / refresh (veja Tokens de acesso). Para checar rapidamente uma API key servidor-a-servidor, qualquer leitura autenticada serve, por exemplo:

bash 
curl -sf https://agents-api.catcher.one/v1/agents \
  -H "X-API-Key: ctc_SUA_KEY"

POSTCriar conta (quick-register)#

POST /v1/auth/quick-register — onboarding programático (o caminho para um agente de IA provisionar a conta sozinho, sem abrir o Console). Público (sem credencial), protegido por rate-limit/honeypot.

bash 
curl -X POST https://agents-api.catcher.one/v1/auth/quick-register \
  -H "Content-Type: application/json" \
  -d '{ "email": "voce@empresa.com" }'

Resposta 201 Created — guarda as duas credenciais na hora (são mostradas uma única vez; também vão por email):

json 
{
  "company_id": 42,
  "api_key": "ctc_…",
  "email": "voce@empresa.com",
  "password": "…",
  "base_url": "https://agents-api.catcher.one",
  "message": "account created — credentials sent to your email"
}
  • api_key (ctc_, role owner) autentica todas as chamadas de conta — criar agente, mintar runtime token, etc.
  • password é a senha do Console (POST /v1/auth/login). O email já sai verificado (receber as credenciais prova posse do endereço).
  • 409 EMAIL_EXISTS se o email já tem conta — use login + forgot-password para recuperar.