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

# CLI Authentication

> How humans log into the BKey CLI (RFC 8628 device authorization) and how they mint client credentials for agents.

# CLI Authentication

Two flows end up issuing a token the CLI can use:

* **For Humans** — `bkey auth login` uses [RFC 8628 device authorization](https://datatracker.ietf.org/doc/html/rfc8628): display a code, scan a QR on your phone, approve with biometrics.
* **For Agents** — `bkey auth setup-agent` mints OAuth `client_credentials` so a headless agent or CI job can authenticate without a human in the loop on every request.

> Agents still need a human to create them. You have to `bkey auth login` once as a human before you can run `setup-agent` — the new agent is gated on a biometric approval from your phone before the credentials are issued.

***

## For Humans

Interactive login from any terminal. Uses the device authorization flow so you can log in on a machine that has no browser (SSH, CI debug shell, IoT device, etc.) by approving on your phone.

### Usage

```bash theme={null}
bkey auth login
```

The CLI prints a short user code and a verification URL, opens the URL in your browser with the code pre-filled, and starts polling. On your phone:

1. Open the BKey app (or follow the URL on a phone browser).
2. Confirm the user code matches.
3. Approve with facial biometrics.

The CLI unblocks the moment the phone completes approval and saves the session as a human profile in `~/.bkey/profiles.json` (default identifier: `default`). Subsequent `bkey …` commands use it automatically. Multiple profiles can coexist — pass `bkey auth login --profile work` to save under a different name, then select with `bkey <cmd> --profile work` or `BKEY_PROFILE=work bkey <cmd>`.

### Flow at the protocol level

1. Client calls `POST /oauth/device_authorization` and receives `device_code`, `user_code`, `verification_uri`.
2. User visits the URL on their phone and enters the code, or scans the QR.
3. User approves with facial biometrics.
4. Client polls `POST /oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code` until it gets an access token.

Use cases:

* CLI tools (`bkey auth login`)
* SSH sessions and CI debug shells
* IoT devices with no browser

***

## For Agents

Agents authenticate with the OAuth 2.1 **client credentials** grant — one `client_id` + `client_secret` per agent, no phone roundtrip on every call. The credentials are minted by a human running `bkey auth setup-agent` after they're logged in.

### Minting agent credentials

```bash theme={null}
# Requires a prior `bkey auth login` (human must be logged in)
bkey auth setup-agent --name "My Deploy Bot" --save
```

* Pushes an approval prompt to the logged-in human's phone if the requested scopes are elevated (biometric approval). Baseline-scope agents (e.g. `approve:action` only) may be created without a phone prompt — all subsequent `bkey approve` calls still go through CIBA at the phone.
* On approval, BKey returns the agent's `client_id` + `client_secret`.
* `--save` stores them as an agent profile in `~/.bkey/profiles.json`. The profile identifier is slugified from `--name` (e.g. `"My Deploy Bot"` → `my-deploy-bot`); override explicitly with `--profile <slug>`. Collisions error unless `--overwrite` is passed.
* `--json` prints the creds to stdout instead (for CI secret setup, env vars, etc.).

### Running as an agent

Since 0.3.0 agent mode is opt-in — a saved agent profile no longer silently overrides your user session. Select agent mode explicitly:

```bash theme={null}
# Approve as the default agent profile
bkey approve "Deploy api-gateway@abc123 to prod" --agent \
  --scope approve:action \
  --user-did did:bkey:...

# Or pin a specific agent profile by name
bkey approve "…" --agent --profile my-deploy-bot …

# Or via env vars (CI/CD, Docker)
export BKEY_MODE=agent
bkey approve "…" …

# Direct client_credentials — bypasses profiles entirely
export BKEY_CLIENT_ID=bkey_client_xxx
export BKEY_CLIENT_SECRET=bkey_secret_xxx
bkey approve "…" …
```

### In code (Python / TypeScript)

```typescript theme={null}
import { BKey } from '@bkey/sdk';

const bkey = new BKey({
  clientId: process.env.BKEY_CLIENT_ID!,
  clientSecret: process.env.BKEY_CLIENT_SECRET!,
});

// Token is exchanged + refreshed automatically.
```

```python theme={null}
from bkey import BKeyClient

client = BKeyClient(
    client_id=os.environ["BKEY_CLIENT_ID"],
    client_secret=os.environ["BKEY_CLIENT_SECRET"],
)
```

### Default scopes

`bkey auth setup-agent` includes a sensible default scope set (`vault:access`, `vault:store`, `signing:create`, `signing:read`, `identity:read`, `approve:action`, `approve:payment`, `payment:authorize`, `payment:address`, `payment:limits`). Override with `--scopes <comma-separated>` to tighten or expand.

Use cases:

* Headless agents (e.g. a cron job that calls paid APIs)
* Server-to-server communication
* CI pipelines making authenticated calls
* MCP servers verifying CIBA approval tokens

### What agents *can't* do on their own

Agent tokens from `client_credentials` don't grant per-action authority by themselves. For anything sensitive (payments, vault access, deploys), the agent must still initiate a [CIBA](/docs/authentication/ciba) approval — the human gets a push and approves with biometrics, the agent gets a short-lived, scope-bound token proving that consent. See the [CIBA guide](/docs/authentication/ciba) for the one-line `approve()` pattern.

***

## See also

* [Client Credentials](/docs/authentication/client-credentials) — raw protocol details for the agent grant
* [CIBA](/docs/authentication/ciba) — per-action biometric approval (what agents use once they have a base token)
* [Authentication overview](/docs/authentication/overview) — all three grant types at a glance
* [CLI reference](/docs/sdk/cli) — `bkey auth`, `bkey approve`, `bkey proxy`, `bkey wrap`, etc.