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 fleet tokens

For CI and shared automations, prefer fleet tokens (managed under Fleet 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.

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_machine / ask_machines 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 are scoped to your account; fleet tokens are scoped to the fleet. Each is managed where it belongs and revoked independently.

Related

• Fleet settings — fleet API keys.
• cmdop authentication
• Concepts: fleets — credential resolver order.
• API key vs OAuth