Providers
Bring your own key
Run catalog models on your own provider account, with no markup and your key placed in the waterfall.
Bring your own key (BYOK) connects your own provider account, so requests for that provider's models run on your key and your provider bills you directly. These calls draw no credits and do not count against your rate-limit tier. You keep one API, one key and one usage view across every provider.
Who can add a key
| Organization | New connection | Manage, rotate, reorder, disconnect |
|---|---|---|
| Pro, Max or Ultra | Yes | Yes |
| Free, already has a connection | Yes | Yes |
| Free, no connection yet | 402 pro_required (free-tier provider accounts such as Groq or NVIDIA NIM connect on every plan) | Not applicable |
Keys already connected keep serving on every plan. Disconnecting your last account on Free ends the exception.
POST adds a new account under a unique alias; PUT rotates the named account's key.
/api/orgs/{org_id}/provider-connections/{provider}PUT/api/orgs/{org_id}/provider-connections/{provider}curl -X POST https://api.experientiallabs.ai/api/orgs/$ORG_ID/provider-connections/openai \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"secret": "sk-...", "setup_alias": "main"}'The secret goes to an encrypted vault. Only its last four characters are ever shown.
How your key routes
| Rule | Effect |
|---|---|
| Default | Your key takes the platform rung's place for that provider, at the same position |
| As a fallback only | Turn the platform rung on and drag your key below it on the model page |
| Fallback rules | A key can be limited to serve only after chosen failures; it is then never dialled first |
| Key rejected or out of quota | Its rung is skipped until a check passes or the cooldown ends |
| Provider throttles one model | Only that model's rung sits out briefly; the key keeps serving others |
| All your rungs fail, no platform rung on | The request fails and names the account |
A skipped key is never silently replaced by platform credit: the request continues only on rungs you have turned on. Your provider policy applies to your own rungs too.
{
"provider": "openai",
"usage": {
"cost": 0,
"is_byok": true,
"cost_details": { "upstream_inference_cost": 0.0123 }
}
}Usage events mark these lane: "pass_through".
Several accounts per provider
Connect more than one account for a provider, each with its own alias. They form a pool: traffic runs on the first account in your order and moves to the next when one runs out of quota. A single throttle never rotates accounts, because switching would lose the prompt cache built on the current one.
GET/api/orgs/{org_id}/provider-connectionsPOST/api/orgs/{org_id}/provider-connections/{provider}/check| Pool | |
|---|---|
| Order | Drag on the Credits page |
| Rotates on | Out of quota |
| Does not rotate on | A single throttle |
| Re-admitted by | A successful key check |
Pin a model to your key
Some models are served only on your own key (for example Claude on Azure). To pin a request to your account, take your account's route_id from the model's providers listing and send it in gateway.routing. See Routing and the BYOK guide.
{
"model": "claude-sonnet-5.5",
"messages": [{ "role": "user", "content": "Hi" }],
"gateway": { "routing": { "route_id": "route_...", "allow_fallbacks": false } }
}