Bring your own key
Connect your own provider accounts over the API so their calls bill your provider directly, with no markup.
Connect an account
POST creates a new account under a unique setup_alias (1 to 63 lowercase letters, digits, hyphens or underscores, unique across all providers in your org). The key is verified on save; read check.status. Use inference keys as secret; OpenAI and Anthropic admin keys go only in the optional spend_secret (spend reads). Secrets are write-only: reads show the last four characters. Concepts and plan rules: BYOK.
| Response | Meaning |
|---|---|
409 account_exists | Alias taken; choose another. Never PUT over it |
402 pro_required | A first connection needs Pro; an org already holding one keeps connecting |
spend_error present | Key saved, spend key failed; retry only that alias with PUT |
check.status not valid | Read check.status_detail.remediation |
/api/orgs/{org_id}/provider-connections/{provider}GET/api/orgs/{org_id}/provider-connectionscurl https://api.experientiallabs.ai/api/orgs/ORG_ID/provider-connections \
-H "Authorization: Bearer YOUR_API_KEY"
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 '{"setup_alias": "openai-work", "secret": "sk-...", "config": {}}'Providers and config
String-secret providers need only secret: openai, anthropic, gemini, xai, deepseek, openrouter, mistral, together, zai, qwen, cerebras and others. These need config (or a token pair) and are easiest in Settings, Connections:
| Provider | Extra fields |
|---|---|
azure_openai | config.endpoint, config.api_version, config.deployments (model to deployment name) |
bedrock | AWS credentials and region |
vertex | Service account and project |
fireworks | Account config |
modal | Token pair as secret |
Each Azure account keeps its own endpoint and deployment map; adding one never replaces another.
{
"setup_alias": "azure-secondary",
"secret": "YOUR_AZURE_KEY",
"config": {
"endpoint": "https://second-resource.openai.azure.com",
"api_version": "v1",
"deployments": {"gpt-4o-mini": "my-deployment"}
}
}Use it on a model
Saving a key changes no routing. A key serves a model once you choose it on that model's waterfall (Use this account in the app, or PUT /api/models/{slug}/waterfall with your BYOK rung). With no custom order, your key takes the place of the platform rung for that provider. To keep it as a fallback only, place it below the platform rung. A BYOK call reports usage.cost: 0, usage.is_byok: true and the provider's charge in usage.cost_details.upstream_inference_cost. An unhealthy key is skipped and its traffic never moves onto platform credit silently.
/api/models/{slug}/waterfallGET/api/models/{slug}/providerscurl https://api.experientiallabs.ai/api/models/claude-opus-5/providers \
-H "Authorization: Bearer YOUR_API_KEY" \
| jq '.providers[] | select(.connection_alias != null) | {connection_alias, provider_connection_id}'
curl -X PUT https://api.experientiallabs.ai/api/models/claude-opus-5/waterfall \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model_provider_ids": ["byok:CONNECTION_ID"]}'Check, rotate, disconnect
Address one account with ?setup_alias=. PUT deliberately rotates the named account (send its exact setup_alias and config).
/api/orgs/{org_id}/provider-connections/{provider}/checkPUT/api/orgs/{org_id}/provider-connections/{provider}DELETE/api/orgs/{org_id}/provider-connections/{provider}POST/api/orgs/{org_id}/provider-connections/{provider}/spend-refreshB=https://api.experientiallabs.ai/api/orgs/ORG_ID/provider-connections
curl -X POST "$B/openai/check?setup_alias=openai-work" -H "Authorization: Bearer YOUR_API_KEY"
curl -X PUT "$B/openai" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"setup_alias": "openai-work", "secret": "sk-new...", "config": {}}'
curl -X DELETE "$B/openai?setup_alias=openai-work" -H "Authorization: Bearer YOUR_API_KEY"Several accounts: priority and failover
With several accounts the org pool tries them by priority (lower first). exhaustion_fallback and ratelimit_failover let the pool move past an exhausted or rate-limited account. failover_only_on makes an account a fallback for listed failures only (null resets it). reorder assigns priorities from an ordered list.
/api/orgs/{org_id}/provider-connections/{provider}/accounts/{setup_alias}/routingPOST/api/orgs/{org_id}/provider-connections/reorderGET/api/orgs/{org_id}/provider-connections/accounts/usageB=https://api.experientiallabs.ai/api/orgs/ORG_ID/provider-connections
curl -X POST "$B/reorder" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"order": [{"provider": "openai", "setup_alias": "openai-work"},
{"provider": "azure_openai", "setup_alias": "azure-secondary"}]}'
curl -X POST "$B/openai/accounts/openai-work/routing" -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" -d '{"ratelimit_failover": true}'
curl "$B/accounts/usage" -H "Authorization: Bearer YOUR_API_KEY"