Authentication

Every request carries an account key in the Authorization header. Keys are machine credentials: use them from your server only.

Authorization: Bearer wsl_live_Ab12Cd34…

Creating and storing keys

• Create keys in Settings → API keys. Only the account owner can see or manage keys; team members can’t, and keys can’t be created during a support session.
• A key is wsl_live_ followed by 40 random characters. It is shown once. Mursilat stores only an HMAC of it with a secret pepper kept outside the database, so a lost key can’t be recovered — rotate it.
• Up to 20 active keys per account. Each key shows its prefix, last 4 characters and when / from which IP it was last used.
• Optional expiry: 1–730 days (API_KEY_EXPIRED afterwards).
• Your plan must include API access (403 API_ACCESS_NOT_IN_PLAN).

• GETWho am I (connectivity test)/v2/me

Scopes

Keys are deny-by-default: a request needs the scope written on its endpoint page, otherwise 403 SCOPE_REQUIRED (the answer names the missing scope). Give each system only what it needs.

Number restriction

When you create a key you choose all numbers or a list. A restricted key sees only its numbers in every list, gets 404 for the others (exactly like an unknown id) and cannot add numbers or manage the account-wide webhook (KEY_NUMBER_RESTRICTED).

IP allowlist

Optionally list the IPv4 / IPv6 addresses or CIDR ranges of your servers. The check runs right after the key lookup, before anything else (403 IP_NOT_ALLOWED). GET /v2/me returns clientIp — the address Mursilat sees — to help you fill it in.

Rotation and revocation

• Rotate issues a new key (shown once). The old one stops at once, or after a grace period of up to 24 hours (graceMinutes ≤ 1440) so you can deploy without downtime.
• Revoke stops a key immediately.
• Every create / change / rotate / revoke is written to the audit log — never the key itself.

Legacy number key (x-api-key)

The per-number x-api-key of v1 still works on v2 for the message endpoints of its own number (send, upload, message status, reactions, edit, delete). Anywhere else it answers 401 ACCOUNT_KEY_REQUIRED. Endpoint pages show “number key ok” where it is accepted.

Protection against guessing

20 unknown or malformed keys from one IP within 10 minutes lock that IP for 15 minutes (429 AUTH_TOO_MANY_FAILURES), even for valid keys. Revoked or expired keys never count toward the lock, so an old deployment can’t lock out the new key.