Docs / Authentication

API keys

One key identifies one organisation, carries a set of scopes, and can be pinned to particular numbers and particular source addresses. Keys are stored hashed and shown once.

Sending the key

Bearer is the documented form. The header alternative exists because a fair number of gateways and low-code tools already spend the Authorization header on something else — both are equivalent.

shell

# Preferred
curl "$WAVESENDA_URL/sessions/" -H "Authorization: Bearer ws_live_..."

# Equivalent
curl "$WAVESENDA_URL/sessions/" -H "X-API-Key: ws_live_..."

A key is not a session token: there is nothing to refresh and no expiry unless you set one. The console’s own login uses short-lived JWTs on a separate scheme, which is why a console token will not authenticate a /v1/ call.

Environments

Prefix	Behaviour
`ws_live_`	Sends over your connected numbers. Messages reach real phones.
`ws_test_`	Routes every send to a mock session that acknowledges and emits webhooks without touching WhatsApp. Safe in CI.

A test key is the right way to build an integration before a real number is ever linked, and the right way to keep a test suite from messaging a colleague at 3am.

Scopes

Read and write are split per resource because the destructive operations here are genuinely destructive — deleting a session logs a real phone number out of WhatsApp, and re-linking it needs physical access to the handset.

Scope	Grants
`messages:read`	Read messages and conversations
`messages:send`	Send, react, edit, revoke, set presence
`sessions:read`	List sessions and read health
`sessions:write`	Create, connect, log out and delete numbers
`contacts:read`	Read contacts and opt-out state
`contacts:write`	Create contacts, import, opt in and out
`groups:read`	Read groups and participants
`groups:write`	Create groups, change participants and settings
`webhooks:write`	Manage endpoints and replay deliveries
`agents:write`	Manage AI agents, knowledge and tools
`campaigns:write`	Manage campaigns and sequences
`analytics:read`	Read reporting

The default set

A key created without an explicit choice gets everything except sessions:write, webhooks:write, agents:write and campaigns:write — the shape most integrations need, without handing out the ability to log a company’s number out of WhatsApp by accident.

Narrowing a key further

Control	What it does
Session scope	Binds the key to specific numbers. An agency can give each client a key that cannot see the others. Unset means every session in the organisation.
IP allow-list	Rejects the key from anywhere else. Worth setting for a key that only ever calls from your own servers.
Rate limit	A per-key ceiling below the account default of 600 requests a minute.
Expiry	A hard cut-off date, after which the key stops working.

Rotation

The secret is displayed once, at creation, and only its hash is kept. That is deliberate: a key we could show you again is a key an attacker with console access could also read. If a key leaks, issue a replacement, deploy it, then revoke the old one — revocation takes effect on the next request.

Keys belong on servers

Anything a browser or a mobile app can read, a user can read. A leaked live key can send from your numbers, and the damage is measured in spam reports against a number you cannot easily replace. Proxy through your own backend.