Pular para o conteúdo

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.

Ver em Markdown

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:

textFormato da chave
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:

httpCabeçalhos aceitos
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"

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.

200
{
  "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:

EscopoO que permite
connections:readLer projetos, conexões, status, filas, grupos, proxy, IP dedicado, templates e GET /me
connections:writeCriar, 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:sendEnviar mensagens e reações, cancelar envios na fila, verificar números e perfis, editar, apagar, marcar como lidas e mostrar presença
templates:writeCriar, atualizar e excluir templates
webhooks:writeMudar as configurações de webhook do projeto, testar o endpoint e reenviar entregas
logs:readLer os registros de mensagens e de entregas de webhook
usage:readLer o uso do projeto e os totais diários
keys:readListar as chaves do projeto (nunca as chaves em si)
keys:writeCriar, 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": "…" }.

StatusQuandoO que fazer
401A 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
403A chave é válida, mas não tem o escopo da operação. A mensagem cita o escopo: This credential lacks the messages:send scopeCrie uma chave com o escopo que falta
404O 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 existeConfira o id e o projeto da chave
429Falhas de autenticação demais deste IP, ou requisições demais deste IPEspere 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.

bashVer na referência
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": "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.

bashVer na referência
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.
Esta página ajudou? · Atualizado em 29 set 2026