Skip to Content
Developer docsBeta

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):

ScopeAllows
campaigns:sendPOST /campaigns, POST /campaigns/{id}/cancel.
campaigns:readGET /campaigns/{id}, GET /campaigns/{id}/recipients.
templates:readGET /templates.
numbers:readGET /numbers.
webhooks:manageGET /webhooks/deliveries.

GET /me works with any key.

Test and live keys

PrefixUse
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

HTTPcodeMeaning
401invalid_api_keyMissing, malformed, revoked, expired or unknown key.
402plan_requiredThe workspace isn't on a paid plan yet.
403insufficient_scopeThe key lacks the scope (details.missing).
403publishable_key_not_allowedA publishable key (mwg_pk_…) on this API.
403workspace_unavailableThe workspace is suspended or being closed.
429rate_limitedOver 600 requests a minute with this key.

See Statuses & errors for every error.

On this page