Headless authentication

Sign in to Orca from terminals with no browser: the device flow, environment variables, and CI patterns.

Three ways to authenticate a machine, from most to least interactive.

1. Device flow: orca login

On a terminal with no usable browser (a coding agent, SSH, a container), orca login runs an RFC 8628 device flow automatically:

First, copy your one-time code: BCDF-GHJK
Then open: https://app.orcapods.ai/cli-auth?code=BCDF-GHJK
Waiting for approval... (expires in 15 minutes, Ctrl-C to cancel)

Open the URL on any device, sign in, check the code matches, and approve. The CLI receives its key by polling and stores it in ~/.config/orca/config.json; the key never appears on a screen or in a paste buffer. Force this flow anywhere with --headless.

Security shape worth knowing: the minted key inherits the approving user’s role, the approval screen shows which terminal asked (the key label, for example claude-code-ada@laptop), and codes are single-use with a 15 minute expiry.

2. Environment variables

For processes that should never prompt:

export ORCA_API_KEY=ao_live_...
export ORCA_API_URL=https://api.orcapods.ai   # only for self-hosted or local

Both the CLI and the MCP server read these before falling back to the config file. Mint keys in the dashboard (Settings, then API Keys) or from an already-authenticated CLI:

ORCA_API_KEY=$(orca keys create ci </dev/null)

3. Pre-minted token

orca login --with-token ao_live_...

Verifies the key and persists it into the current context; useful when a human minted the key elsewhere.

Verify

orca whoami --json

Returns the tenant, role, credential kind, and key id the stored credential acts as.

Honest caveat: keys have no scopes

An Orca API key carries exactly one authorization dimension: the RBAC role it inherited from whoever minted or approved it (owner, admin, member, or viewer). There are no per-resource or per-operation scopes yet. Treat an admin key as admin everywhere; prefer approving device logins from a member account when the agent only needs day-to-day operations, and revoke keys you stop using (orca auth logout --revoke, or the dashboard key list).