API Keys

API keys are the credential your code uses to talk to WhiteBoxXAI. They're individually revocable, and don't expire on a fixed schedule — which makes them the right choice for the SDK, CI/CD pipelines, the MCP server, and anything else running unattended.

Keys look like this:

wbx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create a key

In the dashboard

Go to Settings → API keys (administrators only), create a key, give it a name and optional expiry, and copy it. Non-administrators see who their administrators are instead.

The list shows each key's prefix, expiry and when it was last used, with Revoke.

Via the API

Key creation and revocation are admin-only, because an API key is an organization-wide credential rather than a personal one.

curl -X POST https://api.whiteboxxai.com/api/v1/api-keys \
  -H "Authorization: Bearer $WHITEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline — nightly drift job",
    "scopes": ["read", "write"],
    "expires_in_days": 365
  }'

Field	Notes
name	Required, max 255 characters. Make it descriptive — it's how you'll identify the key later.
scopes	Optional list of labels, e.g. ["read", "write"]. Recorded with the key, but not yet enforced (see below).
expires_in_days	Optional, 1–3650. Omit for a key that never expires.

The 201 response is the only time you see the key material:

{
  "id": "a1b2c3d4-...",
  "name": "CI pipeline — nightly drift job",
  "key_prefix": "wbx_live_a1b2c3d4...",
  "scopes": ["read", "write"],
  "expires_at": "2027-07-29T00:00:00Z",
  "last_used_at": null,
  "revoked_at": null,
  "created_at": "2026-07-29T00:00:00Z",
  "raw_key": "wbx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

raw_key is shown exactly once

Store it immediately in your secrets manager. WhiteBoxXAI keeps only a hash and the prefix — the full key cannot be retrieved again. If you lose it, revoke the key and issue a new one.

Use a key

Send it as a bearer token:

curl https://api.whiteboxxai.com/api/v1/models \
  -H "Authorization: Bearer wbx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

With the Python SDK:

from whiteboxxai import WhiteBoxXAI

client = WhiteBoxXAI(api_key="wbx_live_...")

Or, preferably, from the environment:

export WHITEBOX_API_KEY="wbx_live_..."

import os

client = WhiteBoxXAI(api_key=os.environ["WHITEBOX_API_KEY"])

List keys

GET /api/v1/api-keys

Returns every key in your organization with its metadata — never the key material, only the key_prefix for identification. last_used_at tells you whether a key is still in service, which is what you want before revoking one.

Revoke a key

DELETE /api/v1/api-keys/{key_id}

Returns 204. Revocation is immediate — any process still using that key starts getting 401 on its next request. Revoke a key as soon as you suspect exposure; unlike a password, there's nothing else to rotate.

What a key can do

An API key acts with the permissions of the administrator who created it, inside that administrator's organization. If that person is deactivated, their keys stop working.

Scopes you set when creating a key are recorded with it, but they aren't enforced per request yet, so a key can do anything its creator can. Treat every key as an administrator credential: one key per consumer, expiry dates for temporary access, and revoke anything you don't recognise.

Two things a key can never do:

• Vote on, or finalize, a governance review request. Votes need a person's own session with two-factor authentication and an authenticator code. See Reviews & Decisions.
• Act in another organization. A request for another organization's record returns 404.

Requests made with a key are the ones metered as Governance Events; using the dashboard is not.

API keys vs. login tokens

The Authorization: Bearer header accepts either an API key or a login JWT from POST /api/v1/auth/login. They are not equivalent:

	API key	Login JWT
Lifetime	Until you revoke it (or its optional expiry)	~30 minutes
Permissions	Those of the administrator who created it, in their organization	Those of the signed-in person
Revocable individually	Yes	No — you'd rotate the account's credentials
Good for	SDK, CI/CD, pipelines, MCP server, webhooks	Quick interactive scripts, the dashboard

Use a JWT for a throwaway script if it's convenient. Use an API key for anything that runs without a person watching it — a 30-minute token in a nightly job is a job that fails at minute 31.

Keys and two-factor authentication

Two-factor authentication protects interactive dashboard logins. It does not affect API keys — a key authenticates on its own, with no 2FA challenge. Enabling 2FA won't break your existing integrations, and no code changes are needed.

The practical consequence: an API key is a standalone credential, so treat it with the same care as a password. Keep keys out of source control, out of notebooks you share, and out of log output.

Good practice

• One key per consumer. A separate key for each pipeline, environment, and service means you can revoke one without taking down everything else.
• Name keys after where they run. "CI pipeline — nightly drift job" beats "key 3" when you're deciding six months later whether it's safe to revoke.
• Set an expiry for temporary access. Contractors, spikes, and one-off migrations should get a key with expires_in_days.
• Check last_used_at before revoking. And revoke anything that hasn't been used in a while — an unused key is pure risk.
• Store keys in a secrets manager, not in .env files that get committed. See Secure configuration.

Troubleshooting

401 Unauthorized: Invalid API key

Check that the key hasn't been revoked or expired (GET /api/v1/api-keys shows revoked_at and expires_at), that you copied the whole key, and that your environment variable is actually set in the process making the request.

403 Forbidden on a request that should work

Check whether the administrator who created the key still has the administrator role, and whether the request is one that keys can't make by design, such as voting on a governance review. If you've reached your plan's Governed AI Systems limit, registering a model under a new name also returns 403.

403 when creating a key

Key creation is admin-only. Ask an organization admin to issue it.

Related

• Two-Factor Authentication
• MCP Server — uses an API key via WHITEBOXXAI_MCP_API_KEY.
• SDK Authentication