Bring your own key (BYOK)

You register a provider key once, on your workspace. From then on, whenever a request resolves to that provider, the gateway uses your key to call it — you do not put the provider key in the request. Your unoblox ub-gw-… key is still the only credential your code sends.

The simplest path is the developer portal — add a credential under BYOK for the provider you want. Under the hood these are control-plane routes, authenticated with your dashboard session (not a ub-gw-… key):

POST /workspaces/{workspace_id}/byok
{
  "provider_slug": "openai",
  "label": "Prod OpenAI key",
  "secret": "sk-…"          // write-only: encrypted at rest, never returned
}

The secret is write-only: it is encrypted at rest immediately and never returned by any read. Listing credentials returns metadata only — provider_slug, label, a display last4, and enabled. Rotate by registering again; disable or delete to stop using it.

Nothing changes in the request. Send it exactly as you normally would — the gateway decides per request whether a BYOK credential applies, based on the provider that routing selects:

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": "Hello" }]
  }'

You can confirm a request ran on your key: its generation record carries byok: true. Look it up with the generation endpoint using the x-generation-id from the response.

For a BYOK request, unoblox does not charge the full token price. Instead it meters a 2% overage (basis points of the upstream cost) on the request's list price, debited from your prepaid ₹ balance; the provider charges your own account for the actual tokens. A full-price hold is placed when the request starts and the excess is released when the request settles, so your available balance briefly reflects the full price before dropping to the overage.

A BYOK request is never refused because unoblox can't see what your provider billed you for it. For embeddings, when the upstream response omits a per-call usage.cost figure, unoblox computes your overage from the model's own published (catalog) list price for the tokens you actually used instead — the same overage rate, applied to a different, always-available cost basis. If a model has no published price either, the request still goes through and that call's overage is 0. Either way, the vectors you requested are returned; the fee basis only changes what (if anything) is debited for it.

Some catalog models are flagged freemium — free to call while a workspace's balance stays at or above an admin-set minimum, subject to a fair-use rate limit. None of that applies to BYOK. A BYOK request is an independent route, decided before any freemium check runs: it is never rate-limited by the freemium fair-use limit, never gated by the freemium balance requirement, and never restricted for being a freemium model. It always routes to your own credential and bills only the BYOK overage above — on a freemium model or any other.

By default BYOK spend is small (just the overage), but you can still make it count against a key's spend cap. Set include_byok_in_limit when you create the key so BYOK requests draw against its limit_minor window like any other request. See Authentication for per-key controls.

Two different situations get two different outcomes:

If your workload depends on BYOK never silently running at full price, keep your credential’s enabled status and validity under your own monitoring rather than relying on the request itself to fail when it is missing.