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.
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:
{ "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
| Escopo | O que libera |
|---|---|
connections:read | Consultar 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:write | Criar, 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:send | Enviar e cancelar mensagens, reagir, verificar números, consultar perfis e as operações de mensagem PRO. |
templates:write | Criar, atualizar e excluir templates. |
webhooks:write | Configurar o webhook do projeto, testar o endpoint e reenviar entregas. |
logs:read | Ler o registro de mensagens e o de entregas de webhook. |
usage:read | Ler o uso do projeto e os totais diários. |
keys:read | Listar as chaves do projeto (nunca a chave em si). |
keys:write | Criar, 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ção | Método e caminho |
|---|---|
| Quem está chamando | GET /me |
| Listar projetos | GET /tenants |
| Consultar projeto | GET /tenants/{id} |
| Conexões do projeto | GET /tenants/{id}/connections |
| Consultar conexão | GET /tenants/{id}/connections/{connId} |
| Histórico de heartbeats | GET /tenants/{id}/connections/{connId}/heartbeats |
| QR code como imagem | GET /tenants/{id}/connections/{connId}/qr |
| Listar conexões | GET /connections |
| QR code e status | GET /connections/{id}/qr |
| Fila do número | GET /connections/{id}/queue |
| Listar grupos | GET /connections/{id}/groups |
| Consultar proxy | GET /connections/{id}/proxy |
| IP dedicado | GET /connections/{id}/dedicated-ip |
| Listar templates | GET /connections/{id}/templates |
| Consultar template | GET /connections/{id}/templates/{name} |
connections:write
Tudo o que muda uma conexão ou o número ligado a ela.
| Operação | Método e caminho |
|---|---|
| Desativar projeto | DELETE /tenants/{id} |
| Criar conexão no projeto | POST /tenants/{id}/connections |
| Excluir conexão | DELETE /tenants/{id}/connections/{connId} |
| Desconectar conexão | POST /tenants/{id}/connections/{connId}/disconnect |
| Reconectar conexão | POST /tenants/{id}/connections/{connId}/connect |
| Criar conexão | POST /connections |
| Código de pareamento | POST /connections/{id}/pairing-code |
| Desconectar | POST /connections/{id}/disconnect |
| Sair do WhatsApp | POST /connections/{id}/logout |
| Definir proxy | PUT /connections/{id}/proxy |
| Remover proxy | DELETE /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ção | Método e caminho |
|---|---|
| Enviar mensagem | POST /connections/{id}/send |
| Cancelar da fila | DELETE /connections/{id}/queue/{jobId} |
| Verificar números | POST /connections/{id}/contacts/check |
| Perfil do contato | GET /connections/{id}/profile/{phone} |
| Reagir | POST /connections/{id}/react |
| Editar mensagem | POST /connections/{id}/messages/{messageId}/edit |
| Apagar mensagem | DELETE /connections/{id}/messages/{messageId} |
| Marcar como lidas | POST /connections/{id}/read |
| Mostrar presença | POST /connections/{id}/presence |
templates:write
Escrever templates. Ler templates (listar e consultar) pede só connections:read, e enviar um template pede messages:send.
| Operação | Método e caminho |
|---|---|
| Criar template | POST /connections/{id}/templates |
| Atualizar template | PUT /connections/{id}/templates/{name} |
| Excluir template | DELETE /connections/{id}/templates/{name} |
webhooks:write
Configurar e operar a entrega de webhooks do projeto.
| Operação | Método e caminho |
|---|---|
| Testar webhook | POST /tenants/webhook-test |
| Atualizar projeto | PATCH /tenants/{id} |
| Reenviar entregas mortas | POST /webhooks/deliveries/resend-dead |
| Reenviar entrega | POST /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ção | Método e caminho |
|---|---|
| Listar mensagens | GET /messages |
| Entregas de webhook | GET /webhooks/deliveries |
usage:read
O consumo frente ao plano.
| Operação | Método e caminho |
|---|---|
| Uso do projeto | GET /tenants/{id}/usage |
| Uso diário | GET /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ção | Método e caminho |
|---|---|
| Listar chaves | GET /tenants/{id}/api-keys |
keys:write
Gerenciar as chaves do projeto.
| Operação | Método e caminho |
|---|---|
| Criar chave | POST /tenants/{id}/api-keys |
| Revogar chave | DELETE /tenants/{id}/api-keys/{keyId} |
| Rotacionar chave | POST /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
403com 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 (
403caso contrário). - Uma chave que expira só cria chaves que expiram até a data dela (
403informa 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ção | Método e caminho |
|---|---|
| Baixar mídia | GET /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"]}'const response = await fetch(`https://api.apiwpp.com/tenants/${process.env.TENANT_ID}/api-keys`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ name: 'CRM produção', scopes: ['connections:read', 'messages:send'] }),
})
if (!response.ok) throw new Error(`${response.status}: ${(await response.json()).error}`)
const { key, scopes } = await response.json()
// A chave aparece só nesta resposta: guarde-a no cofre de segredos agora.{
"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.
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, nunca403. - 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:writeeprojects:write, só de proprietários e administradores conectados ao painel: pedir uma delas ao criar uma chave responde400, e uma que já estivesse gravada numa chave é ignorada.
Próximos passos
- Autenticação: o formato da chave, os cabeçalhos, a rotação e a revogação.
- Códigos de erro: o
401, o403e o404em detalhe. - Visão geral da API: todas as operações por grupo.