Manage API tokens
- Version
- 3.x
- Updated
Audience: store admins · Scope: the API Tokens screen · Last reviewed: 2026-08-25
What this does — External software — an import script, a connected shop system, an AI assistant, an integration a developer builds for you — talks to your store through its API, and every one of those callers must present an API token to be let in. The API Tokens screen in the CBX menu is where you create tokens, decide exactly what each one may touch, see when each was last used, and shut one off when it should no longer have access.
What a token may touch: the seven areas
A token does not simply "have access". It has access to areas of your store, and for each area it can either read or read and write. The screen shows this as a grid — one row per area, a read box and a write box:
| Area | What is in it | If a mistake happens here |
|---|---|---|
| catalog | What you sell: products, their pages, questions and answers, product lists, detail texts, examples, rules and price calculations. | Recoverable — a wrong title is a typo someone fixes. |
| store | How you charge and deliver: settings, store details, currencies, tax classes, shipping, payment methods, notifications, countries. | Costly — a wrong tax rate is an invoice that already went out. |
| customers | Your customers and their addresses, reviews and contacts. | Irreversible — personal data, once leaked, stays leaked. |
| orders | Orders, quotes and payments — who bought what. | Irreversible — the same personal data, plus fulfilment. |
| conversations | What visitors said to the AI advisor. | Irreversible — personal data in free text. |
| code | Price calculations written as program code. Ticking this lets the caller put code on your server. | Dangerous — treat it like handing over the keys. |
| system | The installation itself: updates, database housekeeping. | Costly — can stop updates; recoverable from a backup. |
Three things to know about the grid:
- Write includes read. A token that may write the catalog can also read it — you never need both boxes in one row.
- Rows are independent. Ticking orders says nothing about customers. A token that works orders and needs to see who placed them gets both rows ticked.
- Every token can read the store row. That box shows "always" and cannot be unticked: currencies, tax classes and shipping methods are the words everything else is written in, and a token that could not read them could not make sense of a single price. Secrets stored there — payment provider keys, the licence key — are never handed out, whatever the token holds.
Create a token
- Open API Tokens in the CBX menu and click Add.
- Name the token after its holder — "Warehouse import", "Catalog assistant", "Agency staging" — so you can tell later which one to revoke. The name is for you; it grants nothing.
- Choose its scopes. The quickest way is a Start from button above the grid — each one
ticks the boxes for a common job:
- author — build and maintain the catalog.
- fulfilment — work orders, and see the customers they belong to.
- insights — read the catalog and the advisor's conversations, to learn what visitors ask.
- operator — store configuration and system housekeeping; no customer or catalog access.
- everything — every row at write, except code. Then adjust the boxes by hand if the job is different. Grant only what the caller actually needs, and untick anything it does not.
- Code is never part of a Start-from button. Tick it only when you are deliberately allowing someone to put program code on your server, and know who that is.
- Optionally set an expiry date — the token stops working at the start of that day. Leave it empty for a token that never expires.
- Click Save and Close.
The screen now shows the new token once. Copy it immediately and hand it to whoever runs the calling software — it is never shown again, not even to you. The store keeps only a fingerprint, enough to recognise the token when it is presented but not to display it. If a token is lost before it was copied, there is nothing to recover: revoke it and create a new one.
Watch and retire tokens
The list shows every token with its scopes, expiry, creation date and — the column worth checking now and then — Last used. On a store with many tokens, the filter row narrows the list: search by name, or show only tokens carrying a given scope or only revoked ones. A token that has not been used in months probably belongs to something that no longer exists; retire it.
- Revoke — open the token and set Revoked to Yes. The caller is shut out immediately. Revoking is permanent: a revoked token cannot be turned back on, only replaced by a new one. The row stays in the list, so you keep the record of what existed and when it was cut off.
- Remove — deletes the row entirely. The token stops working just the same; you only lose the audit trail. Prefer revoking first and removing revoked leftovers later.
If a token leaks
Treat a token like a password: whoever has it can do whatever its scopes allow. If one ends up in the wrong hands — pasted in a ticket, committed to a code repository — revoke it right away and create a replacement for the legitimate caller. Revocation takes effect on the next request.
Tokens created before the areas existed
Older tokens were made with three broad permissions — read, write, admin. Updating the store translated each of them into the new grid without taking anything away: a former "read" token now reads every area, a former "admin" token writes the store, customers, orders and system rows, and a former "write" token writes the catalog and has the code row ticked, because that is what "write" used to allow. Open each of those tokens once and untick what its holder does not need — the code row first.
Good to know
- Tokens are for software, not people. Staff who work in the admin log in with their own account; a token never grants access to these admin screens.
- The same token works for the store's API and for an AI assistant connected to the store; what it may do is the same in both places.
- Creating a token does not change anything for shoppers — the storefront works entirely without tokens.
- Expiry dates are a good habit for integrations run by outside parties: a token that ends by itself does not rely on anyone remembering to revoke it.
- A developer with command-line access can create tokens there too, with the same areas and the same Start-from names; the result is identical.