Get started

Authentication: API keys, scopes and sessions

Send your API key in the Authorization header as Bearer <key>. A read key can call GET endpoints; a write key can also create, send and change data, except workspace administration, which only works from the app.

How do I send the API key?

Add one header to every request:

Authorization: Bearer pk_live_<48 hex characters>

The word Bearer, followed by one space, is case-sensitive. A header like bearer pk_live_… is not recognised as an API key, and the request fails with 401 and unauthorized.
No other header (such as X-API-Key) is accepted.
Keys are 56 characters long: pk_live_ followed by 48 hexadecimal characters.

What do the scopes allow?

Scope	Allowed methods	Typical use
`read`	`GET` (and `HEAD`)	Dashboards, reporting, syncing conversations into another system.
`write`	All methods an API key may use	Sending messages, starting conversations, marking chats as read, creating and deleting contacts.

A read key that calls any other method gets 403 with API key is read-only. When you create a key, full and full_access are accepted as aliases for write.

What can an API key never do?

An API key acts as an agent of its workspace that can see the whole inbox. It can never administer the workspace. These endpoints return 403 with API keys cannot administer workspaces, whatever the scope, and are labelled Console only in this reference:

Members and invites (adding, changing roles, removing, invites)
Linking or unlinking the number connected by QR code (POST /api/whatsapp/connect and /disconnect)
API keys and outbound webhooks
Cloud API channel settings and the guided Meta signup
Creating, changing and deleting automations, templates and knowledge articles
Assigning conversations (keys get only admins can assign conversations)

Use these from the app while signed in as an owner or admin.

Which workspace does a key act in?

Each key belongs to exactly one workspace and always acts in it. You do not need to send a workspace id. If you send X-Tenant-ID or ?tenant=, it must be the key’s workspace; otherwise the request fails with 403 and API key belongs to a different workspace. See Workspaces.

Which authentication errors can I get?

Status	`error`	Cause
`401`	`invalid or expired API key`	The key is unknown, revoked or older than 365 days.
`401`	`unauthorized`	No `Authorization: Bearer` header and no signed-in session.
`403`	`API key is read-only`	A `read` key used a method other than GET.
`403`	`API keys cannot administer workspaces`	A Console-only endpoint was called with a key.
`403`	`API key belongs to a different workspace`	`X-Tenant-ID` or `?tenant=` names another workspace.
`402`	`subscription required`	Subscriptions are enforced and the workspace has none (`code: "payment_required"`).

How long do keys last?

Keys expire 365 days after creation and cannot be rotated in place. To rotate, create a second key, deploy it, then revoke the old one. Revoking takes effect immediately. See API keys.

How does the web app authenticate?

The app uses a session cookie named whatsappx_session (HttpOnly, SameSite=Lax, valid for 7 days), set when you sign in. Session requests must select a workspace with X-Tenant-ID (or ?tenant=); without one they fail with 400 and workspace required (X-Tenant-ID), and a workspace you are not a member of returns 403 with forbidden.

The sign-in endpoints (/api/auth/register, /login, /logout, /forgot-password, /reset-password, /verify-email, /resend-verification, /google/start, /google/callback and /providers) exist for the app’s own pages and are not part of the integration API. They are rate limited per IP address; see Errors and limits.

Can I call the API from a browser?

The API answers cross-origin requests and allows the Content-Type, Authorization and X-Tenant-ID request headers. Even so, never put an API key in browser or mobile app code, where anyone can read it. Call the API from your server and keep the key in a secret store.