API Keys & Authentication

Every external call to a hosted bot or workflow is authenticated with a Bothive API key. Here's how to manage them safely.

Create a key

Keys are created in the dashboard, and the raw secret is shown once:

1. Go to Developer → API Keys.
2. Click Create key, give it a label, confirm.
3. Copy the bh_… secret immediately — you won't see it again.

On paid plans you must enable two-factor auth before minting keys (free tier is exempt). If creation returns 403 with 2fa_required, turn on 2FA under Settings → Security first.

Key format

Keys look like bh_ followed by a random string. The first ~11 characters are a prefix shown in the dashboard so you can tell keys apart; the rest is the secret. There's a single key type — no separate sk_/pk_ variants.

Send the key

Most endpoints take a Bearer token; the browser chat endpoint also accepts x-api-key:

bash
# Most endpoints
Authorization: Bearer bh_your_api_key

# POST /api/v1/chat
x-api-key: bh_your_api_key

Keep keys secure

• Store keys in server-side env vars — never commit them or ship them in client bundles.
• Use a separate key per app/environment so you can rotate one in isolation.
• To rotate: create the new key, deploy it, then delete the old one.
• For browser UIs, prefer a public bot via the CORS chat endpoint, or proxy through your backend.

Errors

• 401 missing/invalid key · 403 not allowed to run this resource · 429 rate limit or quota.

Usage on a key is billed to its owner, so treat it like a password.