Skip to main content
Bring Your Own Key (BYOK) lets you connect your own provider API keys to Inworld’s LLM Router. This can be useful if you want to manage rate limits directly with your provider or use existing credits.
Current supported providers include OpenAI, Anthropic, Google Vertex AI, Google AI Studio, Cerebras, DeepInfra, Fireworks, Mistral, Groq, and xAI. See all models via the List Models endpoint. Contact us to request a provider or model to be supported.

​
How it works

  • Scoped per workspace: Provider credentials are tied to the workspace where they are configured.
  • One key per provider: Each workspace supports one API key per provider.
  • Automatic fallback: If your key fails (invalid, expired, or rate-limited), Inworld automatically falls back to its own managed credentials to ensure uptime. When this happens, you’ll see "credential_type": "system" in the response.
  • Billing: Your provider bills you directly for usage on your key. Inworld applies a percentage fee for BYOK usage, which is currently waived.

​
Setup

1

Add your provider key

Navigate to the API Keys page in Inworld Studio and click Add third-party key. Select your provider and enter your API key.
2

Save credentials

When you save, Inworld sends a test request using your key to verify it returns a valid response. If the validation succeeds, your key is stored securely.If validation fails, double-check that:
  • The API key is correct and active.
  • The key has the necessary permissions on the provider side.
  • Your provider account has available credits or an active billing plan.

​
Usage

​
Verifying which key was used

Send a regular chat completion request: 
curl -X POST 'https://api.inworld.ai/v1/chat/completions' \
  -H 'Authorization: Basic <your-inworld-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
The response metadata.attempts array includes a credential_type field for each attempt:
ValueMeaning
byokYour own key was used.
systemInworld-managed key was used (automatic fallback).
Example response when BYOK is active: 
{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": { "content": "Hello!", "role": "assistant" }
    }
  ],
  "metadata": {
    "attempts": [
      {
        "credential_type": "byok",
        "model": "openai/gpt-4o",
        "success": true,
        "time_to_first_token_ms": 756
      }
    ]
  }
}

​
Runtime credentials

Instead of saving your key in the dashboard, you can pass provider credentials directly in the request body using the provider_credentials field. This is useful for per-request key selection or for testing a key before saving it. 
curl -X POST 'https://api.inworld.ai/v1/chat/completions' \
  -H 'Authorization: Basic <your-inworld-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "xai/grok-3-mini",
    "messages": [{"role": "user", "content": "Say hello in 3 words"}],
    "provider_credentials": {
      "xai": {
        "api_key": "<your-xai-key>",
        "fallback_to_inworld": true
      }
    }
  }'

​
Provider filtering

You can restrict auto-routing to only use models from specific providers. This is useful when you have a BYOK key for a provider and want to ensure all requests go through it. See Provider Routing for more routing options. 
curl -X POST 'https://api.inworld.ai/v1/chat/completions' \
  -H 'Authorization: Basic <your-inworld-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model_id": "auto",
    "models": ["openai"],
    "messages": [{"role": "user", "content": "Hello"}]
  }'