Alcance Docs

Escopos de API Key

A WebApiAlcance autentica chamadas do MCP por API Key dedicada, mas cada chave carrega um conjunto restrito de escopos — declarações explícitas de quais recursos e ações ela pode acessar. Esse é o princípio do menor privilégio aplicado na camada de borda: a chave consegue exatamente o que o caso de uso exige, nada além. Se a chave vazar, o blast radius fica contido ao escopo emitido, e não à API inteira.

Convenção recurso:acao

O formato é uniforme: dois identificadores separados por dois-pontos. O lado esquerdo é o recurso (uma entidade de negócio ou módulo da API); o lado direito é a ação permitida (read para leitura; write para mutação).

Exemplos: customers:read permite listar e consultar clientes; lembretes:write permite criar/editar lembretes WhatsApp.

A API Key emitida ao MCP carrega exatamente cinco escopos — um para cada tool da Fase 1 mais o necessário para a Fase 1.1:

  • customers:read — buscar e obter dados de cliente (com PII mascarada por padrão).
  • certidao_negativa:read — listar e baixar certidões (CND, FGTS, SEFAZ).
  • lembretes:read — listar lembretes WhatsApp existentes.
  • lembretes:write — criar lembretes WhatsApp (sempre com dry-run).
  • worker_automation:read — consultar status de tasks Celery.

Qualquer endpoint fora desses escopos retorna 403 Forbidden, mesmo que a URL exista e o restante da requisição esteja válido.

Restrito vs Global

A WebApi suporta um escopo global (*:*) usado apenas em integrações administrativas internas. Para o MCP, ele é proibido.

Nunca use escopo global em produção

Uma API Key global concede acesso irrestrito — incluindo endpoints DELETE, gestão de usuários e purge de filas. Em caso de vazamento via logs, screenshots ou histórico de chat do cliente IA, toda a base de clientes fica exposta. Emita sempre chaves restritas, mesmo em ambientes de homologação.

Como solicitar uma API Key

Não há self-service: chaves são emitidas manualmente pelo TI da Alcance para garantir rastreabilidade.

  1. Envie um e-mail para ti@alcancecontabilidade.com.br com assunto [MCP] Solicitação de API Key — <seu nome>.
  2. Informe o caso de uso (qual cliente IA, qual fluxo operacional).
  3. Liste os escopos mínimos necessários — referencie os 5 acima e justifique cada um.
  4. Indique o ambiente (dev, preview ou production).

Você recebe a chave por canal seguro (1Password ou e-mail criptografado). A chave aparece uma única vez; armazene imediatamente em variável de ambiente da Vercel (WEBAPI_API_KEY) — nunca em código.

Rotação

Toda API Key emitida tem prazo de validade implícito de 90 dias. Antes do vencimento:

  • O TI emite uma chave nova com os mesmos escopos.
  • Você atualiza WEBAPI_API_KEY na Vercel (Production/Preview/Development separadamente).
  • A chave antiga é revogada após confirmação de smoke test do gateway.

Em caso de suspeita de vazamento (commit acidental, log exposto, dispositivo comprometido), rotacione imediatamente — não espere o prazo dos 90 dias.