Pular para o conteúdo

Escopos

Os nove escopos que uma chave de API pode ter, o que cada um libera e todas as operações que exigem cada um deles.

Ver em Markdown

Cada operação da API exige um escopo, e cada chave de API tem a lista de escopos escolhida quando ela foi criada. Uma chave sem o escopo da operação recebe 403, com o escopo que falta na mensagem:

403
{ "error": "This credential lacks the messages:send scope" }

Os escopos são independentes: connections:write não inclui connections:read, e messages:send não inclui nenhum outro. Dê a cada chave exatamente os escopos das operações que o sistema dela chama, nem mais, nem menos. As tabelas abaixo saem da especificação OpenAPI: cada operação aparece uma única vez, no escopo que ela exige.

Resumo

EscopoO que libera
connections:readConsultar a própria chave, os projetos, as conexões, o status e o QR code (sem o conteúdo), a fila, os grupos, o proxy, o IP dedicado e os templates.
connections:writeCriar, parear, desconectar, reconectar, sair e excluir conexões; definir e remover o proxy; desativar o projeto. Também revela o conteúdo do QR code.
messages:sendEnviar e cancelar mensagens, reagir, verificar números, consultar perfis e as operações de mensagem PRO.
templates:writeCriar, atualizar e excluir templates.
webhooks:writeConfigurar o webhook do projeto, testar o endpoint e reenviar entregas.
logs:readLer o registro de mensagens e o de entregas de webhook.
usage:readLer o uso do projeto e os totais diários.
keys:readListar as chaves do projeto (nunca a chave em si).
keys:writeCriar, revogar e rotacionar chaves, só com escopos que a chave chamadora tem.

connections:read

Leitura de tudo o que descreve o projeto e as conexões. É também o escopo de GET /me: uma chave sem ele não consegue conferir os próprios escopos.

OperaçãoMétodo e caminho
Quem está chamandoGET /me
Listar projetosGET /tenants
Consultar projetoGET /tenants/{id}
Conexões do projetoGET /tenants/{id}/connections
Consultar conexãoGET /tenants/{id}/connections/{connId}
Histórico de heartbeatsGET /tenants/{id}/connections/{connId}/heartbeats
QR code como imagemGET /tenants/{id}/connections/{connId}/qr
Listar conexõesGET /connections
QR code e statusGET /connections/{id}/qr
Fila do númeroGET /connections/{id}/queue
Listar gruposGET /connections/{id}/groups
Consultar proxyGET /connections/{id}/proxy
IP dedicadoGET /connections/{id}/dedicated-ip
Listar templatesGET /connections/{id}/templates
Consultar templateGET /connections/{id}/templates/{name}

connections:write

Tudo o que muda uma conexão ou o número ligado a ela.

OperaçãoMétodo e caminho
Desativar projetoDELETE /tenants/{id}
Criar conexão no projetoPOST /tenants/{id}/connections
Excluir conexãoDELETE /tenants/{id}/connections/{connId}
Desconectar conexãoPOST /tenants/{id}/connections/{connId}/disconnect
Reconectar conexãoPOST /tenants/{id}/connections/{connId}/connect
Criar conexãoPOST /connections
Código de pareamentoPOST /connections/{id}/pairing-code
DesconectarPOST /connections/{id}/disconnect
Sair do WhatsAppPOST /connections/{id}/logout
Definir proxyPUT /connections/{id}/proxy
Remover proxyDELETE /connections/{id}/proxy

Desativar o projeto fecha as conexões dele, e um projeto inativo deixa de receber webhooks. Veja Projetos e conexões.

messages:send

Tudo o que fala com um contato ou consulta o WhatsApp em nome do número.

OperaçãoMétodo e caminho
Enviar mensagemPOST /connections/{id}/send
Cancelar da filaDELETE /connections/{id}/queue/{jobId}
Verificar númerosPOST /connections/{id}/contacts/check
Perfil do contatoGET /connections/{id}/profile/{phone}
ReagirPOST /connections/{id}/react
Editar mensagemPOST /connections/{id}/messages/{messageId}/edit
Apagar mensagemDELETE /connections/{id}/messages/{messageId}
Marcar como lidasPOST /connections/{id}/read
Mostrar presençaPOST /connections/{id}/presence

templates:write

Escrever templates. Ler templates (listar e consultar) pede só connections:read, e enviar um template pede messages:send.

OperaçãoMétodo e caminho
Criar templatePOST /connections/{id}/templates
Atualizar templatePUT /connections/{id}/templates/{name}
Excluir templateDELETE /connections/{id}/templates/{name}

webhooks:write

Configurar e operar a entrega de webhooks do projeto.

