CLI login

The CLI login endpoints let a terminal or a coding agent create a Strix account and get an API token without a dashboard visit. The flow uses OAuth 2.0 device authorization. The open-source CLI runs this flow with the strix cloud login command.

Start device authorization

This endpoint does not require authentication. The browser step establishes the user identity.

curl -X POST "https://app.strix.ai/api/v1/cli/login"

The response contains a user_code, a verification_uri_complete, a device_code, an expires_in value, and a poll interval in seconds. Show the user_code to the user and open verification_uri_complete in a browser. Keep the device_code private. This endpoint and the poll endpoint accept POST only. If a browser opens one of these URLs with GET, the server starts no sign-in. It returns 405 with an Allow: POST header and a short explanation. The body is HTML for a browser and JSON for other clients. The JSON body contains the strix cloud login command, the install URL, and the documentation URL.

Poll for completion

Poll this endpoint with the device_code at the returned interval.

curl -X POST "https://app.strix.ai/api/v1/cli/login/poll" \
  -H "Content-Type: application/json" \
  -d '{"device_code": "<DEVICE_CODE>", "scope_profile": "recommended", "client_instance_id": "<STABLE_INSTALLATION_ID>", "device_name": "macOS CLI · a1b2c3d4"}'

Choose scope_profile as minimal, recommended, or full, or send a custom scopes array. The server always includes the minimum scopes scans:read, scans:write, and billing:read; the member’s role caps the final set. The CLI exposes --scope-profile and --scopes. The open-source CLI generates one opaque client_instance_id per installation and a privacy-safe device_name that contains no hostname. Sending both makes later sign-ins from the same installation replace that session’s secret and expiry in the same database row instead of creating an unlimited series of keys. Different installations remain separately visible and revocable in Settings → API Access as CLI sessions. Omit both fields only for compatibility with an older client. Without either field, the server uses Recommended. This profile covers the resources that strix cloud commands use every day:

Scans: scans:read, scans:write, scans:message, uploads:write
Findings: vulnerabilities:read, vulnerabilities:write, dependencies:read, supply_chain:read, supply_chain:write
Assets and schedules: assets:read, assets:write, schedules:read, schedules:write
Reviews and knowledge: pr_reviews:read, pr_reviews:write, knowledge:read, knowledge:write, chat:read, chat:write
Connectors: connectors:read, connectors:write
Integrations: integrations:read, integrations:write
Workspace: organizations:read, organizations:write, webhooks:read, audit:read, analytics:read, license:read, billing:read, billing:write

The workspace and integration scopes let an admin agent complete the first-time setup steps from the login response. The agent can name the workspace and connect a repository provider. The billing scopes let an admin agent complete the user-approved Link/MPP credit top-up flow when a scan needs credits. Account administration still requires Full or an explicit custom scope request: members:read, members:write, invitations:read, invitations:write, webhooks:write, tokens:write, llm:read, llm:write, test_users:read, and test_users:write. Workspace listing and switching the current CLI session do not themselves require organizations:read or tokens:write. The server omits the scopes that the member’s role cannot receive. A profile change applies to new logins only. An existing session keeps the ceiling that the user approved at sign-in. While the user has not confirmed in the browser, the response is an error with the code authorization_pending. Continue to poll. If the response code is slow_down, increase the poll interval by 5 seconds.

Interactive workspace and scope selection

Send "interactive": true in the poll request to select a workspace and scopes after the browser step. When the user confirms in the browser, the response then contains selection_required: true, a short-lived selection_token, is_new_user, the workspaces of the user, and the full scope catalog with descriptions. Each scope entry shows if the scope is part of the minimum set, if it is a default, and the lowest member role that can receive it. Each workspace entry contains has_default_name. This value is true when the user is an admin and the workspace still has the generated name, for example Alex's Workspace. Complete the login with the selection:

curl -X POST "https://app.strix.ai/api/v1/cli/login/complete" \
  -H "Content-Type: application/json" \
  -d '{"selection_token": "<SELECTION_TOKEN>", "organization_id": "<uuid>", "scope_profile": "minimal", "workspace_name": "Acme Security"}'

The workspace must be one of the memberships of the user. The server always includes the minimum scopes. The role of the member limits the final set. The selection token expires after 10 minutes. The strix cloud login command uses this flow in an interactive terminal. It offers a workspace picker and the scope presets Recommended, Full access, and Minimal. The --workspace flag selects a workspace by name or ID without a prompt. The workspace_name field is optional. Use it when the workspace has has_default_name set to true. The user must be an admin of the workspace. The server mints the token and then renames the workspace. A failed rename does not fail the sign-in. If the value equals the current default name, the server records that the user chose the name. An empty value keeps the current name. In an interactive terminal, the strix cloud login command asks a first-time user for a workspace name. When the user confirms, the response contains the account and a personal API token:

