Chaves de API

O WhatIsUp.dev usa tokens bearer para autenticação na API. Cadastre-se, pegue uma chave no dashboard, coloque num header Authorization: Bearer …, pronto.

Ciclo de vida

As chaves são provisionadas automaticamente no cadastro; a rotação é emitir-depois-revogar.

Formato

As chaves se parecem com:

zpk_live_abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGH

zpk_live_ e zpk_test_ são os dois prefixos. São uma dica para o tooling; o gateway não restringe funcionalidades por prefixo.
A cauda são 32 bytes aleatórios URL-safe. As chaves são armazenadas com hash — o texto puro é mostrado para você exatamente uma vez, na criação. A gente nunca registra e não consegue mostrar de novo.

Escopo

Toda chave pertence a um cliente. Por padrão, uma chave pode agir sobre todo canal daquele cliente. Você também pode emitir uma chave com escopo de canal passando channel_id na criação — essa chave só consegue enviar mensagens de / ler entregas daquele único canal. Chaves de canal são úteis para apps de menor privilégio (ex.: uma ferramenta de marketing que só deve postar de um número).

Header de autenticação

Authorization: Bearer zpk_live_…

Não coloque a chave em query strings de URL — elas vazam para logs, headers de referrer e screenshots de CI.

Rotação

Emita uma nova chave, troque seu env, depois revogue a antiga. Não há endpoint separado de "rotacionar sem downtime" porque emitir-depois-revogar já cobre isso: as duas chaves são válidas na janela de sobreposição.

Emita uma nova chave (a chave existente autentica esta chamada):

curl -sX POST "$WHATISUP_API/v1/api-keys" \
  -H "Authorization: Bearer $WHATISUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"app-2026-q2"}'

Depois seu app lê a nova chave do env e faz redeploy. Com a nova chave em uso, revogue a antiga:

curl -sX DELETE "$WHATISUP_API/v1/api-keys/key_01J..." \
  -H "Authorization: Bearer $WHATISUP_API_KEY"

Limites de requisições

Toda requisição autenticada cobra 1 token de um bucket por cliente. Os padrões te dão um burst de 60 requisições e ~1 requisição / segundo sustentado — suficiente para a maioria das cargas.

A resposta inclui:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47

…e na rejeição:

HTTP/1.1 429 Too Many Requests
Retry-After: 4
{"error": {"code": "rate_limited", "message": "…"}}

Se você bate no limite com frequência, fale com a gente antes de fragmentar chaves de API — preferimos aumentar o seu bucket.

Log de auditoria

Toda emissão, toda revogação, toda falha de autenticação deixa uma entrada no log de auditoria. Veja na aba Atividade do dashboard. As entradas de auditoria sobrevivem ao recurso que referenciam, então o rastro vive mais que o que ele aponta.