API keys

Manage → Settings → API keys.

"Credentials an integration uses to reach this store through the public API. A key can only ever do less than the person who created it."

That second sentence is the important rule, and the last section covers it properly.

Minting a key

New key.

Name — required, and the form says why: "Give the key a name so you can recognise it later." Six months from now wbk_a1b2c3… tells you nothing; "Acme stock sync" does.

Scopes — split into Content access and Site access. At least one is required. Pick the least that works: an integration that only reads orders gets orders.read and nothing more.

The secret is shown exactly once

After creating, a dialog appears:

Copy your key now — "This is the only time it will be shown. Store it somewhere safe — if you lose it, revoke this key and create another."

Literally true. The key is stored hashed (SHA-256), so nobody — including the platform's own operators — can read it back. There is no "show again".

The list afterwards only ever shows the prefix (wbk_a1b2c3…), enough to tell keys apart and useless as a credential.

Losing a key means revoke and mint another. Not an inconvenience — the only thing that makes "shown once" mean anything.

The key list

The columns: Name, Key (prefix), Access, Last used, Status.

Last used is the most useful column when tidying up: a key that reads Never after months is almost certainly forgotten, and every forgotten key is an unwatched open door.

Revoking

Revoke — "Anything using “{name}” will stop working immediately. This cannot be undone."

A revoked key stays in the list marked Revoked, so you can still see that it existed and what it could do.

Using a key

The How to use an API key card on the screen walks through four steps, with a curl example and a button into the API console. In short: send the secret in the Authorization header of every request. No session, no cookie, no login.

curl https://api.your-host/api/v1/products \
  -H "Authorization: Bearer wbk_your_secret_here"

A key belongs to exactly one store, which is why there is no store id in the path — no {siteId} anywhere in /api/v1. A key that could be pointed at another store by editing a URL would be a key whose blast radius depends on the caller's honesty. An agency running five stores holds five keys.

A missing scope answers 403 insufficient_scope — not 404, so you can tell "you may not" from "it is not there".

The full detail is in The public API.

Two bounds, not one

What this page exists to say:

Bound 1 — the key's own scopes. What you ticked when you created it.

Bound 2 — the current role of the person who created it. The panel says: "A key is also limited by the role of whoever created it — if that person's access is reduced later, the key's is too."

Permissions are resolved per request, never captured at mint time. A key created by an admin who is later demoted to Viewer loses write access on the next request — no revocation sweep.

Two practical consequences:

• When somebody leaves, demote them or remove them from the site. That narrows every key they ever minted, at once, without hunting for them.
• A key can stop working without you touching it. If an integration suddenly gets 403, check the role of whoever created the key before suspecting the code.

If a key's stored scopes stop validating altogether, the API answers 403 key_unusable — not the caller's fault, and said so. The fix is a new key.

API keys versus app tokens

wbk_ is a key a merchant mints for their own tooling.

wba_ is a token issued to an app when a merchant installs it from the marketplace.

Both work on /api/v1 and behave identically once past the door; they differ in who holds them and how they are issued. See Build an app.