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 tarefas assíncronas.

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

Escopo mínimo

Sempre use escopos restritos

Em caso de vazamento via logs, screenshots ou histórico de chat do cliente IA, o impacto fica limitado aos escopos emitidos. Solicite sempre apenas o escopo mínimo necessário, inclusive em 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 de uso.

Você recebe a chave por canal seguro (cofre de senhas ou e-mail criptografado). A chave aparece uma única vez; armazene imediatamente em um cofre de segredos - 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 a chave no seu cofre de segredos.
  • 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.