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 — not enforced yet​

API keys carry a scopes field, and it is returned when you inspect a key. Granular scope enforcement is not applied: today a valid API key reaches every endpoint its account reaches, whatever its scopes say. Do not rely on scopes to limit a key's reach.

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.

Enforcement is being prepared, and deliberately not by flipping a switch. The gateway currently computes what each request would require and records the verdict without denying anything, so the keys that a sudden rollout would break can be identified and fixed first. When enforcement does arrive it will be announced ahead of time, not shipped as a silent change — a key that stops working without warning is an outage on your side.

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:

Roadmap

Rate-limit response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) and published per-plan tiers are not yet available. Do not parse them — they are not emitted today.