Autenticação e chaves
Uma chave carrega o workspace e os escopos. É esse par que define o alcance de tudo.
Toda rota do data plane, exceto GET /v1/openapi.json, exige a chave da organização no cabeçalho Authorization: Bearer <chave> — inclusive os três verbos do gateway MCP (POST/GET/DELETE /mcp/{slug}), que usam a MESMA chave gov_ de /v1/*, não uma credencial própria do transporte. Credencial ausente ou inválida recusa 401 nao_autenticado; credencial válida sem alcance recusa 403 escopo_insuficiente — nunca uma resposta vazia.
Authorization: Bearer gov_a1b2c3d4e5f6...
Content-Type: application/jsonDuas famílias de chave, que nunca se substituem
O produto tem duas superfícies, e cada uma tem a própria credencial. Uma chave de uma família nunca autentica a rota da outra — o portão é estrutural, não uma questão de escopo.
| Família | Alcance | Onde autentica |
|---|---|---|
gov_ | Chave de aplicação: pertence a UM workspace e é a credencial do data plane. | /v1/* e /mcp/{slug} (os três verbos) |
govadm_ | Chave administrativa: escopo de organização, para automatizar o que uma pessoa faria no console (criar workspaces, convidar, emitir chaves). | /console/* |
Workspace: o recorte que a chave carrega
O workspace não é um filtro que você passa — é uma propriedade da chave. A trilha que ela lê é a do próprio workspace; pedir a de outro, mesmo dentro da mesma organização, recusa 403 workspace_nao_permitido. É o que permite dar uma chave por time, por ambiente ou por produto sem que um enxergue o tráfego do outro.
Escopos do data plane
Uma chave nova nasce com exatamente o conjunto abaixo — o mesmo que o bootstrap e o "criar chave" do console sempre emitiram, sem escolha de escopo na criação (escolher escopo por chave ainda não existe).
| Escopo | O que abre |
|---|---|
completions.write | Completions, embeddings e prompts versionados — o portão de ESCRITA do data plane inteiro. |
logs.list | GET /v1/logs |
logs.view | Reservado: nenhuma rota do data plane exige este escopo hoje. |
analytics.view | GET /v1/usage |
providers.list | GET /v1/models |
prompts.read | POST /v1/prompts/{referencia}/render |
prompts.list | Reservado: nenhuma rota do data plane exige este escopo hoje. |
mcp.invoke | O proxy do gateway MCP (os três verbos do transporte). |
agent.invoke | O gateway A2A: o proxy JSON-RPC dos agentes e a descoberta do agent card. O escopo é o portão do recurso; quem governa ALCANCE é a provisão do agente por workspace. |
Rotação e revogação
- O segredo aparece uma única vez, na criação (e na rotação). Não existe rota que o devolva depois — nem para o dono da organização.
- Rotacionar troca o segredo no lugar: a próxima requisição com o segredo velho recebe 401 nao_autenticado, indistinguível de um segredo desconhecido.
- Revogar tem o mesmo efeito imediato. O que a chave já gravou na trilha permanece — a auditoria não some com a credencial.