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.
- Envie um e-mail para ti@alcancecontabilidade.com.br com assunto
[MCP] Solicitação de API Key - <seu nome>. - Informe o caso de uso (qual cliente IA, qual fluxo operacional).
- Liste os escopos mínimos necessários - referencie os 5 acima e justifique cada um.
- 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.