The API uses secret API keys. Each key belongs to one workspace.
Send the keyLink to this section#
Put the key in the Authorization header as a bearer token:
GET /api/v1/workspace HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer tc_live_Xk2…
curl https://tradecatalog.app/api/v1/workspace \
-H "Authorization: Bearer $TRADECATALOG_API_KEY"
Keys always start with tc_live_. There are no test keys: try things out on a workspace with sample data, or read before you write.
Make a keyLink to this section#
Only the workspace owner or an admin can make keys, in Settings → API.
| Setting | What it means |
|---|---|
| Name | Your label, e.g. “Sage stock sync”. Shown in Settings and in the activity log. |
| Read only | GET requests only. |
| Read & write | Also PUT /products, PUT /customers and PATCH /orders/{id}. |
The key is shown once. We store only a SHA-256 hash, so nobody at TradeCatalog can see it again. Settings shows the first few characters (like tc_live_Xk2m…) so you can tell keys apart.
A workspace can have up to 20 live keys. Give each system its own key, so you can revoke one without breaking the others.
Who can have keysLink to this section#
The workspace needs one of these to make keys:
- an active subscription
- a Pro trial
- a pilot account (arranged with Happy Webs)
Demo workspaces can’t make or use keys.
If the subscription lapses, you get 14 days’ grace. After that the workspace returns to Free. Existing keys can still read, but API writes fail with 403 read_only until Pro is active again. Catalogue edits and buyer orders in the app keep working.
What a key can doLink to this section#
A key acts with the permissions of the person who made it, as they are now. A key made by an owner or admin can read every customer, every customer’s prices, every order and the activity log. Treat it like that person’s password. A key made by someone limited to their assigned customers or regions sees only those customers and their orders, prices and activity; any other customer or order returns 404, the same as one that doesn’t exist, and price changes return 403.
If that person is later given a narrower role, the key narrows with them: a write the new role isn’t allowed to make fails with 403 forbidden, the same as in the app. If they leave the workspace, the key stops working with 401 key_owner_removed. Make a new key from someone who still has access.
Last used and revokingLink to this section#
Settings shows when each key was last used (updated at most once an hour). Choose Revoke to stop a key straight away. The next request with it gets 401 unauthorized. Revoked keys can’t be restored.
Who the changes are logged asLink to this section#
Writes appear in the workspace’s activity log as API key “Sage stock sync”. Order status changes are recorded against the person who made the key.
Keep keys safeLink to this section#
- Keep keys on your server, in environment variables or a secrets manager.
- Never put a key in a web page, browser extension or mobile app. The API doesn’t allow browser (CORS) requests for this reason.
- Never commit a key to git. If you do, revoke it and make a new one.
- Use a read-only key wherever you only need to read.
ErrorsLink to this section#
| Status | Code | Why |
|---|---|---|
| 401 | unauthorized | No Authorization header, a malformed one, an unknown or revoked key, or a demo workspace. The response has WWW-Authenticate: Bearer. |
| 401 | key_owner_removed | The person who made the key no longer has access to the workspace. Make a new key. |
| 403 | insufficient_scope | A read-only key tried to write. |
| 403 | forbidden | The person who made the key isn’t allowed to do that (for example, a Viewer can’t write). |
| 403 | read_only | API writes are unavailable on the Free plan. |
See Errors for the full list.
AI apps use a different sign-in
Claude, ChatGPT and other MCP clients don’t use API keys. Each person signs in with their own login through OAuth. See MCP.