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.

ResponseMeaning
409 account_existsAlias taken; choose another. Never PUT over it
402 pro_requiredA first connection needs Pro; an org already holding one keeps connecting
spend_error presentKey saved, spend key failed; retry only that alias with PUT
check.status not validRead check.status_detail.remediation
POST/api/orgs/{org_id}/provider-connections/{provider}GET/api/orgs/{org_id}/provider-connections
curl 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:

ProviderExtra fields
azure_openaiconfig.endpoint, config.api_version, config.deployments (model to deployment name)
bedrockAWS credentials and region
vertexService account and project
fireworksAccount config
modalToken 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.

PUT/api/models/{slug}/waterfallGET/api/models/{slug}/providers
curl 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"]}'
B=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.

POST/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/usage
B=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"