# Escopos

Fonte: https://apiwpp.com/docs/referencia/escopos
Seção: Referência
Atualizado em: 2026-09-29

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:

Resposta `403`

```json
{ "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`](https://apiwpp.com/docs/api/conta/quem-esta-chamando): uma chave sem ele não consegue conferir os próprios escopos.

| Operação | Método e caminho |
| --- | --- |
| [Quem está chamando](https://apiwpp.com/docs/api/conta/quem-esta-chamando) | `GET /me` |
| [Listar projetos](https://apiwpp.com/docs/api/projetos/listar-projetos) | `GET /tenants` |
| [Consultar projeto](https://apiwpp.com/docs/api/projetos/consultar-projeto) | `GET /tenants/{id}` |
| [Conexões do projeto](https://apiwpp.com/docs/api/projetos/listar-conexoes-do-projeto) | `GET /tenants/{id}/connections` |
| [Consultar conexão](https://apiwpp.com/docs/api/projetos/consultar-conexao) | `GET /tenants/{id}/connections/{connId}` |
| [Histórico de heartbeats](https://apiwpp.com/docs/api/projetos/historico-de-heartbeats) | `GET /tenants/{id}/connections/{connId}/heartbeats` |
| [QR code como imagem](https://apiwpp.com/docs/api/projetos/qr-code-como-imagem) | `GET /tenants/{id}/connections/{connId}/qr` |
| [Listar conexões](https://apiwpp.com/docs/api/conexoes/listar-conexoes) | `GET /connections` |
| [QR code e status](https://apiwpp.com/docs/api/conexoes/qr-code-e-status) | `GET /connections/{id}/qr` |
| [Fila do número](https://apiwpp.com/docs/api/mensagens/fila-do-numero) | `GET /connections/{id}/queue` |
| [Listar grupos](https://apiwpp.com/docs/api/conexoes/listar-grupos) | `GET /connections/{id}/groups` |
| [Consultar proxy](https://apiwpp.com/docs/api/conexoes/consultar-proxy) | `GET /connections/{id}/proxy` |
| [IP dedicado](https://apiwpp.com/docs/api/conexoes/ip-dedicado) | `GET /connections/{id}/dedicated-ip` |
| [Listar templates](https://apiwpp.com/docs/api/templates/listar-templates) | `GET /connections/{id}/templates` |
| [Consultar template](https://apiwpp.com/docs/api/templates/consultar-template) | `GET /connections/{id}/templates/{name}` |

> **O QR code pede connections:write**
>
> As duas operações de QR code exigem só `connections:read`, mas escanear o QR code liga um número à conexão, como o código de pareamento. Por isso, o campo `qr` só vem preenchido para uma chave que também tem `connections:write`; com só `connections:read`, ele vem `null`, e o `status` da conexão continua visível. Um painel que só acompanha o status não precisa de `connections:write`.

## `connections:write`

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

| Operação | Método e caminho |
| --- | --- |
| [Desativar projeto](https://apiwpp.com/docs/api/projetos/desativar-projeto) | `DELETE /tenants/{id}` |
| [Criar conexão no projeto](https://apiwpp.com/docs/api/projetos/criar-conexao-no-projeto) | `POST /tenants/{id}/connections` |
| [Excluir conexão](https://apiwpp.com/docs/api/projetos/excluir-conexao) | `DELETE /tenants/{id}/connections/{connId}` |
| [Desconectar conexão](https://apiwpp.com/docs/api/projetos/desconectar-conexao-do-projeto) | `POST /tenants/{id}/connections/{connId}/disconnect` |
| [Reconectar conexão](https://apiwpp.com/docs/api/projetos/reconectar-conexao) | `POST /tenants/{id}/connections/{connId}/connect` |
| [Criar conexão](https://apiwpp.com/docs/api/conexoes/criar-conexao) | `POST /connections` |
| [Código de pareamento](https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento) | `POST /connections/{id}/pairing-code` |
| [Desconectar](https://apiwpp.com/docs/api/conexoes/desconectar) | `POST /connections/{id}/disconnect` |
| [Sair do WhatsApp](https://apiwpp.com/docs/api/conexoes/sair-do-whatsapp) | `POST /connections/{id}/logout` |
| [Definir proxy](https://apiwpp.com/docs/api/conexoes/definir-proxy) | `PUT /connections/{id}/proxy` |
| [Remover proxy](https://apiwpp.com/docs/api/conexoes/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](https://apiwpp.com/docs/guias/projetos-e-conexoes).

## `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](https://apiwpp.com/docs/api/mensagens/enviar-mensagem) | `POST /connections/{id}/send` |
| [Cancelar da fila](https://apiwpp.com/docs/api/mensagens/cancelar-mensagem-na-fila) | `DELETE /connections/{id}/queue/{jobId}` |
| [Verificar números](https://apiwpp.com/docs/api/contatos/verificar-numeros) | `POST /connections/{id}/contacts/check` |
| [Perfil do contato](https://apiwpp.com/docs/api/contatos/perfil-do-contato) | `GET /connections/{id}/profile/{phone}` |
| [Reagir](https://apiwpp.com/docs/api/mensagens/reagir) | `POST /connections/{id}/react` |
| [Editar mensagem](https://apiwpp.com/docs/api/mensagens/editar-mensagem) | `POST /connections/{id}/messages/{messageId}/edit` |
| [Apagar mensagem](https://apiwpp.com/docs/api/mensagens/apagar-mensagem) | `DELETE /connections/{id}/messages/{messageId}` |
| [Marcar como lidas](https://apiwpp.com/docs/api/mensagens/marcar-como-lidas) | `POST /connections/{id}/read` |
| [Mostrar presença](https://apiwpp.com/docs/api/mensagens/mostrar-presenca) | `POST /connections/{id}/presence` |

> **Operações PRO**
>
> Editar, apagar, marcar como lidas e mostrar presença exigem, além de `messages:send`, um plano com operações de mensagem. Sem ele, a resposta é `403` com `code: "plan_feature_required"`, mesmo que a chave tenha o escopo. Veja [Operações de mensagem](https://apiwpp.com/docs/guias/operacoes-de-mensagem).

## `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](https://apiwpp.com/docs/api/templates/criar-template) | `POST /connections/{id}/templates` |
| [Atualizar template](https://apiwpp.com/docs/api/templates/atualizar-template) | `PUT /connections/{id}/templates/{name}` |
| [Excluir template](https://apiwpp.com/docs/api/templates/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](https://apiwpp.com/docs/api/projetos/testar-webhook) | `POST /tenants/webhook-test` |
| [Atualizar projeto](https://apiwpp.com/docs/api/projetos/atualizar-projeto) | `PATCH /tenants/{id}` |
| [Reenviar entregas mortas](https://apiwpp.com/docs/api/registros/reenviar-entregas-mortas) | `POST /webhooks/deliveries/resend-dead` |
| [Reenviar entrega](https://apiwpp.com/docs/api/registros/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](https://apiwpp.com/docs/guias/webhooks-e-assinatura).

## `logs:read`

Os registros de mensagens e de entregas de webhook.

| Operação | Método e caminho |
| --- | --- |
| [Listar mensagens](https://apiwpp.com/docs/api/registros/listar-mensagens) | `GET /messages` |
| [Entregas de webhook](https://apiwpp.com/docs/api/registros/listar-entregas-de-webhook) | `GET /webhooks/deliveries` |

## `usage:read`

O consumo frente ao plano.

| Operação | Método e caminho |
| --- | --- |
| [Uso do projeto](https://apiwpp.com/docs/api/uso/uso-do-projeto) | `GET /tenants/{id}/usage` |
| [Uso diário](https://apiwpp.com/docs/api/uso/uso-diario) | `GET /usage/daily` |

Veja [Uso e registros](https://apiwpp.com/docs/guias/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](https://apiwpp.com/docs/api/chaves-de-api/listar-chaves) | `GET /tenants/{id}/api-keys` |

## `keys:write`

Gerenciar as chaves do projeto.

| Operação | Método e caminho |
| --- | --- |
| [Criar chave](https://apiwpp.com/docs/api/chaves-de-api/criar-chave) | `POST /tenants/{id}/api-keys` |
| [Revogar chave](https://apiwpp.com/docs/api/chaves-de-api/revogar-chave) | `DELETE /tenants/{id}/api-keys/{keyId}` |
| [Rotacionar chave](https://apiwpp.com/docs/api/chaves-de-api/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 `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](https://apiwpp.com/docs/api/midia/baixar-midia) (`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`](https://apiwpp.com/docs/webhooks/message-incoming) e expira. Uma URL alterada, de outro arquivo ou vencida responde `404`.

| Operação | Método e caminho |
| --- | --- |
| [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia) | `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).

```bash
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"]}'
```

```js
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.
```

Resposta `201`

```json
{
  "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`.

**Confira os escopos**

```bash
curl -s https://api.apiwpp.com/me -H "Authorization: Bearer $API_KEY"
```

> **Uma chave por sistema**
>
> Crie uma chave para cada sistema que integra, com só os escopos dele: o CRM que envia mensagens fica com `messages:send` e `connections:read`, o serviço que recebe webhooks e reenvia entregas fica com `webhooks:write` e `logs:read`. Se uma vazar, você revoga só ela, e o estrago possível fica limitado aos escopos que ela tinha.

## 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

- [Autenticação](https://apiwpp.com/docs/autenticacao): o formato da chave, os cabeçalhos, a rotação e a revogação.
- [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro): o `401`, o `403` e o `404` em detalhe.
- [Visão geral da API](https://apiwpp.com/docs/api): todas as operações por grupo.
