Authentication and scopes

Every request carries an API key in the Authorization header:

HTTP

Authorization: Bearer wm_live_5f0c…

Keys are created in the dashboard (Integrations → Webhooks & API, administrators only), with a name, scopes and an optional expiry date. They belong to the organization: whatever you do with them is recorded in the activity log under the user who created the key, together with the key's identifier.

Scopes

A key can only access routes that declare one of its scopes. The rest of the API (users, billing, keys, WhatsApp) is for dashboard sessions only and responds 403 API_KEY_NOT_ALLOWED_HERE.

Scope	Unlocks
`contacts:read`	List and view contacts, their timeline and their notes
`contacts:write`	Create, edit, delete, bulk update, identities and notes
`campaigns:read`	List and view campaigns, recipients and estimated cost
`campaigns:write`	Create, add audience, send, pause and resume
`conversations:read`	List and view conversations
`automations:read`	List automations and their runs
`reports:read`	All reports
`messages:send`	Reserved for the next version (sending messages in conversations)

Request only the scopes each integration needs: one key for your website with contacts:write, another for your reporting dashboard with reports:read.

Authentication responses

Code	`code`	What happened
401	`API_KEY_INVALID`	The key doesn't exist, is mistyped or was revoked
401	`API_KEY_EXPIRED`	The key has expired: create another one
403	`API_KEY_SCOPE_MISSING`	The route requires a scope the key doesn't have
403	`API_KEY_NOT_ALLOWED_HERE`	The route is not open to API keys
429	`API_KEY_RATE_LIMITED`	More than 600 requests in one minute with that key

Best practices

Store the key in your secrets manager or in your server's environment variables; never in the browser or in a mobile app.
One key per integration: that way revoking one doesn't stop the others.
Set an expiry date on keys used for testing and by third-party vendors.
Rotate keys when the person or company using them changes.