API Keys

API keys authenticate every request to the REST API. A workspace can have up to 20 active keys, and each key has its own name, scopes, rate limit and optional restrictions.

Creating a key

1. In the dashboard, open Settings → Developers → API keys. Only owners and admins can manage keys.
2. Choose Create key and fill in:
   • Name — a label such as "ERP sync" or "Analytics read-only".
   • Mode — live or test (see below).
   • Scopes — at least one scope from the list below. Pick only what the integration needs.
   • Allowed IPs (optional) — up to 20 IP addresses or CIDR blocks (for example 203.0.113.0/24). When set, the key only works from those addresses; anywhere else returns 403 with the code ip_not_allowed.
   • Expiry date (optional) — after this date the key stops working.
   • Rate limit — requests per second and burst. The default is 10 per second with a burst of 50; the maximum is 50 per second with a burst of 200.
3. Confirm your password (or re-authenticate, if your account signs in without a password). Creating and rotating keys is a sensitive action and always asks for this step.
4. Copy the secret immediately. The full key (for example wk_live_...) is shown once, in that response only. Mulabbe stores only a one-way hash plus the first 12 characters, so it can never show the secret again.

Key format and modes

A key looks like wk_live_ or wk_test_ followed by at least 32 random URL-safe characters.

• Live keys (wk_live_...) act on real data and real channels.
• Test keys (wk_test_...) can read everything, but write operations are limited to conversations on sandbox channels. A write against a live channel fails with 403 and the code test_key_live_channel. Use a test key while you develop, then switch to a live key.

Scopes

Each route requires exactly one scope. A request with a key that lacks the required scope returns 403 with the code missing_scope and a required_scope field naming it.

Rotating a key

Rotation replaces the secret while keeping the key's identity, scopes, restrictions and rate limit. From Settings → Developers → API keys, choose Rotate on a key and pick a grace period between 0 and 72 hours:

• During the grace period both the old and the new secret work, so you can deploy the new secret without downtime.
• A grace period of 0 cuts the old secret off immediately.
• The new secret is shown once, exactly like at creation.

Rotate on a schedule (for example every 90 days) and immediately if you suspect a leak.

Revoking a key

Revoking a key stops it — and any old secret still inside a rotation grace period — on the next request. Revocation cannot be undone; create a new key if you need access again.

Monitoring

The key list in the dashboard shows each key's prefix (for example wk_live_AbCd), its scopes, when it expires and when and from which IP address it was last used. Use this to find keys that are no longer needed.

Security recommendations

• Never put an API key in client-side code, a mobile app, or a public repository. Keys belong on your server, in an environment variable or a secret manager.
• Scope keys minimally. A reporting job needs orders:read, not products:write. Use one key per integration so you can revoke one without breaking the others.
• Restrict by IP when your servers have stable addresses.
• Set an expiry date on keys created for temporary work.
• Prefer test keys during development, so a mistake cannot write to live customer conversations.
• Watch the "last used" information and revoke keys you no longer recognise.