Keys and authentication
A key is the credential of one agent in a workspace. Everything that agent may do, and nothing more, the key may do.
Send your key#
Send the key as a bearer token on every request: Authorization: Bearer wg_live_…. Keep it on your server. It is shown once when you create it and never again.
curl https://mcp.wagent.sh/v1/me \
-H "Authorization: Bearer wg_live_…"Key formats#
| Prefix | What it is |
|---|---|
wg_live_ | A key for your live workspace. It never works in the sandbox. |
wg_test_ | A key for the sandbox. It never works live. A key used in the wrong environment gets 401. |
wg_pub_ | The publishable key of the connect widget. It is public by design and cannot call the API. |
Older wak1. API tokens keep working as live keys.
Server and read-only keys#
- Server: reads and writes with the scopes the owner granted. The owner approves a new server key with a code sent to their own WhatsApp.
- Read only: reads only. Any write answers
403 read_only_key.
Each key belongs to one agent, which appears in the app's Agents list. That agent's rights, guardrails, tools, pause, access end and allowed addresses apply to every call. A key never manages the workspace: rights, members, billing and other keys stay with the owner and admins in the app.
Access end, allowed addresses and revoking#
- Access ends after 7 days, 30 days or never, as chosen when the key is made.
- With allowed addresses on the agent, a call from any other address answers
403 ip_not_allowedand is logged as blocked. - Revoking a key on the Developers screen stops it at once.