Skip to main content
Every request carries your API key in an apikey request header.
That is the whole scheme. There is no OAuth flow, no token exchange, no expiry to refresh.
It is apikey, not Authorization: Bearer, not X-API-Key, and never a query string parameter. A request without that header comes back 401 missing_api_key.

​
Creating a key

Keys are created in the portal, on the API Keys screen. You cannot create a key using another key — that is deliberate, so a leaked key can never mint replacements that survive you revoking it. When you create one, the full key is shown once:
We store only a hash of your key. Nobody can retrieve the original afterwards — not you, not our support team. Copy it into your secret store immediately. If you lose it, revoke it and create a new one.
After that, the key list shows only a short prefix, the label you gave it, when it was created and when it was last used. That is enough to tell two keys apart without exposing either.

​
Where to keep it

Do

  • Keep it on your server, in an environment variable or secret manager.
  • Give each system its own key, labelled, so you can revoke one without touching the others.
  • Rotate it if it ever appears in a log, a screenshot, a chat message or a git commit.

Do not

  • Put it in a browser, a mobile app, or anything a user can view source on.
  • Put it in a URL or query string — URLs end up in server logs and browser history.
  • Commit it. Check your .env is in .gitignore before the first push.
Anyone holding your key can send WhatsApp messages as you, from your numbers, to anyone. Treat it exactly like a password.

​
One key drives all your numbers

A key identifies your account, not a number. The same key can send from every number on your account — you choose which one per request, with instance_id:
Same key, same header, different number sending. See One key, many numbers. You can still create several keys on one account if you want to — one per application, say — so that revoking a key only affects the system it belongs to. Every key on the account can reach every number on the account; keys are not scoped to individual numbers.

​
Revoking a key

On the API Keys screen, revoke the key you no longer want. Revocation takes effect on the very next request: the key is checked against the database every time it is used, so there is no cache to wait out. A revoked key returns 401 invalid_api_key — exactly the same answer an entirely made-up key gets, so nobody can probe which keys once existed.

​
Rotating without downtime

Because an account can hold several live keys at once, rotation needs no maintenance window:
1

Create the new key

Label it clearly, for example billing-server-2026-08.
2

Deploy it

Update the environment variable and restart. Both keys work at this point.
3

Confirm it is in use

The key list shows last used for each key. Wait until the new key shows recent activity and the old one has gone quiet.
4

Revoke the old key

Now revoke it. If something was still using it, that system starts failing with 401 invalid_api_key — which is exactly the signal you want.

​
What else can block a valid key

A key can be perfectly valid and still be refused, because authentication is only the first gate. In order, a request is checked for: Each is explained on the Errors page.

​
Testing a key

The cheapest way to prove a key works is to list your numbers. It sends nothing and costs nothing:
A 200 means the key is good. A 401 means it is not.