API Tokens

8.8 API tokens

Since 3.1.43 a user can issue API tokens for themselves: bearer credentials for scripts, CI jobs, an MCP server or the CLI, that carry a subset of the user's own grants and a cluster scope, and expire. A client sends the token as Authorization: Bearer <token> and never logs in. Every call is attributed to the user who issued the token in the security log.

A token replaces the interactive login for machine clients. The login itself, the POST /api/login call that returns a session JWT from a username and password, and the accounts it authenticates are described in First login and API client usage. Creating a token still requires that login: a token cannot issue tokens.

A token can only narrow what its owner may do, never extend it:

• At creation, every grant put in the token must be a grant the owner holds.
• At every request, the effective grants are the token's grants and the owner's current grants. Remove a grant from the user, and every token of that user loses it at once. Delete the user, and the tokens stop working.
• A token scoped to named clusters can only reach those clusters' endpoints. Global settings and cluster management need the "every cluster" scope.
• A token cannot issue tokens. Creating one requires an interactive login.
• Two grants control it: token-create lets a user issue tokens for their own account, token-manage lets them list and revoke other users' tokens on a cluster. Both are in the default ACL of admin; dba, sponsors and external dbops get token-create. If your api-credentials-acl-allow lists grants explicitly, add token or token-create to the users who should issue tokens. The system service account can never hold these grants.

8.8.1 Creating a token

Dashboard: click your user name in the top bar, then API tokens in the User Profile window, then New token. Give it a label, pick the grants (none selected means every grant you hold), the cluster scope, and the lifetime. The token is displayed once with a copy button; the eye icon shows it again later, since it is yours.

CLI:

replication-manager-cli token create --label ci --grants "db-show proxy" --clusters belair --expire-days 30
replication-manager-cli token list
replication-manager-cli token revoke <id>

--grants takes grant prefixes as in the ACL configuration (db-show, proxy, cluster-switchover, …); --expire-days -1 means no expiry; both default to "everything I hold" and the server default lifetime.

API:

8.8.2 Using a token

With the interactive login you first exchange a username and password for a session JWT (see API client usage):

JWT=$(curl -s -k -H 'Content-Type: application/json' --data '{"username":"admin","password":"..."}' https://repman:10005/api/login | jq -r .token)
curl -k -H "Authorization: Bearer $JWT" https://repman:10005/api/clusters/belair/topology/servers

With an API token there is no login call, the token is the bearer:

curl -k -H "Authorization: Bearer <token>" https://repman:10005/api/clusters/belair/topology/servers
replication-manager-cli --api-token <token> topology --cluster belair

A session JWT expires after api-token-timeout hours and dies when replication-manager restarts; an API token lives until its expiry or revocation and survives restarts.

A revoked token is refused immediately. Revoking another user's token needs the token-manage grant on every cluster the token covers.

Dashboard, every user's tokens on a cluster (since 3.1.44): with token-manage on a cluster, its Users tab shows an API tokens panel listing every token that covers the cluster, whoever owns it: owner, label, clusters, grants, creation, last use (time and address) and expiry, in two tabs. Active lists the tokens in use: the trash icon revokes one after a confirmation naming its owner and label. Archive lists the revoked tokens (when and by whom) and the expired ones, kept 90 days as the audit trail. The token string itself is never shown there. When the token also covers a cluster where you lack token-manage, the revoke is refused and the error names that cluster. The Users tab opens with cluster-grant or token-manage; each panel needs its own grant.

8.8.3 Where tokens live

Tokens are stored on the replication-manager instance in <monitoring-datadir>/api-tokens.json, encrypted with the persistent secret key (monitoring-key-path) and excluded from the configuration git sync. They survive a restart of replication-manager. Rotating the secret key invalidates every token: reissue them afterwards.

8.8.4 Settings

Both are server-wide settings.

8.8.5 Security log

Events api_token_created, api_token_revoked and api_token_denied (a token used out of its scope or for a grant it does not carry) are written to the security log with the owner's name and the client address. See Security logging.