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

OrganizationNew connectionManage, rotate, reorder, disconnect
Pro, Max or UltraYesYes
Free, already has a connectionYesYes
Free, no connection yet402 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.

POST/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

RuleEffect
DefaultYour key takes the platform rung's place for that provider, at the same position
As a fallback onlyTurn the platform rung on and drag your key below it on the model page
Fallback rulesA key can be limited to serve only after chosen failures; it is then never dialled first
Key rejected or out of quotaIts rung is skipped until a check passes or the cooldown ends
Provider throttles one modelOnly that model's rung sits out briefly; the key keeps serving others
All your rungs fail, no platform rung onThe 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
OrderDrag on the Credits page
Rotates onOut of quota
Does not rotate onA single throttle
Re-admitted byA 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 } }
}