Ability to authenticate Cap CLI using an API key, or a device (non browser) flow

[aidansunbury]

I am trying to get the cap cli authenticated easily on remote linux sandboxes. These sandboxes will only ever be headless and have no human viewable browser, so there is no point in trying to install the desktop app to authenticate, and authenticating through the browser is also barely possible but not in a consistent and easy way.

If you run cap auth status, you get this message:

Not signed in. Sign in to Cap Desktop (the CLI reuses its login), or set CAP_API_KEY to a Cap auth key from Settings.

But there is nowhere in the cap settings on web to mint a CAP_API_KEY, and my agent confirmed this by looking at the source code.

I need this feature to actually exist, where I can mint an API key, securely inject it into my remote sandbox, and use the API key to authenticate the CLI.

[linear]

CAP-768

[tembo]

You've correctly identified a gap in the current implementation. The CLI mentions CAP_API_KEY in error messages (apps/cli/src/credentials.rs:445-446), but there's no corresponding UI in the web settings to actually generate one.

Current authentication options

The CLI currently supports three credential sources (in priority order per apps/cli/src/credentials.rs):

1. CAP_API_KEY or CAP_AGENT_TOKEN environment variables - intended for CI/headless use, but there's no web UI to mint these
2. cap auth login - browser-based PKCE OAuth flow that starts a local callback server on 127.0.0.1 (apps/cli/src/agent_auth.rs:261-268), which won't work in headless environments
3. Cap Desktop login - reuses the desktop app's stored session token

The developer API keys visible in the dashboard (cpk_/csk_ keys under Dashboard > Developers) are for the SDK API endpoints, not CLI authentication.

Implementation notes

The CLI agent authentication infrastructure already exists:

• Token format: cap_cli_ prefix with 43 base64url characters (apps/web/lib/agent-auth.ts:133-134)
• Database table: agent_api_keys with userId, tokenHash, scopes, expiresAt columns (migration 0035)
• Token exchange endpoint: /api/v1/auth/token
• Scope system: 23 granular scopes from caps:read to developer:secrets (apps/web/lib/agent-auth.ts:4-28)

What's missing is a web UI page (likely under account or developer settings) that lets users manually generate a cap_cli_* token, similar to how the OAuth flow does it programmatically. The token would be inserted into agent_api_keys with a hashed version stored, and the plaintext shown once for the user to copy.

Alternatively, a device authorization flow (RFC 8628) would let users run something like cap auth login --device which displays a code, then they approve it on any browser - no local callback server needed.

[richiemcilroy]

Thanks for the detailed report, and you were right: the CLI pointed at a settings page that did not exist yet. #2076 adds it.

Once it ships, the flow for your sandboxes is:

1. Open Dashboard, then Settings, then Account, and find Cap CLI access.
2. Create an API key: pick a name, an access profile (creator, admin, or full, the same scope sets as cap auth login), and an expiry (30/90/365 days). The cap_cli_ key is shown once.
3. Inject it into the sandbox as CAP_API_KEY (or CAP_AGENT_TOKEN, both work) and verify:

export CAP_API_KEY="cap_cli_..."
cap auth status --json

The key authenticates every cap command and MCP tool with the scopes of the chosen profile, and you can revoke it from the same page at any time. Keys minted by cap auth login show up in that list too.

The PR also fixes the underlying wart you hit: a cap_cli_ token in CAP_API_KEY previously fell into the legacy desktop code path and failed, which is why nothing you tried worked. Docs for the headless flow are added under /docs/agents/setup.

A device authorization flow (RFC 8628) is a reasonable follow-up for interactive-but-remote cases, but minted keys cover the sandbox use case you described, so we went with that first.

[aidansunbury]

Let's go!