​

CLI Authentication

• For Humans — bkey auth login uses RFC 8628 device authorization: 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

​

Usage

bkey auth login

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

​

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.

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

​

For Agents

​

Minting agent credentials

# 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

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

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.

from bkey import BKeyClient

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

​

Default scopes

• 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

​

See also

• Client Credentials — raw protocol details for the agent grant
• CIBA — per-action biometric approval (what agents use once they have a base token)
• Authentication overview — all three grant types at a glance
• CLI reference — bkey auth, bkey approve, bkey proxy, bkey wrap, etc.