Guides

Authentication

Every inference request is authenticated with a workspace-scoped API key, sent as a bearer token. Keys carry their own limits — scopes, rate limits and spend caps — so you can hand one to a service without handing it your whole account.

Bearer keys

unoblox API keys look like ub-gw-{user}-{secret}. Send the key in the Authorization header:

header

Authorization: Bearer ub-gw-user_xxx-xxxxxxxxxxxxxxxx

The secret is shown once at creation — only its hash is stored. If you lose it, revoke the key and mint a new one from API Keys.

Per-key controls

Each key can be constrained independently when you create it:

Field	Purpose
model_scope	Restrict the key to specific model slugs.
cidr_allow	Only accept requests from these IP ranges.
rpm	Requests-per-minute rate limit for this key.
limit_minor	Hard spend cap in paise over the reset window.
limit_reset	When the spend cap resets (e.g. monthly).
expires_at_ms	Auto-expiry timestamp for the key.
include_byok_in_limit	Count BYOK requests against this key's spend cap.

A revoked or expired key fails closed with authentication (401); over the rpm cap gets rate_limit_exceeded (429). Over the key’s own limit_minor spend cap is a distinct case — payment_required (402), with x-unoblox-refusal: spend_limit_exceeded on the response — never budget_exceeded, which is a separate, workspace/organization-level budget (see Errors). Every case is a typed error, never a generic 4xx.

Workspaces

Keys belong to a workspace — an isolated environment that scopes keys, credentials, usage and budgets. Requests bill against the workspace's shared credit balance. Switch or create workspaces in the developer portal. Pick a real model from /models before running this:

curl

curl https://api.unoblox.ai/v1/chat/completions \
  -H "Authorization: Bearer $UNOBLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<model-id>", "messages": [{"role":"user","content":"Hi"}] }'

Control-plane vs. inference

The dashboard API (accounts, keys, usage) authenticates with an opaque ubs_… session token and enforces MFA and step-up on sensitive actions. Inference through the gateway uses the ub-gw-… key above. The two are deliberately separate envelopes.

Treat keys like passwords.

Never commit them or ship them in client-side code. Prefer server-side use, narrow scopes, and short expiries for anything shared.

PreviousQuickstart NextModels