API keys

Manage → Settings → API keys.

"Credentials for an integration to reach this store through the public API. A key can always 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: "Name the key so you recognise it later." Six months from now wbk_a1b2c3… tells you nothing; "Acme inventory sync" does.

Scopes — split into Content access and Store 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 the key is shown. Store it somewhere safe — if you lose it, revoke this key and create another."

That is 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…), which is enough to tell keys apart and useless as a credential.

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

The key list

The columns are Name, Key (prefix), Scopes, Last used, Status.

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

Revoking

Revoke — "Anything using “{name}” stops 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

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

This is 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 bounded by its creator's role — if their permissions are reduced later, so are the key's."

Permissions are resolved live, per request, never captured at mint time. So a key created by an admin who is later demoted to Viewer loses write access on the next request — no revocation sweep, no bookkeeping on the integration's side.

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.