API Keys

Which key do you want?

Default to workspace keys. Use master only when you actually need cross-workspace access, and prefer revoking + reissuing over passing one around.

Getting a key

1. Sign in at app.whitelabel.dev
2. Switch to the workspace you want the key scoped to
3. Open /account/api-keys
4. Click Create key, give it a name
5. Copy the full whlk_... token immediately — it's shown once

Forgot to copy? You'll need to revoke the key and create a new one. Whitelabel can't retrieve the full token after creation (we only store an HMAC).

Using a key

Put the key in the Authorization header on every request:

curl https://app.whitelabel.dev/api/v1/workspaces \
  -H "Authorization: Bearer whlk_..."

Common patterns

From Node.js:

const res = await fetch('https://app.whitelabel.dev/api/v1/workspaces', {
  headers: { 'Authorization': `Bearer ${process.env.WHITELABEL_API_KEY}` }
})
const json = await res.json()

From Python:

import os, httpx
r = httpx.get(
    'https://app.whitelabel.dev/api/v1/workspaces',
    headers={'Authorization': f'Bearer {os.environ["WHITELABEL_API_KEY"]}'}
)

Scope rules

• Workspace-scoped (whlk_). Each key only sees the workspace it was created under. To work across workspaces, create multiple keys OR use a master key.
• Master / account-wide (whlmk_). Bound to your user, not a workspace. Grants access to every workspace you're a member of — including workspaces you join after the key was created. No scope limits; it can do everything you can do.
• Role-scoped. A workspace key inherits the creator's role at creation time. Master keys inherit role per-workspace at request time.
• Time-bounded (optional). Both kinds can have an expiry. Expired keys 401 immediately.

Rotating + revoking

If a key leaks: revoke it at /account/api-keys. Revocation is immediate — within a second the key starts returning 401.

For a rotating workflow:

1. Create a new key with a new name (e.g. prod-2026-q3)
2. Update your application to use the new key
3. Confirm everything works
4. Revoke the old key

Errors