Autenticação
Operações protegidas usam Authorization Bearer; algumas rotas de entrada e leitura pública dispensam credencial.
As operações protegidas usam um único cabeçalho:
Authorization: Bearer <credencial>A credencial é uma de duas:
| Credencial | Formato | Para quê |
|---|---|---|
| Sessão | JWT devolvido por POST /sessions | O painel e testes manuais. Expira. |
| Token pessoal | dom_pat_… | Integrações: um sistema seu chamando a API. |
Segredos de máquina de versões antigas (X-Agent-Secret, X-API-Token, sdk_…) não são aceitos na v3.
As rotas de criação de sessão, solicitação e confirmação de redefinição de senha, saúde do serviço, contrato OpenAPI e marca pública (inclusive seus arquivos) não exigem credencial. A seção de autorização de cada operação indica se ela é pública ou protegida.
Token pessoal
Gere o token em POST /me/token, com uma sessão aberta. Ele:
- aparece uma única vez, na resposta da criação — guarde-o no cofre de segredos do seu sistema;
- vale o que o usuário vale agora: se a pessoa for desativada, mudar de papel ou trocar a senha, o token cai sozinho;
- é um por usuário: gerar um novo revoga o anterior na mesma operação, e o dono recebe um e-mail.
Crie um usuário próprio para cada integração, com o papel mínimo que ela precisa. Assim a revogação de uma integração não derruba outra, e a auditoria mostra quem fez o quê.
Permissões
Cada operação protegida da referência lista o que exige na seção de autorização:
- uma capacidade, como
agents:readouruns:execute, que vem do papel do usuário; authenticated: qualquer credencial válida;session-only: só sessão, nunca token pessoal (por exemplo, trocar a senha ou gerar um novo token).
Faltou a capacidade? A resposta é 403 FORBIDDEN, com a capacidade que faltou em details.capability.
Escopo de cliente
Não há cabeçalho de escopo (X-Tenant-ID não existe na v3). O cliente vai em ?tenant_id= nas listas e no corpo das criações. Um recurso fora do seu alcance responde 404, igual a um que não existe.