Skip to main content

Personal API tokens

Route: /administration (API tokens) · Role: admin

Personal API tokens let a script or tool call the /api/v1 API as you, with your role. Optional scopes narrow the token further.

Create a token​

  1. Open Administration → API tokens.
  2. Enter a Token name (for example ci-deploy).
  3. Optionally enter scopes, comma-separated. Leave blank for the full * scope.
  4. Click Create token.
  5. Copy the token now — it is shown once and starts with cxp_.
cxp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Scopes​

Scopes are resource:action, or * for everything. Valid scopes:

customers:read   customers:write  projects:read    projects:write
time:read        time:write       time:review      agreements:read
agreements:write billing:read     billing:write    reports:read
admin:read       admin:write

The effective permission is the intersection of the token's scopes and the owner's role — a billing:write scope on an engineer still needs a role that can write billing.

Use a token​

curl -s https://intranet.example/api/v1/me \
  -H "Authorization: Bearer cxp_XXXXXXXX..."

Tokens authenticate bearer requests. A browser session cookie takes precedence if both are present.

Revoke a token​

Click Revoke on the row. The token stops working immediately; revocation is stamped and audited. Revoked tokens remain listed with the revoked label.

Copy once

Only a hash is stored. If you lose a token, revoke it and create another — there is no reveal.

The table shows​

Name and scopes, the token preview (prefix…lastFour), and last-used time.