Authentication & keys
Secret keys, test and live, and how to keep them safe.
Every request carries a secret key in the Authorization header:
Authorization: Bearer mwg_sk_live_...Creating a key
Owners and admins create keys in Mawgood › Settings › Developers. You can create keys during a
trial, but calls return 402 plan_required until the workspace subscribes to a paid plan.
- The full key is shown once, when you create it. Mawgood keeps only a hash, so a lost key can't be shown again: create a new one and revoke the old.
- Give each system its own key ("Order system", "Zapier"), so you can revoke one without stopping the others.
- A key belongs to the workspace, not to the person who created it.
- Rotate issues a new key with the same settings; the old one keeps working for 7 days.
Scopes
Each key has the scopes you pick when you create it (the first four by default: everything the Quickstart uses):
| Scope | Allows |
|---|---|
campaigns:send | POST /campaigns, POST /campaigns/{id}/cancel. |
campaigns:read | GET /campaigns/{id}, GET /campaigns/{id}/recipients. |
templates:read | GET /templates. |
numbers:read | GET /numbers. |
webhooks:manage | GET /webhooks/deliveries. |
GET /me works with any key.
Test and live keys
| Prefix | Use |
|---|---|
mwg_sk_live_ | Production. Sends real WhatsApp messages and charges credits. |
mwg_sk_test_ | Development. POST /campaigns runs every check a live key gets (split_required, not_ready…), then answers 403 test_key_cannot_send. Nothing is written. |
Reads and cancel work the same with both. GET /me tells you who a key is:
{
"workspace": { "id": "ws_2Hd8Qp", "name": "Aura Store" },
"key": {
"name": "Order system",
"prefix": "mwg_sk_live_7Lm3",
"kind": "secret",
"mode": "live",
"scopes": ["campaigns:send", "campaigns:read"]
}
}Keeping keys safe
- Keep keys on your server, in an environment variable or a secrets manager. Never put one in a website, a mobile app, a public repository or a support message.
- If a key may have leaked, revoke it in Settings › Developers at once. Revoked keys fail with
invalid_api_key. - Anyone with a key can send in your name. Treat it like your WhatsApp number's password.
- Try it in the API reference sends your key from this browser, straight to the API. Use a
test key (
mwg_sk_test_) there: it reads and checks everything but never sends. Only these docs may call the API from a browser; your own website can't (keep the key on your server).
Errors
| HTTP | code | Meaning |
|---|---|---|
| 401 | invalid_api_key | Missing, malformed, revoked, expired or unknown key. |
| 402 | plan_required | The workspace isn't on a paid plan yet. |
| 403 | insufficient_scope | The key lacks the scope (details.missing). |
| 403 | publishable_key_not_allowed | A publishable key (mwg_pk_…) on this API. |
| 403 | workspace_unavailable | The workspace is suspended or being closed. |
| 429 | rate_limited | Over 600 requests a minute with this key. |
See Statuses & errors for every error.