Access tokens

An access token replaces a domain password in a script or a scheduled task. It can be narrowed to a single action, given an expiry date, and revoked — without touching anyone's account.

Two kinds

Kind	Its permissions	When to use it
Personal	Re-intersected on every request with the owner's current permissions	A tool you run in your own name
Service	Fixed from the creator's permissions at the moment of creation, and unchanged afterwards	A nightly job or a standing link between systems

The difference shows on the day a user loses a role. A personal token loses the permissions that role granted at that moment, with nobody touching it. A service token keeps working — which is its whole point: a nightly script should not fail on the day the person who set it up leaves. Creating a service token requires a separate permission, and revocation is the control on it.

Scopes are permission keys

The scope picker is the same catalog as Roles and permissions, with the same access ladders and the same actions. There is also a "copy permissions from a role" shortcut.

The list starts empty. A permission you do not hold cannot be ticked at all, and the reason is shown beside it — a create that quietly returned a token weaker than you asked for is exactly the fault that gets debugged at three in the morning.

Creation, once and only once

The secret is shown once, at creation. It is not stored — only a signature of it is — so there is no "show it again". A lost token is replaced by refreshing it.

What is stored and shown is the public id: a short string that is not a secret, safe to quote in a support request, and the value that appears in the change log.

The default expiry is 90 days, and the picker also offers 30, 60 and a year. "No expiry" exists but takes an explicit separate confirmation — that is how an estate accumulates credentials nobody remembers.

Each user has a quota of live tokens. At the quota you revoke an existing one before creating another; that is not a technical limit but a control on the credential list staying short enough to read.

The list

The table shows name, kind, number of permissions, last used, from where, expiry and status. Anyone holding the manage-all-tokens permission also gets an owner column, and everyone's tokens.

Status	Meaning
Active	Valid, and already used
Never used	Valid, and never presented to the server
Disabled	Switched off, and reversible
Expired	Past its expiry date
Cancelled	Stopped permanently

The status is computed on the server in one priority order — revocation beats expiry, and expiry beats the switch — so the table, the drawer and any future alert cannot say three different things about one token.

Refresh, revoke, delete

Refresh issues a new secret for the same name and the same permissions. The old token stays valid for an overlap period you choose — a day, a week or a month, or "now" for an immediate cut — so it can be swapped in the system using it without downtime.

Revoke is irreversible. Anyone using the token gets a permission error immediately, and the row stays as evidence: who revoked it, when, and the address it was last used from.

Delete removes that evidence too. If the aim is only to stop a token, revoke is the better move.

How it is sent

In the X-API-Key header, or as Authorization: Bearer. The secret itself is never written to a log, an audit record or an error message; the only value that appears there is the public id.