Escopos
O que cada escopo da chave de API da conta libera, operação por operação.
Escopo é uma permissão nomeada. A chave de API da conta carrega um conjunto de escopos escolhido na criação, e cada operação da API exige um escopo. Se a chave não tem o escopo da operação, a resposta é 403 com code: ACCOUNT_API_SCOPE_REQUIRED, mesmo com a chave válida.
A regra de ouro: dê o menor conjunto que resolve a integração.
Catálogo
| Escopo | Libera | Operações |
|---|---|---|
instances:read | Ler as conexões da conta, o estado e os recursos de cada uma | GET /api/wa/instances, GET /api/wa/status/{instanceId}, GET /api/nexus/instances/{publicInstanceId}/capabilities |
messages:send | Enviar mensagens por qualquer conexão da conta | POST /api/send |
Com a chave da conta, GET /api/wa/instances devolve só a identificação e a prontidão de cada linha (publicInstanceId, instanceId, displayName, phoneAlias, transportType, deviceType, status, readiness, phone, lastConnectedAt). Configuração, proxy e vínculos do CRM são do painel, com sessão.
Escopo novo entra sempre junto com as operações que ele libera e com uma entrada no changelog. A referência da API é a fonte final: a lista de segurança de cada operação mostra o escopo exigido na entrada AccountApiKey.
Combinações comuns
| Integração | Escopos |
|---|---|
| Painel externo que só mostra o estado das linhas | instances:read |
| Automação que dispara mensagens a partir de um evento do seu sistema | instances:read, messages:send |
Robô que envia por uma linha fixa e já conhece o instanceId | messages:send |
Mesmo quando a integração "só envia", vale incluir instances:read se ela precisa descobrir o instanceId ou conferir se a linha está conectada antes de enviar.
O que escopo não controla
- Qual conta: a chave pertence a uma conta e só enxerga ela. Não existe escopo que atravesse contas.
- Ações administrativas: criar chip, configurar webhook e gerenciar chaves exigem sessão do painel, com qualquer escopo.
- Credenciais de outro tipo: a chave da linha tem alcance fixo e não usa este catálogo. A credencial de afiliação tem um catálogo próprio, listado na referência da API.
Mudar os escopos de uma chave
Não se edita a chave. Crie outra com o conjunto certo, troque na integração e revogue a antiga. O motivo está em Chave de API da conta.
Seu próximo passo está na Central de Ajuda Nexus.