Bring your own key (BYOK)

With BYOK, calls made with a BYOK-enabled Belarel key run on your organization’s own provider key. You pay the provider directly for the model usage; Belarel bills only a platform fee. Everything else stays the same: admission, policies, caps, tags, the request journal and the belarel block.

Supported providers and models

BYOK is available for OpenAI and Anthropic language models served through Belarel’s routing layer. In GET /v1/models, belarel.byok_available: true marks the models that can run on your own key.

BYOK does not apply to:

• Embeddings. POST /v1/embeddings runs on the platform embedder; a BYOK key gets 400 byok_unavailable there (and embedding models are not listed for it).
• Other models. A model that is not an OpenAI or Anthropic model served this way answers 400 byok_unavailable.
• Sandbox keys. A bel_test_… key never reaches a provider, so BYOK has no effect on it.

Set it up

BYOK is configured by an owner or admin in your organization dashboard, not through the public API.

1. Add your provider key. In Governance → API keys → Provider keys (BYOK), choose the provider and paste your key, then select Check and save.

2. Let Belarel validate it. Before storing anything, Belarel checks the key with the provider by listing its models, a call that costs nothing. A key the provider refuses is rejected; if the provider cannot be reached, nothing is stored and you can retry.

3. Create a BYOK API key. When you create a Belarel key in Governance → API keys, enable Bill on our own provider keys (BYOK). Sub-keys created from a BYOK key are BYOK too: they always use the same payment mode as their parent.

4. Call the API as usual. No request changes. The response tells you the call ran on your key (see below).

Your organization has at most one active key per provider. Saving a new one replaces the previous one, which is revoked. You can revoke a provider key from the same tab at any time.

How your provider key is stored

• It is validated with the provider before it is stored.
• It is encrypted (AES-256-GCM) before it reaches the database, and only the inference service reads it, at the moment it serves a call.
• It is never returned by any screen or API after you save it. The dashboard shows only a hint: its first characters and its last four (for example sk-…ab12).

How billing works

On a BYOK call, the provider bills your provider account for the tokens. Belarel bills a platform fee: a percentage of the model’s catalog cost for that call, at the rate set in your organization’s price list. The fee is what the belarel.cost block reports:

"belarel": {
  "request_id": "req_6f1c…",
  "model_served": "<model-id>",
  "cost": { "usd": 0.00004, "credits": 0.04, "source": "estimated", "billing": "byok" },
  "policy": {
    "decisions": [
      { "rule": "org_api_catalog", "verdict": "allow", "detail": "residency any" },
      { "rule": "credential_mode", "verdict": "allow", "detail": "byok openai" }
    ]
  },
  "data_mode": "standard"
}

• cost.billing: "byok" means the call ran on your provider key, and usd / credits are the platform fee, not the model cost.
• The fee counts against your key’s spend caps and your organization’s budgets like any other cost.
• Admission is at full price. Before the call, the reservation against your key’s caps, your organization’s credit check and your contract’s maximum cost per request all use the full-price worst-case estimate — the model’s listed price, not the fee. Only settlement is at the fee. A BYOK call therefore needs room for its full-price estimate, and a call that fails without reported usage settles at that full-price estimate (or its input part) against the key’s caps — not billed, like any failed call.
• If your organization’s price list has no fee defined for BYOK, BYOK calls are refused with 503 admission_unavailable rather than served for free. Contact your Belarel administrator.

Note

Your provider’s own limits apply to BYOK calls. If your provider key is refused, rate-limited or out of quota at the provider, the call fails. When the provider answers 401, 403 or 429 to a BYOK call, Belarel does not count that failure as an outage of the model, so it does not affect anyone else’s traffic. Other provider failures count like those of any other call.

Errors

Code	HTTP	Meaning	What to do
byok_unavailable	400	The model (or embeddings) cannot run on your own provider key.	Pick a model with byok_available: true, or use a non-BYOK key for this call.
byok_credential_rejected	400	Your provider refused your organization’s provider key during the call.	An owner or admin checks or replaces the provider key under Provider keys (BYOK). Do not retry as is.
provider_credential_missing	409	The Belarel key is BYOK, but your organization has no active key for this model’s provider.	An owner or admin adds the provider key under Provider keys (BYOK).
admission_unavailable	503	No BYOK fee is defined for your organization (the message says BYOK is not priced), or your provider key could not be read.	A missing fee is not fixed by a retry, though the answer carries Retry-After: 60 and the official SDKs retry it on their own — contact your Belarel administrator. An unreadable key: retry after Retry-After (5 s).

When your provider refuses your own key during a call — revoked, invalid, or without permission for the model — the call fails with 400 byok_credential_rejected: fix the key in your BYOK settings, since retrying will not help. When your provider rate-limits the call, you receive 429 rate_limited; other provider failures surface as 503 service_unavailable. A provider refusal that arrives before any output costs you nothing. If the stream had already started, the same code arrives in an in-band error event. See Errors & debugging.

See also

• Data modes
• Cost & usage
• Budgets & caps
• Errors & debugging