{
  "api_token": "strix_...",
  "organization_id": "<uuid>",
  "organization_name": "My workspace",
  "email": "user@example.com",
  "expires_at": "2026-11-24T00:00:00.000Z",
  "is_new_user": true,
  "scopes": ["scans:read", "scans:write", "billing:read"],
  "scope_ceiling": ["scans:read", "scans:write", "billing:read"],
  "requested_scopes": ["scans:read", "scans:write", "billing:read"],
  "scope_profile": "minimal",
  "token_id": "<uuid>",
  "credential_source": "cli",
  "device_name": "macOS CLI · a1b2c3d4",
  "onboarding": {
    "workspace_named": false,
    "repositories_connected": false,
    "domains_added": false,
    "github_install_url": "https://github.com/apps/strix/installations/new?state=..."
  },
  "next_steps_hint": "Your workspace still has its default name. Name it with strix cloud org update --name. ...",
  "next_steps": [
    { "action": "Name your workspace", "cli": "strix cloud org update --name \"Acme Security\"", "method": "PATCH", "path": "/api/v1/organization" },
    { "action": "Connect GitHub repositories for PR security reviews and code scans", "cli": "strix cloud integrations install github", "method": "POST", "path": "/api/v1/integrations/github/install-url" },
    { "action": "List your workspaces", "cli": "strix cloud workspaces list", "method": "GET", "path": "/api/v1/workspaces" },
    { "action": "Add a domain to test", "cli": "strix cloud domains add --domain example.com --asset-type web_app", "method": "POST", "path": "/api/v1/domains" },
    { "action": "Check your scan credits", "cli": "strix cloud billing credits", "method": "GET", "path": "/api/v1/billing/credits" },
    { "action": "Start a scan", "cli": "strix cloud scans start --engagement-type live_test --domain-ids <uuid> --wait", "method": "POST", "path": "/api/v1/scans" }
  ],
  "dashboard_url": "https://app.strix.ai"
}

The next_steps list gives the first actions after a sign-in, in order. Each step contains the CLI command and the matching API call. An agent can read the list from the JSON response. The CLI prints next_steps_hint after a successful login. The onboarding object reports what the workspace still lacks. The server computes it from live data on every sign-in:

workspace_named is false while the workspace still has the generated default name. Rename the workspace with PATCH /api/v1/organization.
repositories_connected is true when at least one repository has an active installation.
domains_added is true when at least one domain exists in the workspace.
github_install_url is present for an admin session without asset scopes while no repository is connected. A person opens the link in a browser. If the browser has no dashboard session, the dashboard asks the person to sign in with the same account and then returns to the installation. The link expires after 10 minutes.

The setup steps in next_steps match the permissions of the session. The list contains the rename step only when the session has organizations:write. The list contains the GitHub step only when the session has integrations:write and github_install_url is present. If the server cannot read the live state, the response omits onboarding. The token is still valid in that case. When the workspace can still start the Cloud plan trial, the list ends with a step that starts the trial. The Cloud plan includes PR security reviews and starts with a free trial of up to 7 days. The plan does not include scan credits. The api_token value is shown only once. Store it in a secure location. scope_ceiling is the immutable maximum authority accepted at this login; workspace and profile changes can narrow it but cannot widen it. Broader access requires another browser sign-in. For a first-time user, Strix creates the account and a default workspace automatically. The token is valid for 90 days.

CLI output and automation

In a terminal, strix cloud output is compact and action-oriented: lists favor names, branches, lifecycle states, and numbered selectors. Internal organization and user IDs are omitted, while a required selector that is too long for a compact table is repeated losslessly in a copyable block. Paginated lists print the next --page or --offset, and detail views prioritize useful prose within a safe terminal bound. A bare resource group with a safe read operation runs its default list/read action; use -h or help to list that group’s verbs. Pass --json for the complete record. When stdout is redirected or is not a terminal, output automatically becomes JSON and the CLI never prompts. Binary downloads are the exception: redirect their raw bytes intentionally, or use --output FILE --json to write the file and receive structured download metadata.

Workspaces

A personal token belongs to one workspace. Use these endpoints to list the workspaces of the user, create a workspace, and retarget the active personal token to another workspace. All three need a personal token from the login flow. A service token belongs to a single workspace and cannot use them.

List workspaces

curl -X GET "https://app.strix.ai/api/v1/workspaces" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Required scope: none. The bearer must be a personal token. Keeping this recovery operation scope-independent lets a Minimal CLI session discover and switch workspaces. Each entry contains id, name, role, and current. In an interactive terminal, the CLI presents the entries as a numbered list and hides the long IDs from the compact table. JSON output still contains the complete records:

