Technical reference

Authentication: API keys and headers

Page updated: 2026-04-03

Summary

WAPing uses server-to-server API keys with Authorization: Bearer. This is not Meta’s OAuth flow for WhatsApp Business Cloud API.

Canonical reference: Hostnames, path prefixes, JSON field names, and changelog are maintained on docs.waping.app. Examples below are illustrative — align your integration with the live OpenAPI/reference there.

Connection model: WAPing links WhatsApp through a QR session (similar in concept to WhatsApp Web). This is not Meta’s WhatsApp Business Cloud API product, and you do not complete Meta BSP / Cloud API onboarding inside WAPing for this path.

Key definitions

Term	Definition
API key	Opaque secret issued by WAPing; presented as Bearer token. Not a Meta app secret or Cloud API token.
401 vs 403	401 = credential problem. 403 = credential OK but plan or permission denies the action (e.g. Free tier has no API).
Workspace	Tenant boundary: keys and devices belong to one workspace; keys do not cross workspaces.

Purpose

Define how the API validates callers and how to distinguish auth failures from session or validation errors.

Best for

Server-side workers and backends holding keys in a secret store.
Rotating keys without re-scanning QR (session and key lifecycle are separate).

Not for

Embedding API keys in mobile apps or public frontends.
Expecting Meta OAuth or Cloud API long-lived tokens—WAPing uses its own keys only.

Mechanism

Send the key on every request. Keys are created and rotated in the dashboard; they are independent of WhatsApp QR linkage (you can rotate keys without re-scanning QR).

Required headers (typical)

Authorization: Bearer {WAPING_API_KEY{'}'}
Content-Type: application/json
Accept: application/json

Request example

GET (illustrative)

GET /v1/devices HTTP/1.1
Host: api.waping.app
Authorization: Bearer {WAPING_API_KEY{'}'}
Accept: application/json

Response example (success)

200 OK

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    { "id": "dev_123", "status": "connected" }
  ]
}

Errors

HTTP	Code (example)	Meaning	Retry?
401	UNAUTHORIZED	Missing, malformed, or revoked API key.	No — fix credentials.
403	FORBIDDEN	Key valid but plan lacks API access (e.g. Free tier) or insufficient scope.	No — upgrade or scope.
403	FORBIDDEN	Key cannot access resource (workspace / resource ACL).	No — fix permissions.

Operational notes

Rotate keys on a schedule; keep two valid keys during rotation if you run high-availability workers.
Redact Authorization in logs and APM.
Use separate keys per environment (staging vs production) where possible.

Plan entitlements (API access)

REST API keys and webhooks follow published plan rows below. HTTP 429 throttling is separate from “can I call the API at all”—see Rate limits.

Plan	WhatsApp devices (linked)	Outbound messages / month	REST API & webhooks
Free	1	500	Not included
Starter	1	3,000	Included
Growth	5	30,000	Included
Pro	15	300,000	Included
Enterprise	50	1,000,000	Included

Aligned with plan cards on /pricing (reviewed 2026-04-03).

Caveats

A valid key does not guarantee sends: the linked WhatsApp session must still be connected (see QR session lifecycle).