How it works
Save a provider key
On the Models page, add a key for any of
OpenAI, Anthropic, Google, Groq, xAI, Mistral, DeepSeek, or Cohere. Optionally
set a custom base URL (e.g. an Azure endpoint).
Orbitrage encrypts it
Keys are encrypted at rest with AES-256-GCM. The plaintext is never logged and
never returned to the browser again.
Seeing the split
Every call surfaces whether BYOK applied — in the dashboard (byok=true) and in
the response headers:
| Header | Value |
|---|---|
X-Orbitrage-BYOK | The provider name used (e.g. anthropic), or pooled. |
X-Orbitrage-BYOK-Reason | Why BYOK did or didn’t apply (see below). |
X-Orbitrage-BYOK-Reason values:
| Reason | Meaning |
|---|---|
applied | Your key was found, enabled, and used. |
applied-with-model-rewrite | Used, with the upstream model id adjusted. |
no-key-for-provider | The model maps to a provider you haven’t saved a key for. |
key-disabled | You saved the key but toggled it off. |
unmapped-model | The model doesn’t map to a BYOK provider. |
decrypt-failed | The stored key couldn’t be decrypted (re-save it). |
Pooled fallback
Enable an org-level setting so a failed BYOK provider call silently retries on pooled credits to keep production up. Turn it off for strict BYOK (fail rather than spend pooled credits).BYOK vs. pooled credits
Pooled credits
Orbitrage bills your credit balance at the upstream price plus a 2.5% markup.
Nothing to configure — works out of the box.
BYOK
Your provider bills you directly at your negotiated rates. Orbitrage credits
are untouched. You still get full routing and observability.
Security
- Keys are encrypted with AES-256-GCM using a server-only key; plaintext is never stored or logged.
- Decryption happens in-memory at the gateway, per request, only for the matching provider.
- Provider keys are scoped to your organization and protected by row-level security — no other org can read them.