strix cloud workspaces             # numbered human-readable list
strix cloud workspaces --json      # complete records for agents

Create a workspace

curl -X POST "https://app.strix.ai/api/v1/workspaces" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Team"}'

Required scope: organizations:write and an admin role. The Recommended preset includes this scope for admins. The user becomes the admin of the new workspace.

Switch the active token to another workspace

curl -X POST "https://app.strix.ai/api/v1/workspaces/<ORGANIZATION_ID>/token" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "X-Strix-Workspace: <CURRENT_ORGANIZATION_ID>" \
  -H "Content-Type: application/json" \
  -d '{"scope_profile": "minimal"}'

Required scope: none. The bearer must be a personal token. The user must be a member of the workspace. An ordinary switch preserves the server-side requested profile, then the target-workspace role caps its effective scopes. A scope_profile or custom scopes request may narrow within scope_ceiling; a request beyond the ceiling returns 403 and requires login again. The endpoint retargets the same row and keeps its bearer secret and expiry, making an exact retry safe after a lost response.

strix cloud workspaces use 3              # number from the current list
strix cloud workspace use "My Team"       # singular alias and exact name
strix cloud workspaces use <WORKSPACE_ID> # stable ID for automation
strix cloud session scopes               # effective scopes and login ceiling
strix cloud session scopes set minimal   # narrow without logging in again

workspace and workspaces are aliases. The use selector accepts a displayed number, exact case-insensitive name, or workspace ID. If names are duplicated, use the displayed number or ID. A list number is convenient for a person but is not a stable automation identifier; an agent should use the ID from --json. Ordinary switching does not ask for scopes again. workspaces use --json returns the resulting profile, granted/requested/ceiling scopes, expiry, CLI-session metadata, and a stored boolean without returning the bearer secret. The CLI updates local metadata only after success and never persists --token or STRIX_API_TOKEN overrides.

Session safety and revocation

Managed CLI-session requests include X-Strix-Workspace with the organization selected when the process started. If another shell switches the same device session, a stale command receives 409 workspace_session_changed instead of silently running against the new workspace. JSON CLI output preserves the error code plus current and expected workspace IDs for agent recovery. GET /workspaces, GET /cli/session, and an exact workspace-switch retry remain available for recovery; stale processes cannot change scopes or revoke the session. Direct API clients using a CLI session should send the same header; ordinary API tokens are unchanged.

strix cloud session                        # fetch remote session state
strix cloud session scopes --json          # effective/requested/ceiling scopes
strix cloud session scopes set recommended
strix cloud logout                         # remote revoke, then local deletion
strix cloud logout --local-only            # deliberate emergency local cleanup

When a command needs a scope that the session does not have, the API returns 403 with details.code set to insufficient_scope, the required_scope, and a hint. The hint gives the one instruction that resolves the error:

If the scope is inside the login ceiling, run strix cloud session scopes set full.
If the scope is outside the login ceiling, run strix cloud login --scope-profile full and approve the wider access in the browser.
If the role of the member cannot hold the scope, ask a workspace admin to change the role.
For an ordinary API token, create a token that includes the scope in Settings → API Access.

GET /api/v1/cli/session returns the current session. PATCH changes scope_profile or custom scopes within the ceiling. DELETE revokes that same bearer without requiring tokens:write. Normal logout keeps the local token after transport or server failures so revocation can be retried; a definitive success or already-invalid (401) response permits local deletion. Revoked and expired CLI-session rows are retained for a bounded audit window, then purged.

Tab completion

Completion is generated by the source CLI as well as packaged binaries. It therefore works with uv run strix too:

source <(strix completions zsh)
# From a source checkout:
source <(uv run strix completions zsh)
# bash: source <(strix completions bash)
# fish: strix completions fish | source

Add the appropriate command to the shell startup file to enable it in future terminals. Completion covers cloud groups, verbs, flags, and singular resource aliases; it does not send a request or expose token values.

Getting Started

Guides

Start device authorization

Poll for completion

Interactive workspace and scope selection

CLI output and automation

Workspaces

List workspaces

Create a workspace

Switch the active token to another workspace

Session safety and revocation

Tab completion

​Start device authorization

​Poll for completion

​Interactive workspace and scope selection

​CLI output and automation

​Workspaces

​List workspaces

​Create a workspace

​Switch the active token to another workspace

​Session safety and revocation

​Tab completion

Start device authorization

Poll for completion

Interactive workspace and scope selection

CLI output and automation

Workspaces

List workspaces

Create a workspace

Switch the active token to another workspace

Session safety and revocation

Tab completion