Autenticação
Os três tipos de credencial aceitos pela API e quando usar cada um.
Toda chamada à API envia uma credencial no header Authorization, no formato Bearer <credencial>. A plataforma aceita três tipos, e a escolha define em nome de quem a chamada acontece.
curl https://<seu-host-aumo>/api/v1/me \
-H "Authorization: Bearer <sua-credencial>"Tipos de credencial
| Credencial | Formato | Age como | Use para |
|---|---|---|---|
| Token de usuário | JWT emitido pelo login | O usuário logado | Admin, Chat e ferramentas internas com sessão de usuário. |
| Personal Access Token (PAT) | aumo_pat_<prefixo>_<segredo> | O dono da chave | Scripts e integrações que agem em nome de uma pessoa. |
| Chave de projeto | aumo_pk_<prefixo>_<segredo> | A própria chave | Integrações de um workspace que não devem depender de uma pessoa. |
Personal Access Token
Um PAT age como o usuário que o criou. Ele nunca tem mais permissão que o papel atual do dono, e fica limitado à organização, aos workspaces permitidos, aos scopes concedidos e à data de expiração.
Se o dono perde acesso ou muda de papel, o PAT acompanha. O consumo de tokens e as cotas contam para o usuário dono da chave.
Chave de projeto
Uma chave de projeto pertence a um único workspace e não tem dono nem papel. Os scopes concedidos na criação são toda a sua autorização.
Por isso ela continua válida depois que a pessoa que a criou sai da organização. Ela só deixa de valer quando é revogada ou expira. Uso e cota são atribuídos à própria chave.
Uma chave de projeto só enxerga as conversas que ela mesma criou.
Criando uma chave
Chaves são criadas por workspace, no platform-core. O valor completo aparece uma única vez, na resposta de criação. Guarde-o num cofre de segredos.
| Método | Rota | Ação |
|---|---|---|
POST | /api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys | Cria um PAT. |
GET | /api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys | Lista os PATs. |
DELETE | /api/v1/org/{org_id}/workspaces/{workspace_id}/api-keys/{api_key_id} | Revoga um PAT. |
POST | /api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys | Cria uma chave de projeto. |
GET | /api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys | Lista as chaves de projeto ativas. Use include_revoked=true para ver as revogadas. |
DELETE | /api/v1/org/{org_id}/workspaces/{workspace_id}/project-keys/{project_key_id} | Revoga uma chave de projeto. |
Só é possível conceder a uma chave de projeto os scopes que você mesmo tem no workspace. Emitir e revogar chaves de projeto exige ser dono do projeto ou admin da organização.
Para trocar uma chave, crie a nova, atualize a integração e só depois revogue a anterior.
Scopes
Cada endpoint exige um scope, indicado na página do endpoint como Scope. Os scopes seguem o padrão <recurso>:<ação>.
| Para | Scopes necessários |
|---|---|
| Conversar com um agente | conversations:write, assistants:read, models:read |
| Anexar arquivos no chat | artifacts:read, artifacts:write |
| Publicar um agente | assistants:publish |
| Chamar modelos diretamente | models:read |
| Executar um workflow | workflow_run:write |
Chamar um agente executa o modelo como o chamador. Por isso uma chave que conversa com agentes precisa também de models:read.
Nenhuma chave pode carregar scopes de gestão de chaves. Uma chave não cria nem revoga outras chaves.