OperaçãoMétodo e caminho
Testar webhookPOST /tenants/webhook-test
Atualizar projetoPATCH /tenants/{id}
Reenviar entregas mortasPOST /webhooks/deliveries/resend-dead
Reenviar entregaPOST /webhooks/deliveries/{id}/resend

Com PATCH /tenants/{id}, a chave muda a configuração de webhook do projeto: webhookSecret, webhookToken, webhookHeaders, webhookBaseUrl e emitOutgoing. O nome, o plano, o estado ativo e os limites maxPerMinute, maxPerHour e maxPerDay são só da plataforma: pedir qualquer um deles responde 403, seja qual for o escopo. Ler as entregas pede logs:read. Veja Webhooks e assinatura.

logs:read

Os registros de mensagens e de entregas de webhook.

OperaçãoMétodo e caminho
Listar mensagensGET /messages
Entregas de webhookGET /webhooks/deliveries

usage:read

O consumo frente ao plano.

OperaçãoMétodo e caminho
Uso do projetoGET /tenants/{id}/usage
Uso diárioGET /usage/daily

Veja Uso e registros.

keys:read

Ver as chaves do projeto: nome, prefixo, chave mascarada (wag_live_<prefixo>_…), escopos, estado e datas. A chave em si nunca volta: só o hash SHA-256 dela fica guardado.

OperaçãoMétodo e caminho
Listar chavesGET /tenants/{id}/api-keys

keys:write

Gerenciar as chaves do projeto.

OperaçãoMétodo e caminho
Criar chavePOST /tenants/{id}/api-keys
Revogar chaveDELETE /tenants/{id}/api-keys/{keyId}
Rotacionar chavePOST /tenants/{id}/api-keys/{keyId}/rotate

Uma chave nunca gerencia uma chave mais poderosa do que ela mesma:

  • Ela só cria chaves com escopos que ela tem. Pedir outro responde 403 com a lista dos que faltam: An API key cannot grant scopes it does not hold: templates:write.
  • Ela só revoga ou rotaciona chaves cujos escopos ela tem (403 caso contrário).
  • Uma chave que expira só cria chaves que expiram até a data dela (403 informa a data máxima) e não rotaciona uma chave que duraria mais do que ela.
  • A rotação cria uma chave com o mesmo nome, os mesmos escopos e a mesma validade da antiga.

Por isso, a chave que gerencia as outras costuma ter todos os escopos, e as chaves dos sistemas, só os que cada um usa.

Sem escopo: download de mídia

Baixar mídia (GET /media/{connectionId}/{fileName}) é a única operação sem chave de API. A credencial é a própria URL: ela vem assinada (exp e sig) no campo media.url do evento message.incoming e expira. Uma URL alterada, de outro arquivo ou vencida responde 404.

OperaçãoMétodo e caminho
Baixar mídiaGET /media/{connectionId}/{fileName}

Criar uma chave com os escopos certos

No painel, a chave é criada no projeto, com os escopos marcados na hora. Pela API, uma chave com keys:write cria outra no mesmo projeto. scopes é obrigatório, tem pelo menos um item, sem repetições, e só aceita os nove escopos desta página; expiresAt é opcional (ausente ou null: não expira).

curl -s -X POST https://api.apiwpp.com/tenants/$TENANT_ID/api-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CRM produção", "scopes": ["connections:read", "messages:send"]}'
201
{
  "id": "6f9a2b3c-4d5e-4f6a-9b0c-1d2e3f4a5b6c",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
  "name": "CRM produção",
  "prefix": "q7m4w1zc",
  "maskedKey": "wag_live_q7m4w1zc_…",
  "scopes": ["connections:read", "messages:send"],
  "status": "active",
  "createdBy": "apiKey:5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "createdAt": "2026-09-24T12:00:00.000Z",
  "lastUsedAt": null,
  "expiresAt": null,
  "revokedAt": null,
  "rotatedAt": null,
  "key": "wag_live_q7m4w1zc_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8"
}

Para conferir o que uma chave pode fazer, chame GET /me com ela (precisa de connections:read): a resposta traz os scopes e os projetos que ela alcança em tenantIds.

bashConfira os escopos
curl -s https://api.apiwpp.com/me -H "Authorization: Bearer $API_KEY"

Chaves, projetos e o painel

  • Cada chave pertence a um projeto e só alcança os recursos dele. Um recurso de outro projeto responde 404, como um que não existe, nunca 403.
  • No painel, proprietários e administradores da organização criam, rotacionam e revogam chaves; membros veem as chaves, mas não as gerenciam.
  • Algumas ações do painel, como mudar o plano, pagar e criar projetos, dependem de permissões que nenhuma chave de API recebe, e não têm operação na API. Essas permissões são billing:write e projects:write, só de proprietários e administradores conectados ao painel: pedir uma delas ao criar uma chave responde 400, e uma que já estivesse gravada numa chave é ignorada.

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026