Skip to main content

Authentication

Protected Builder API requests authenticate with an API key. Requests are account-scoped: the account is derived from the key, so you normally don't send anything else. Health, capabilities, the public inference-model catalog and public training model-config endpoints are available without authentication; the live OpenAPI document marks those exceptions explicitly.

Get your API key​

  1. Log in to console.colabhive.com
  2. Go to Settings → API Keys
  3. Click Create New API Key and copy it

API keys start with the prefix hive_. Store the key immediately — it is shown only once.

Sending the key​

Pass the key in either header:

# Preferred
curl "https://api.colabhive.com/api/builder/v1/endpoints" \
  -H "X-API-Key: hive_..."

# Or as a Bearer token
curl "https://api.colabhive.com/api/builder/v1/endpoints" \
  -H "Authorization: Bearer hive_..."

Only tokens beginning with hive_ are accepted as API keys.

Python SDK​

from colabhive import ColabHive

client = ColabHive(api_key="hive_...")
export COLABHIVE_API_KEY="hive_..."
# Optional — the account is auto-detected from the key:
export COLABHIVE_ACCOUNT_ID="0914e1c6-..."
import os
from colabhive import ColabHive

client = ColabHive(api_key=os.environ["COLABHIVE_API_KEY"])

Account context (X-Account-ID) — optional​

The account is derived from your API key, so X-Account-ID is optional for the normal API-key flow. When API-key authentication is used, a supplied X-Account-ID must match the account bound to that key; a different value is rejected with HTTP 403. It is never silently ignored and an API key cannot use it to switch accounts. The SDK sends it when you provide account_id, purely for convenience.

# Fine without X-Account-ID — the key identifies the account:
curl "https://api.colabhive.com/api/builder/v1/datasets" \
  -H "X-API-Key: hive_..."
Console session cookie

When calling from a browser logged in to console.colabhive.com, requests can authenticate via the colabhive_session cookie instead of an API key. A session may select another account with X-Account-ID only when the authenticated user has membership in that account; otherwise the request is rejected. This fallback is for the Console UI — API clients should always use an API key.

Security best practices​

  • ✅ Store keys in environment variables or a secrets manager
  • ✅ Use separate keys for development and production
  • ✅ Rotate keys regularly
  • ❌ Never commit keys to git or hardcode them in source
  • ❌ Never share keys in public channels

Scopes — account-wide authority​

API keys carry a scopes field, and it is returned when you inspect a key. Granular scope enforcement is not yet general: most Builder routes allow a valid key to exercise its account's authority whatever its scopes say. The documented exception is Cohort run/cancel/operational health: a restrictive key must carry inference:execute; an empty-scope legacy key retains the legacy account-wide behavior. Do not infer enforcement on any other route unless its reference says so.

Treat a key as holding your account's full authority. If you need a narrower blast radius today, the lever that works is the account boundary, not the scope list.

Outside that Cohort exception, the gateway may compute and record a shadow scope verdict for diagnostics, but it does not deny requests and is not a customer authorization boundary. Build against account-wide key authority unless the specific route contract says it enforces a scope.

Rate limits​

Rate limiting is enforced at the infrastructure layer (Nginx). When a limit is exceeded, requests receive HTTP 429. Per-endpoint limits (rate_limit_rpm) exist in the platform, but:

Rate-limit response contract

Rate-limit response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are not emitted today. Published tiers describe commercial plans on colabhive.com/pricing, not an API-emitted contract — no endpoint returns your plan or its limits today.