Escopos de API Key

Toda API Key emitida pela WebApiAlcance carrega uma lista explícita de escopos no formato recurso:acao — por exemplo, customers:read ou certidao_negativa:write. Esse modelo segue o princípio do menor privilégio: cada chave recebe apenas o conjunto mínimo de permissões necessárias para sua tarefa, reduzindo o impacto de um eventual vazamento.

A WebApi também suporta escopos atrelados a usuários humanos (via JWT), mas esta página foca em API Keys, que são o caso de uso dominante em integrações.

Como funciona

O middleware FastAPI da WebApi (scope_required) deriva o escopo necessário a partir da rota e do método HTTP da requisição:

Recurso = primeiro segmento após /api/v1/, com hifens convertidos em underscore. Exemplo: /api/v1/certidao-negativa/... → certidao_negativa.
Ação = read para métodos GET/HEAD/OPTIONS; write para POST/PUT/PATCH/DELETE.

Antes de aceitar a requisição, o middleware extrai o token do header Authorization: Bearer, identifica os escopos associados à API Key e verifica se o escopo derivado consta na lista. Sem o escopo, retorna 403 Forbidden com mensagem "Escopo necessario: <recurso>:<acao>".

Há também o escopo wildcard *:*, concedido apenas a usuários role=admin e a API Keys explicitamente marcadas como escopo global. Esta flag exige permissão de administrador para ser ativada.

Catálogo de escopos

A tabela abaixo lista os escopos principais da WebApiAlcance. O catálogo completo, sempre atualizado conforme novas rotas são adicionadas, está disponível via endpoint GET /api/v1/scopes/.

Escopo	O que permite
`customers:read`	Listar e consultar clientes (`GET /api/v1/customers/`)
`customers:write`	Criar, atualizar e remover clientes
`certidao_negativa:read`	Listar certidões e baixar PDFs
`certidao_negativa:write`	Solicitar nova certidão e disparar workers
`lembretes:read`	Consultar lembretes / notificações agendadas
`lembretes:write`	Criar, atualizar e remover lembretes
`worker_automation:read`	Consultar status de jobs Celery e filas
`worker_automation:write`	Disparar e cancelar workers de automação
`api_keys:read`	Listar API Keys e seus escopos (e ver o catálogo de escopos)
`api_keys:write`	Criar, atualizar e revogar API Keys
`scopes:read`	Consultar associações de escopos a usuários e chaves

Endpoint catálogo

O catálogo completo e canônico é exposto em GET /api/v1/scopes/ (lista plana) e GET /api/v1/scopes/available (agrupado por tag OpenAPI). Ambos exigem o escopo api_keys:read. Verifique com TI Alcance se há escopos adicionais não listados acima — o catálogo é regenerado a cada deploy.

Solicitando uma API Key

A emissão de API Keys é administrada pelo TI Alcance. O fluxo padrão:

Abra um chamado descrevendo o caso de uso da integração — qual sistema vai consumir, com que frequência e quais dados precisa acessar.
O TI Alcance avalia a solicitação e define a lista mínima de escopos necessária. Por exemplo: um job de relatório lê clientes e lembretes → customers:read + lembretes:read.
A chave é criada via POST /api/v1/api-keys/, atrelada a um usuário emissor e a uma data de expiração (recomendado: 90 dias).
A chave em texto plano é entregue uma única vez ao solicitante por canal seguro (cofre interno, não e-mail).
O solicitante armazena a chave em variável de ambiente — nunca em código-fonte.

Para revogar, basta desativar a chave via PUT /api/v1/api-keys/{id} com ativa: false ou deletar com DELETE /api/v1/api-keys/{id}. A invalidação propaga em até 30 segundos (TTL do cache de escopos).

Escopo restrito vs global

API Keys podem ser criadas com a flag escopo_global: true, que substitui a lista de escopos pelo wildcard *:* — efetivamente concedendo acesso a toda a WebApi, incluindo endpoints administrativos.

Evite escopo global

Chaves com escopo_global: true violam o princípio do menor privilégio e amplificam drasticamente o impacto de qualquer vazamento — uma única chave global comprometida expõe todos os dados e operações da WebApi, incluindo gestão de usuários e outras API Keys.

Por isso a WebApi restringe a criação dessa flag: apenas usuários com role=admin podem emitir ou promover uma chave a global. Para integrações comuns, sempre prefira escopo restrito com a lista mínima necessária. Use global apenas em scripts internos de manutenção pontual, executados localmente, e descarte a chave após o uso.

A política interna da Alcance é clara: o gateway MCP usa API Key restrita, nunca global. O conjunto de escopos do MCP é revisado a cada nova tool adicionada — se uma tool nova precisa de lembretes:write, esse escopo é adicionado à chave; nenhum escopo extra "por garantia".