API reference

API reference: API tokens

Cloud Control API-token management: list your org's tokens, create a cc_pat_ token with a role ceiling and expiry (secret shown once), and revoke a token. Session-only.

Manage cc_pat_… API tokens. Token administration requires a session — a Bearer-authenticated request here gets a 403. Members see their own tokens; org admins see the whole org's.

GET/api/org/tokensSession only

List tokens (yours; org-wide for admins). Never includes the secret.

Example response

json

{ "tokens": [ { "id": 3, "name": "inventory-export", "role": "Viewer",
  "createdAt": "2026-07-10T…", "expiresAt": "2026-08-09T…", "lastUsedAt": "2026-07-18T…",
  "revokedAt": null, "mine": true, "creator": { "name": "Ada", "email": "ada.lovelace@example.com" } } ] }

Errors

Status	When
`401`	Not signed in.
`403`	Authenticated with a Bearer token (tokens can't manage tokens).

POST/api/org/tokensSession only (role ≤ your capabilities)

Create a token; the secret is returned exactly once.

Parameters

Name	In	Required	Description
`name`	body	yes	1–60 characters.
`role`	body	yes	One of the assignable org roles; not above your own capabilities.
`expiresDays`	body	no	Default 30, up to 365, or null for no expiry.

Example request

json

{ "name": "ci-reader", "role": "Viewer", "expiresDays": 30 }

Example response

json

{ "ok": true, "secret": "cc_pat_…", "token": { "id": 4, "name": "ci-reader", "role": "Viewer" } }

Errors

Status	When
`400`	Bad name, unknown role, or bad expiresDays.
`403`	Bearer-authenticated, or the role exceeds your capabilities.

DELETE/api/org/tokens/{id}Session only

Revoke a token. Revoked (and expired) tokens then authenticate as 401.

Parameters

Name	In	Required	Description
`id`	path	yes	Token id in your org.

Example response

json

{ "ok": true }

Errors

Status	When
`403`	Bearer-authenticated.
`404`	No such token in your org.