Authentication

Every BizOS API request is authenticated with a Bearer API key (bzk_live_…). Keys are scoped to exactly one organization, stored hashed server-side, shown once, and revocable. The CLI reads BIZOS_API_KEY / BIZOS_API_URL.

API keys

The CLI authenticates with an org API key. Keys look like:

bzk_live_a1b2c3d4e5f6...

The server authenticates every /api/cli/* route via guardCliRequest(req), which reads the Authorization: Bearer … header and resolves the org from the key. There is no separate "select org" step — the key is the org.

How keys are scoped

• One org per key. A key grants access to exactly one organization. All requests use serviceClient() filtered by org_id, so a key can never read or write another org's data.
• Rate-limited per key. Each key is independently rate-limited.
• Billing-bound. Credit-spending happens only through the shared billing library, scoped to the key's org. A key cannot bypass billing.

Security

• Hashed at rest. Only a hash of the secret is stored server-side; the plaintext secret is never persisted by BizOS.
• Shown once. When you create a key, the secret is returned a single time. If you lose it, revoke it and create a new one.
• Revocable. Delete a key from Settings → API keys at app.bizos.lol and it stops working immediately.
• Stored 0600 locally. bizos login writes the key to ~/.config/bizos/config.json and chmods it to owner-only. The key is never echoed to logs, shell history, or the working directory.

Creating and managing keys

Keys are created and revoked in the browser dashboard (these endpoints use your logged-in session, not an API key):

1. app.bizos.lol → Settings → API keys.
2. Create key → name it → copy the secret (shown once).
3. To revoke, delete the key from the same screen.

The dashboard list shows each key's name, prefix, and last_used_at — but never the secret.

Logging in from the CLI

Interactive (stores the key locally):

bizos login

Non-interactive (CI, agents) — set an env var and skip login:

export BIZOS_API_KEY="bzk_live_your_key_here"
bizos whoami

To clear the stored key:

bizos logout

Environment variables

The effective key is resolved as: BIZOS_API_KEY → stored key. The effective base URL is resolved as: --api-url flag → BIZOS_API_URL → stored URL → https://app.bizos.lol.

Auth errors

A 401 means the key is missing, malformed, or revoked. The API returns:

{ "error": "unauthorized", "message": "Run `bizos login`." }

Fix it by running bizos login again or setting a valid BIZOS_API_KEY.