> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
ORCA_API_KEY=$(orca keys create ci </dev/null)
```

## 3. Pre-minted token

```bash theme={null}
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

```bash theme={null}
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).