API & MCP tokens
Overview
A token is a long-lived access key for everything that reaches the system without a sign-in screen: your own programs, automations from other systems, and the MCP server through which AI tools work.
Two properties govern how to handle them. A token exercises the permissions of its user — it can never do more than the account it hangs on, though it can be narrowed to a subset. And a token can be revoked at any time, without touching the account.
Core tasks
Create a token. Create token requires a name, the owning user and the type. The name should state the purpose — in a year's time it is the only thing by which a token can be identified.
Choose the right type. There are two, and they differ in traceability:
| Type | Meaning | Appears in the log as |
|---|---|---|
| API | personal token for your own programs | Human |
| MCP / AI | identity for AI tools via the MCP server | AI |
The difference is not cosmetic: it decides whether the audit log later says "a human did this" or "an AI did this". An AI tool using an API token makes the origin of every change unrecognisable.
Narrow the permissions. By default a token holds all permissions of its user. Choose instead the subset the purpose needs — a token meant only to read should only be able to read.
Set an expiry. An expiry date limits the damage of a token gone astray by itself.
Revoke. A revoked token stops working immediately. The list keeps it with status Revoked, so that it stays traceable that it existed.
Monitor what exists. The list shows name, user, type, a token preview, the permissions, last use, expiry and status. The Last used column reading Never is the best sign of a token nobody needs — and that can therefore go.
Fields in detail
| Field | Required | Values / format | What it does |
|---|---|---|---|
Name name | yes | text, max. 120 characters | What the token is for. In an incident this is the only trail to which program is affected — "Shop connection" helps, "test" does not. |
User userUlid | no | an existing account | In whose name the token acts. It carries exactly that account's permissions — no more, and no less without the restriction below. |
Actor type actorType | no | human, AI, automation | How actions are marked in the audit log. An AI token acts visibly as AI, under the same identity. |
Restriction scopes | no | list of areas | What the token is limited to. Without an entry it can do everything the account can — which is why a restriction is the rule, not a precaution for the timid. |
Valid until expiresAt | no | point in time | When the token ends by itself. An expiry date is the most effective guard against forgotten access. |
The key is shown exactly once — on creation. After that it cannot be made visible again, only revoked and reissued. Revoking takes effect immediately.
Settings & permissions
- Permission
platform.api_token.manage. Without it the page is unreachable. - The token value is shown once. After creation it cannot be retrieved again; the list shows only
a preview. If it is lost, a new token is created.
- Three statuses: Active, Revoked, Expired.
- Permissions stay coupled. If the user loses a permission, the token loses it too.
FAQ & troubleshooting
I lost the token value. It cannot be recovered. Revoke the old token and create a new one.
Access is suddenly refused. Check in this order: status Expired? Status Revoked? Was a permission withdrawn from the user? Is the account deactivated?
The audit log says "Human" for AI actions. Then the AI tool is using a token of type API. Create one of type MCP / AI.
A member of staff is leaving. Deactivating the account is not enough as a deliberate act — additionally check which tokens hang on that account and revoke them.