Authentication & API keys

Create an API key

API keys are created from the dashboard. The raw secret is shown once at creation — only its hash and a short prefix are stored — so copy it somewhere safe immediately.

1. Go to Dashboard → Developer → API Keys.
2. Click Create key, give it a label, and confirm.
3. Copy the bh_… secret. You won't see it again — if you lose it, delete the key and make a new one.

Key format

Keys look like bh_ followed by a random hex string, e.g. bh_a1b2c3d4e5f6…. The first ~11 characters (bh_ + 8 hex) are the prefix shown in the dashboard so you can tell keys apart; the rest is the secret. There is a single key type — there are no separate sk_/pk_ variants.

Send the key

Most endpoints accept the key as a Bearer token in the Authorization header. The browser-facing chat endpoint also accepts an x-api-key header.

Authorization: Bearer bh_your_api_key

x-api-key: bh_your_api_key

curl -X POST https://bothive.cloud/api/bots/<botId>/run \
  -H "Authorization: Bearer bh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Hello" }'

Keep keys secure

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

Error responses

Authentication and authorization failures come back as JSON with the matching status code:

401  { "error": "Missing API key" }
401  { "error": "Invalid API key" }
403  { "error": "Unauthorized" }            // key can't run this bot
429  { "error": "Rate limit exceeded" }     // back off or upgrade

Rate limits & quotas

Requests are rate-limited and metered against a monthly quota, both scaled by your subscription tier and billed to the key's owner. When you hit a limit you'll get a 429; responses on metered endpoints also include an X-Quota-Remaining header so you can track usage. See your current plan and limits under Dashboard → Billing.

Next steps