API keys
Create an API key scoped to one organization so your own code can call the gateway.
The dashboard signs people in with a session cookie. Your own code can't use a cookie, so it needs a credential it can send on every request: an API key (a long secret string that identifies the caller). You create keys in the dashboard, and the gateway checks the key on each call.
Create a key
- Open API keys in the dashboard sidebar.
- Select New key.
- Give it a Name, such as "Production server". The name is how you tell keys apart and revoke the right one later.
- Tick the Permissions the key needs (see Permissions below).
- Select Create key.
The Save your API key dialog shows the full key once. Copy it then. You cannot read it again. If you lose it, revoke the key and make a new one. The dialog also shows your gateway's API endpoint and a sample request that uses the new key.
The list shows each key's prefix, permissions, when it was created, and when it was last used.
Keys start with the prefix wa_.
Use a key
Send the key on each request, either as a Bearer token in the Authorization
header or in the x-api-key header. Both work:
curl https://your-gateway/api/v1/sessions \
-H "Authorization: Bearer wa_..."
# or
curl https://your-gateway/api/v1/sessions \
-H "x-api-key: wa_..."The gateway's endpoints accept either an API key (for your code) or a user token (for the dashboard). You don't need different URLs for the two.
Each key belongs to one organization
A key belongs to exactly one organization — the one that was active when you created it. It can only touch that org's sessions, messages, webhooks, and events.
There is no account-wide key. To work across several organizations, create a separate key in each one. This matches how the dashboard treats people: a credential only ever sees the resources of the org it belongs to.
Permissions
A key carries a set of permissions. The gateway checks them on every action and rejects anything the key isn't allowed to do.
| Permission | What it allows |
|---|---|
read | List and read sessions, chats, contacts, and messages. |
send | Send messages and message actions (react, edit, revoke, forward). |
manage | Create and change sessions and webhooks. |
events | Connect to the realtime WebSocket to receive events. |
Give each key only the permissions it needs. A key that only pushes notifications
needs send, not manage.
Anyone who has the key can act as that organization until you revoke it. Keep keys out of source control and out of client-side code, and revoke a key the moment you think it might be exposed. Revoking takes effect right away — apps using that key stop working.
Revoke a key
On the API keys page, find the key by its name, select Revoke, and confirm with Revoke key. The key stops working immediately. Anything still using it will start getting rejected, so swap in a new key first if the old one is in use.