Skip to Content

API tokens

API tokens are how non-human callers — CI pipelines, scripts, the SDK — authenticate to CMDOP. The cabinet manages them; the desktop and CLI consume them.

Personal vs workspace tokens

TypeLives onScopeSurvives member churn?
Personal tokenAccountWhatever workspaces you belong to.No — revoked when the member leaves.
Workspace tokenWorkspaceOne workspace; no personal data.Yes — owned by the workspace.

For CI and shared automations, prefer workspace tokens (managed under Workspace settings). For your own scripts, personal tokens are fine.

Creating a token

Click “Create token”. Required fields:

  • Name — what this token is for (e.g. gha-deploy).
  • Scope — pick the minimum set you need (see below).
  • Expiry — never, 30 days, 90 days, 1 year, or custom.

The secret is shown exactly once. Copy it immediately — there is no recovery.

Treat API tokens like passwords. They are shown exactly once. If lost, revoke and reissue.

Permissions / scopes

Available scopes:

  • machines:read — list and inspect machines.
  • machines:write — register, deregister, retag.
  • commands:execute — drive sessions and run commands.
  • files:read, files:write — read or modify files via the agent.
  • schedules:manage — create, edit, delete schedules.
  • agent:invoke — call ask_agent / ask_agents cross-machine.
  • permissions:manage — edit permissions.yaml rules remotely.

Pick scopes by least privilege. A read-only dashboard token only needs machines:read.

Token rotation

Recommended cadence: every 90 days for production tokens, every cycle for short-lived CI runners.

To rotate without downtime:

  1. Issue a new token with the same scopes.
  2. Roll the new value out to consumers.
  3. Verify in the audit log that the old token’s last use was before the rollout.
  4. Revoke the old token.

Per-mode storage on disk

The CLI stores OAuth tokens in token_prod.json or token_dev.json depending on the active mode. API tokens are stored separately in ssh_workspaces.json (mode 0600). The cabinet does not expose this split, but it matters when you switch modes — see ../../cli/authentication.

Revocation

Revoke a token from the list:

  • Single revoke — click “Revoke”, confirm.
  • Mass revoke after a leak — “Revoke all” button at the top of the list.

Revoked tokens fail their next call with 401 Unauthorized.

Audit

Every token issuance, use, and revocation logs to the Audit log with the actor and request ID.

Where this data lives

Personal tokens live in the Django profiles app. Workspace tokens live in workspaces.

Last updated on
What is CMDOP