Authentication
Bearer API keys, key rotation, platform (app) keys and the tenant header.
Every /v1 call carries an API key as a Bearer token:
curl https://api.whabuzz.com/v1/tenant -H "Authorization: Bearer wb_live_7Hq2Xc9LmN4pR8sT1vW6yZ0aB3dE5fG7hJ2kM4nP6"Only GET /v1/health is public.
#Keys
- Format:
wb_live_orwb_test_followed by 40 characters. The environment is a label that lets you keep staging credentials apart. Both hit the real WhatsApp Cloud API. - The full key is returned once, when you create or rotate it. WhaBuzz stores only a hash and the first 12 characters (
prefix) for display. - Tenant owners and admins manage keys; agents cannot.
#Rotate
POST /v1/api-keys/{key_id}/rotate creates a new key with the same name and environment and lets the old one keep working for 24 hours, so you can deploy the new key without downtime.
#Revoke
DELETE /v1/api-keys/{key_id} revokes immediately. Keys are cached briefly for speed, so a revoked key usually stops working within 30 seconds, and in the worst case within about 90 seconds.
#Platform keys
If you run a platform that serves many businesses (an app in WhaBuzz terms), a WhaBuzz administrator issues you an app key. It is not tied to one business. On tenant routes, say which business you mean with a header:
curl https://api.whabuzz.com/v1/numbers \
-H "Authorization: Bearer $WHABUZZ_APP_KEY" \
-H "X-WhaBuzz-Tenant: a578246e-b97f-48e6-ae42-939ec3ccf917"WhaBuzz checks that the tenant belongs to your app. Missing header on a tenant route is 400 invalid_request. The /v1/tenants routes (create and list your businesses) need no header. See Tenants.
#Account status gates
A key works only while its tenant allows it:
| Tenant status | /v1 behaviour |
|---|---|
pending_approval, rejected | 403 tenant_not_approved on everything except GET /v1/tenant |
active | allowed |
suspended | 403 tenant_suspended on everything except GET /v1/tenant, GET /v1/billing* and GET /v1/events*. Inbound messages are still forwarded to your endpoints. |
#Response headers
Every response carries X-WhaBuzz-Request-Id (quote it to support), X-WhaBuzz-Processing-Ms and Server-Timing: wb;dur=<our ms>, meta;dur=<Meta's ms>. Send responses also carry X-WhaBuzz-Event-Id. See Rate limits and pacing for how to read the timing split.
This page as Markdown: /authentication.md. All docs in one file: /llms-full.txt.