Escopos

Os escopos limitam o que sua chave pode fazer. O princípio é: peça o mínimo necessário pra reduzir blast radius em caso de vazamento.

Tabela de escopos

Escopo	Métodos	Recursos
documents:read	GET	/documents, /documents/{id}, /documents/{id}/audit-trail, /documents/{id}/download
documents:write	POST, PUT, DELETE	/documents, /documents/{id}/send, /documents/{id}/cancel, /documents/{id}/tags
documents:create	POST	Somente POST /documents (subset de write)
templates:read	GET	/templates, /templates/{id}
templates:write	POST, PUT, DELETE	/templates, /templates/{id}
webhooks:manage	*	/webhooks (CRUD + rotate)
signers:manage	POST, DELETE	/documents/{id}/signers
reports:read	GET	/reports/*

Como funciona na prática

A cada request, o middleware verifica:

1. Header X-Api-Key traz uma chave válida? → autenticado
2. O recurso/método requer algum escopo? → busca na chave
3. A chave tem o escopo? → autoriza
4. Se não tem → 403 Forbidden com requiredScope no body

{
  "title": "Forbidden",
  "status": 403,
  "detail": "A chave de API não possui o escopo 'documents:write' necessário para este recurso.",
  "requiredScope": "documents:write"
}

Wildcard *

Algumas chaves (geralmente internas do tenant) podem ter ["*"] — permite qualquer escopo. Evite isso pra integrações externas. Sempre liste explicitamente.

Como pedir mais escopos

Se você precisa de um escopo que sua chave atual não tem, peça ao admin Aceitou do seu cliente:

• Pra alterar a chave existente: ele edita a integração e adiciona o escopo
• Pra criar uma nova chave separada: outro IntegrationClient (útil quando você quer isolar — ex: chave pra escrita vs chave pra reports)