Autenticação
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, 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:
wag_live_<prefixo>_<segredo>
wag_live_k3x9p2ab_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8- O prefixo tem 8 letras minúsculas e dígitos. Ele identifica a chave nas listagens (
prefixemaskedKey, comowag_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:
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 -s https://api.apiwpp.com/me \
-H "Authorization: Bearer $API_KEY"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())$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));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 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.
{
"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.
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.
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 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.
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"]}'{
"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 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.
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} desliga a chave na hora. Ela continua na listagem 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.
Próximos passos
- Parear um número: QR code, código de pareamento e os status da conexão.
- Erros: o que cada status HTTP significa e quando tentar de novo.
- Chaves de API: as quatro operações de chave na referência.