# Autenticação

Fonte: https://apiwpp.com/docs/autenticacao
Seção: Começando
Atualizado em: 2026-09-29

Como a chave de API é enviada, o que os escopos permitem, o que cada erro de autenticação quer dizer e como criar, rotacionar e revogar chaves.

Toda operação da API, com uma exceção, se autentica com uma **chave de API**. A chave pertence a um projeto e carrega uma lista de **escopos**: o que ela pode fazer. Não existe login, token de sessão nem troca de credenciais por token: a mesma chave vai em toda requisição.

A exceção é o [download de mídia](https://apiwpp.com/docs/api/midia/baixar-midia), que usa a URL assinada que chega no evento `message.incoming` e não recebe chave.

## A chave de API

Uma chave tem este formato:

**Formato da chave**

```text
wag_live_<prefixo>_<segredo>
wag_live_k3x9p2ab_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8
```

- O **prefixo** tem 8 letras minúsculas e dígitos. Ele identifica a chave nas listagens (`prefix` e `maskedKey`, como `wag_live_k3x9p2ab_…`) e não é secreto.
- O **segredo** tem 43 caracteres (32 bytes aleatórios em base64url).
- A chave inteira é mostrada **uma única vez**, na resposta que a cria ou rotaciona. A apiwpp guarda só um hash dela, então não há como mostrá-la de novo: se ela se perder, crie outra.
- Cada chave vale para **um projeto**. Ela alcança só esse projeto e as conexões dele; para outro projeto, use outra chave.
- A chave pode ter uma data de expiração (`expiresAt`) ou valer até ser revogada.

No painel, crie as chaves dentro do projeto, em **API keys**. Donos e administradores da organização criam, rotacionam e revogam chaves; membros só as veem.

## Envie a chave em toda requisição

A chave vai num destes dois cabeçalhos, à sua escolha:

**Cabeçalhos aceitos**

```http
Authorization: Bearer wag_live_k3x9p2ab_…
X-Api-Key: wag_live_k3x9p2ab_…
```

Os dois são equivalentes. Se a requisição trouxer os dois com chaves diferentes, ela é recusada com `401`. O endereço base da API é `https://api.apiwpp.com`.

**cURL**

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

**Node.js**

```js
const res = await fetch('https://api.apiwpp.com/me', {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
console.log(await res.json())
```

**PHP**

```php
$ch = curl_init('https://api.apiwpp.com/me');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($body, true));
```

**Python**

```python
import os
import requests

res = requests.get(
    "https://api.apiwpp.com/me",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
print(res.json())
```

## Confira a chave com GET /me

[`GET /me`](https://apiwpp.com/docs/api/conta/quem-esta-chamando) responde com quem está chamando: a organização, os escopos que a chave tem, o projeto a que ela está vinculada (`tenantIds`) e quando ela expira. Ele exige o escopo `connections:read`.

Resposta `200`

```json
{
  "kind": "apiKey",
  "user": null,
  "organization": { "id": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d", "name": "Acme", "slug": "acme" },
  "role": null,
  "scopes": ["connections:read", "messages:send"],
  "tenantIds": ["3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61"],
  "apiKey": { "id": "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b", "expiresAt": null }
}
```

É a forma mais simples de validar uma chave recém-configurada e de descobrir o `id` do projeto dela.

## Escopos

Cada operação da referência mostra o escopo de que precisa. Uma chave pode ter estes nove:

| Escopo | O que permite |
| --- | --- |
| `connections:read` | Ler projetos, conexões, status, filas, grupos, proxy, IP dedicado, templates e `GET /me` |
| `connections:write` | Criar, parear, desconectar, reconectar, fazer logout e excluir conexões; definir e remover o proxy; desativar o projeto. Também é o escopo que **recebe o QR code** |
| `messages:send` | Enviar mensagens e reações, cancelar envios na fila, verificar números e perfis, editar, apagar, marcar como lidas e mostrar presença |
| `templates:write` | Criar, atualizar e excluir templates |
| `webhooks:write` | Mudar as configurações de webhook do projeto, testar o endpoint e reenviar entregas |
| `logs:read` | Ler os registros de mensagens e de entregas de webhook |
| `usage:read` | Ler o uso do projeto e os totais diários |
| `keys:read` | Listar as chaves do projeto (nunca as chaves em si) |
| `keys:write` | Criar, rotacionar e revogar chaves do projeto |

Dê a cada sistema só os escopos de que ele precisa. Um painel de monitoramento, por exemplo, fica bem com `connections:read`: ele vê o `status` das conexões, mas não recebe o QR code, que conecta um número. A lista de operações por escopo está em [Escopos](https://apiwpp.com/docs/referencia/escopos).

> **Uma chave nunca cria outra mais poderosa**
>
> Com `keys:write`, uma chave só concede escopos que ela mesma tem, e só revoga ou rotaciona chaves cujos escopos ela tem. Uma chave que expira só cria chaves que expiram até a mesma data. Pedir mais do que isso responde `403`.

## Quando a autenticação falha

Decida pelo status HTTP, não pelo texto do erro. O corpo é sempre `{ "error": "…" }`.

| Status | Quando | O que fazer |
| --- | --- | --- |
| `401` | A chave está ausente, não existe, foi revogada ou expirou, ou o projeto dela está desativado. O corpo é `{ "error": "Unauthorized" }` | Confira a chave e o cabeçalho; não repita a mesma chave |
| `403` | A chave é válida, mas não tem o escopo da operação. A mensagem cita o escopo: `This credential lacks the messages:send scope` | Crie uma chave com o escopo que falta |
| `404` | O recurso não existe **ou pertence a outro projeto**. As duas situações respondem igual, para que ninguém descubra se um recurso de outra pessoa existe | Confira o `id` e o projeto da chave |
| `429` | Falhas de autenticação demais deste IP, ou requisições demais deste IP | Espere os segundos de `Retry-After` |

Cada chave errada enviada de um mesmo IP conta: depois de **20 falhas de autenticação em 5 minutos**, as próximas requisições com chave errada desse IP recebem `429` com `Retry-After` e `{ "error": "Too many failed authentication attempts" }` até a janela terminar. Uma requisição com a chave certa nunca é barrada por esse limite; ela continua sujeita ao limite geral de **600 requisições por minuto por IP**. Os dois números são os padrões da plataforma; veja [Limites](https://apiwpp.com/docs/referencia/limites).

## Criar, rotacionar e revogar chaves

Além do painel, uma chave com `keys:write` gerencia as chaves do próprio projeto pela API.

### Criar

[`POST /tenants/{id}/api-keys`](https://apiwpp.com/docs/api/chaves-de-api/criar-chave) recebe um `name` (1 a 100 caracteres), os `scopes` (pelo menos um) e, se quiser, um `expiresAt` no futuro. A resposta `201` traz a chave em `key`, pela única vez.

**Criar uma chave**

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

Resposta `201`

```json
{
  "id": "7a1c3e5f-2b4d-4f6a-8c0e-1d3f5a7b9c2e",
  "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-29T12:00:00.000Z",
  "lastUsedAt": null,
  "expiresAt": null,
  "revokedAt": null,
  "rotatedAt": null,
  "key": "wag_live_q7m4w1zc_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8"
}
```

Um projeto tem no máximo **50 chaves ativas**; a 51ª responde `409`, assim como criar uma chave num projeto desativado.

### Rotacionar

[`POST /tenants/{id}/api-keys/{keyId}/rotate`](https://apiwpp.com/docs/api/chaves-de-api/rotacionar-chave) cria uma chave nova com o nome, os escopos e a expiração da antiga, e mantém a antiga funcionando por `overlapSeconds`, para você trocar a chave sem interromper nada. O padrão é 24 horas (`86400`), o máximo é 7 dias (`604800`) e `0` revoga a antiga na hora.

**Rotacionar com 1 hora de sobreposição**

```bash
curl -s -X POST https://api.apiwpp.com/tenants/$TENANT_ID/api-keys/$KEY_ID/rotate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overlapSeconds": 3600}'
```

A resposta `201` traz `apiKey` (a nova, com `key` visível só agora) e `previous` (a antiga, com `rotatedAt` e o novo `expiresAt`). Uma chave é rotacionada uma vez só: rotacionar de novo a mesma chave, uma chave revogada ou uma chave expirada responde `409`.

### Revogar

[`DELETE /tenants/{id}/api-keys/{keyId}`](https://apiwpp.com/docs/api/chaves-de-api/revogar-chave) desliga a chave na hora. Ela continua na [listagem](https://apiwpp.com/docs/api/chaves-de-api/listar-chaves) com `status: revoked`, para auditoria. A listagem mostra todas as chaves ativas e as 100 revogadas ou expiradas mais recentes, com `lastUsedAt` (atualizado no máximo uma vez por minuto), nunca a chave em si.

> **Guarde a chave num cofre de segredos**
>
> Nunca coloque a chave no código, no repositório ou no navegador: ela dá acesso a enviar mensagens pelos seus números. Guarde-a num cofre de segredos ou numa variável de ambiente do servidor, use uma chave por sistema e revogue na hora qualquer chave que possa ter vazado.

## Próximos passos

- [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero): QR code, código de pareamento e os status da conexão.
- [Erros](https://apiwpp.com/docs/guias/erros): o que cada status HTTP significa e quando tentar de novo.
- [Chaves de API](https://apiwpp.com/docs/api/chaves-de-api/listar-chaves): as quatro operações de chave na referência.
