Permissões

Uma requisição autenticada passa por três checagens, nesta ordem. Qualquer uma que negue encerra a requisição com 403.

#	Checagem	O que confere	Recusa
1	Escopo do token	o recurso e o nível de acesso concedidos ao token	403 INSUFFICIENT_SCOPE
2	Papel da pessoa	o que a pessoa do token pode fazer na organização	403 USER_PERMISSION_DENIED ou 403 NOT_A_MEMBER
3	Liberação da organização	se a Kobana liberou a tela equivalente do console para a organização	403 FEATURE_NOT_ENABLED

1. Escopos

O token precisa do escopo do recurso e do nível de acesso que o método exige. A gramática, a tabela de recursos e os exemplos estão em Autenticação → Escopos.

2. Papel da pessoa

Um token emitido para uma pessoa (com a claim email) nunca alcança mais do que a pessoa: além dos escopos, vale o papel dela na organização. Cada rota exige uma permissão agent.<recurso>.<ação>:

Ação	Quando
list, read	listar e detalhar
create, update, delete	criar, alterar e remover
executions.run	disparar uma tarefa
webhook_deliveries.replay	reenviar uma entrega de webhook
repository.sync	sincronizar o Playbook

Os papéis aceitam curingas: *, agent.* e agent.<recurso>.*.

Resposta	Quando
403 USER_PERMISSION_DENIED	o papel não concede a permissão (details.required diz qual)
403 NOT_A_MEMBER	a pessoa do token não tem vínculo com a organização

Um token de integração, sem pessoa, vale só pelos escopos. GET /v1/me não confere papel.

3. Liberação da organização

As rotas que espelham telas do console (disparo, logs, webhooks, entregas, ambientes, secrets, agendamentos, endpoint da tarefa, repositório e uso) respeitam também as liberações que a Kobana dá à organização. Uma operação não liberada responde 403 FEATURE_NOT_ENABLED, com details.permission.

Plano contratado

Disparar uma tarefa exige o Kadu no plano da organização. Sem plano, o disparo responde 403 ENTITLEMENT_REQUIRED, com details.reason e details.required_product. Leitura, cadastro e cancelamento nunca são bloqueados pelo plano. Ver Plano e custos.