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 the dashboard and go to your organization's API Keys page.
- Click New key.
- Give it a name — this is how you tell keys apart and revoke the right one later.
- Tick the permissions the key needs (see Permissions below).
- Click Create key.
The full secret is shown once, right after you create it. Copy it then. You can't read it again — if you lose it, revoke the key and make a new one.
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 and click Revoke. 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.