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_2tQfTk9bJtq1Vj8x4nKxqL2g

Um prefixo só: zpk_. Não existe distinção zpk_live_ / zpk_test_ nem ambiente de sandbox — revisões anteriores desta página descreviam os dois; nenhum foi implementado. Toda chave é uma chave de produção.
A cauda são 24 caracteres base64 url-safe (18 bytes aleatórios, 144 bits de entropia), então a chave inteira tem 28 caracteres. Os primeiros 12 — ex.: zpk_2tQfTk9b — são o prefix da chave, que é o que o dashboard e o GET /v1/api-keys mostram, e é seguro logar. As chaves são guardadas como digest HMAC-SHA256 sob um pepper do servidor; o texto puro é mostrado exatamente uma vez na criação.

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).

Atalho: POST /v1/channels com "issue_scoped_key": true cria o canal e a chave presa a ele numa chamada só, devolvendo scoped_key.secret uma única vez.

Escopos

scopes restringe o quê uma chave pode fazer; channel_id restringe onde. Os dois são aplicados. O vocabulário é <recurso>.<read|write> — read cobre GET, write cobre todo o resto — mais * (tudo) e <recurso>.*.

Recursos: channels, messages, media, chats, contacts, groups, communities, newsletters, labels, blacklist, stories, calls, presences, profile, settings, business, webhooks, keys, events, limits, metrics.

Uma chave só-de-envio para um canal — o formato que a maioria das integrações quer:

{
  "name": "notifier",
  "channel_id": "8d653c66-e4ff-43ee-97da-3de5ad5680d4",
  "scopes": ["messages.write", "messages.read", "channels.read"]
}

Uma chamada fora da concessão recebe 403 insufficient_scope, com details.required e details.granted para a diferença ficar visível.

Um array scopes vazio significa SEM RESTRIÇÃO, não "sem acesso". Chaves emitidas antes da aplicação de escopos carregam [], então vazio é tratado como escopo de conta inteira — restringir teria revogado toda chave existente. Sua chave só é restrita quando você passa explicitamente um array scopes não-vazio na emissão.

Header de autenticação

Authorization: Bearer zpk_2tQfTk9bJtq1Vj8x4nKxqL2g

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/0f2c5ad1-8b47-4e93-a5d2-6c81e04fb7a9" \
  -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.