BYOK

Bring your own API Keys

OpenRouter supports both OpenRouter credits and the option to bring your own provider keys (BYOK).

When you use OpenRouter credits, your rate limits for each provider are managed by OpenRouter.

Using provider keys enables direct control over rate limits and costs via your provider account.

Your provider keys are securely encrypted and used for all requests routed through the specified provider.

Manage keys in your workspace BYOK settings.

The cost of using custom provider keys on OpenRouter is 5% of what the same model/provider would cost normally on OpenRouter and will be deducted from your OpenRouter credits. This fee is waived for the first 1M BYOK requests per-month.

Key Priority and Fallback

Each BYOK key belongs to one of two sections:

• Prioritized — Attempted in order, before falling back to OpenRouter endpoints. Use this section for your primary provider keys.
• Fallback — Tried only after OpenRouter endpoints have been attempted, in order. Use this section for backup keys you only want used as a last resort.

You can drag keys between sections on the provider detail page (e.g. /workspaces/default/byok/openai).

By default, if all keys in both sections encounter a rate limit or failure, OpenRouter will fall back to using shared OpenRouter endpoints.

You can toggle “Always use for this provider” on individual prioritized keys to prevent any fallback to OpenRouter endpoints. When enabled, OpenRouter will only use your keys for requests to that provider, which may result in rate limit errors if your keys are exhausted, but ensures all requests go through your account.

When you have multiple keys for the same provider, OpenRouter tries them in priority order (see Multiple BYOK Keys). If the first key fails, it falls through to the next matching key before falling back to shared capacity.

BYOK with Provider Ordering

When you combine BYOK keys with provider ordering, OpenRouter always prioritizes BYOK endpoints first, regardless of where that provider appears in your specified order. After all BYOK endpoints are exhausted, OpenRouter falls back to shared capacity in the order you specified.

This means BYOK keys effectively override your provider ordering for the initial routing attempts. There is currently no way to change this behavior.

For example, if you have BYOK keys for Amazon Bedrock, Google Vertex AI, and Anthropic, and you send a request with:

1
{
2
  "provider": {
3
    "allow_fallbacks": true,
4
    "order": ["amazon-bedrock", "google-vertex", "anthropic"]
5
  }
6
}

The routing order will be:

1. Amazon Bedrock (your BYOK key)
2. Google Vertex AI (your BYOK key)
3. Anthropic (your BYOK key)
4. Amazon Bedrock (OpenRouter’s shared capacity)
5. Google Vertex AI (OpenRouter’s shared capacity)
6. Anthropic (OpenRouter’s shared capacity)

Partial BYOK with Provider Ordering

If you only have a BYOK key for some of the providers in your order, the BYOK provider is still tried first. For example, if you specify order: ["amazon-bedrock", "google-vertex"] but only have a BYOK key for Google Vertex AI:

1
{
2
  "provider": {
3
    "allow_fallbacks": true,
4
    "order": ["amazon-bedrock", "google-vertex"]
5
  }
6
}

The routing order will be:

1. Google Vertex AI (your BYOK key)
2. Amazon Bedrock (OpenRouter’s shared capacity)
3. Google Vertex AI (OpenRouter’s shared capacity)

Note that even though Amazon Bedrock is listed first in the order array, the Google Vertex AI BYOK endpoint takes priority.

If you want to prevent fallback to OpenRouter endpoints entirely, enable “Always use for this provider” on your BYOK keys in your workspace BYOK settings.

Multiple BYOK Keys for the Same Provider

You can configure multiple BYOK keys for the same provider. All matching keys are used for routing, and each key produces its own endpoint copy that is pinned to that specific key throughout the request lifecycle.

Priority Order

Keys are tried in the order you define, within their section. Prioritized keys are tried first, then OpenRouter endpoints, then Fallback keys. You can reorder keys via drag-and-drop on the provider detail page (e.g. /workspaces/default/byok/openai). When a key fails (e.g. rate limit or error), OpenRouter falls through to the next matching key.

For example, if you have three OpenAI keys:

• Prioritized section: First key, Second key
• Fallback section: Backup key

OpenRouter will try: First key, then Second key, then OpenRouter endpoints, then Backup key.

Key Filters

Each BYOK key supports optional filters to control when it is used:

• Model filter — Restrict the key to specific models (e.g. only use this key for openai/gpt-4o). When set, the key is only used for requests to the listed models. Other models for the same provider will skip this key.
• API key filter — Restrict which of your OpenRouter API keys can use this BYOK key. Useful for isolating BYOK usage to specific applications or environments.
• Member filter — Restrict which workspace members can use this BYOK key. Useful for giving different team members access to different provider accounts.

Filters are evaluated before routing. A key is only used when all of its active filters match the current request. If no filters are set, the key is available to all models, API keys, and members.

Combining Filters with Multiple Keys

Filters and multiple keys work together to enable flexible routing strategies. For example:

• Key A: OpenAI, model filter = [openai/gpt-4o], “Always use for this provider” enabled
• Key B: OpenAI, no model filter (matches all models)

In this setup:

• Requests for openai/gpt-4o try Key A first, then Key B if Key A fails (shared capacity is skipped because “Always use for this provider” is enabled on Key A)
• Requests for other OpenAI models (e.g. openai/gpt-4o-mini) use Key B only, with shared capacity as fallback

Key Names

Each key can be given an optional name (e.g. “Production”, “Team A”, “GPT-4 only”) to help organize keys when you have multiple keys for the same provider.

Azure API Keys

Azure has two resource types, each using a different domain:

• Azure AI Foundry — resources at *.services.ai.azure.com. Uses the model catalog and does not require per-model deployments.
• Azure OpenAI — resources at *.openai.azure.com. Requires explicit per-model deployments.

Foundry Configuration (Recommended)

The simplest way to configure Azure BYOK is with a Foundry configuration. Provide your API key, resource name, and resource type:

1
[
2
  {
3
    "api_key": "your-azure-api-key",
4
    "resource_name": "your-resource-name",
5
    "resource_type": "ai_foundry"
6
  }
7
]

• api_key: Your Azure API key, found under “Keys and Endpoint” in the Azure portal.
• resource_name: The name of your Azure resource (the subdomain portion of your endpoint URL).
• resource_type: Either "ai_foundry" for Azure AI Foundry resources (*.services.ai.azure.com) or "openai" for Azure OpenAI resources (*.openai.azure.com). Defaults to "openai" if omitted.

This configuration works for all models available in your Azure resource — no per-model setup required.

Per-Deployment Configuration (Legacy)

For more control, you can specify individual deployments with full endpoint URLs:

1
[
2
  {
3
    "model_slug": "mistralai/mistral-large",
4
    "endpoint_url": "https://example-project.openai.azure.com/openai/deployments/mistral-large/chat/completions?api-version=2024-08-01-preview",
5
    "api_key": "your-azure-api-key",
6
    "model_id": "mistral-large"
7
  },
8
  {
9
    "model_slug": "openai/gpt-5.2",
10
    "endpoint_url": "https://example-project.openai.azure.com/openai/deployments/gpt-5.2/chat/completions?api-version=2024-08-01-preview",
11
    "api_key": "your-azure-api-key",
12
    "model_id": "gpt-5.2"
13
  }
14
]

Each per-deployment configuration requires:

1. endpoint_url: The full deployment endpoint URL including /chat/completions and the API version. See the Azure Foundry documentation for details.
2. api_key: Your Azure API key.
3. model_id: The name of your model deployment in Azure.
4. model_slug: The OpenRouter model identifier you want to use this key for.

You can mix Foundry and per-deployment configurations in the same array. Per-deployment configs take priority when a matching model slug is found.

AWS Bedrock API Keys

To use Amazon Bedrock with OpenRouter, you can authenticate using either Bedrock API keys or traditional AWS credentials.

Option 1: Bedrock API Keys (Recommended)

Amazon Bedrock API keys provide a simpler authentication method. Simply provide your Bedrock API key as a string:

your-bedrock-api-key-here

Note: Bedrock API keys are tied to a specific AWS region and cannot be used to change regions. If you need to use models in different regions, use the AWS credentials option below.

You can generate Bedrock API keys in the AWS Management Console. Learn more in the Amazon Bedrock API keys documentation.

Option 2: AWS Credentials

Alternatively, you can use traditional AWS credentials in JSON format. This option allows you to specify the region and provides more flexibility:

1
{
2
  "accessKeyId": "your-aws-access-key-id",
3
  "secretAccessKey": "your-aws-secret-access-key",
4
  "region": "your-aws-region"
5
}

You can find these values in your AWS account:

1. accessKeyId: This is your AWS Access Key ID. You can create or find your access keys in the AWS Management Console under “Security Credentials” in your AWS account.

2. secretAccessKey: This is your AWS Secret Access Key, which is provided when you create an access key.

3. region: The AWS region where your Amazon Bedrock models are deployed (e.g., “us-east-1”, “us-west-2”).

Make sure your AWS IAM user or role has the necessary permissions to access Amazon Bedrock services. At minimum, you’ll need permissions for:

• bedrock:InvokeModel
• bedrock:InvokeModelWithResponseStream (for streaming responses)

Example IAM policy:

1
{
2
  "Version": "2012-10-17",
3
  "Statement": [
4
    {
5
      "Effect": "Allow",
6
      "Action": [
7
        "bedrock:InvokeModel",
8
        "bedrock:InvokeModelWithResponseStream"
9
      ],
10
      "Resource": "*"
11
    }
12
  ]
13
}

For enhanced security, we recommend creating dedicated IAM users with limited permissions specifically for use with OpenRouter.

Learn more in the AWS Bedrock Getting Started with the API documentation, IAM Permissions Setup guide, or the AWS Bedrock API Reference.

Google Vertex API Keys

To use Google Vertex AI with OpenRouter, you’ll need to provide your Google Cloud service account key in JSON format. The service account key should include all standard Google Cloud service account fields, with an optional region field for specifying the deployment region.

1
{
2
  "type": "service_account",
3
  "project_id": "your-project-id",
4
  "private_key_id": "your-private-key-id",
5
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
6
  "client_email": "your-service-account@your-project.iam.gserviceaccount.com",
7
  "client_id": "your-client-id",
8
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
9
  "token_uri": "https://oauth2.googleapis.com/token",
10
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
11
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/your-service-account@your-project.iam.gserviceaccount.com",
12
  "universe_domain": "googleapis.com",
13
  "region": "global"
14
}

You can find these values in your Google Cloud Console:

1. Service Account Key: Navigate to the Google Cloud Console, go to “IAM & Admin” > “Service Accounts”, select your service account, and create/download a JSON key.

2. region (optional): Specify the region for your Vertex AI deployment. Use "global" to allow requests to run in any available region, or specify a specific region like "us-central1" or "europe-west1".

Make sure your service account has the necessary permissions to access Vertex AI services:

• aiplatform.endpoints.predict

Example IAM policy:

1
{
2
  "bindings": [
3
    {
4
      "role": "roles/aiplatform.user",
5
      "members": [
6
        "serviceAccount:your-service-account@your-project.iam.gserviceaccount.com"
7
      ]
8
    }
9
  ]
10
}

Learn more in the Google Cloud Vertex AI documentation and Service Account setup guide.

Debugging BYOK Issues

If your BYOK requests fail, you can debug the issue by viewing provider responses on the Activity page.

Viewing Provider Responses

1. Navigate to your Activity page in the OpenRouter dashboard.
2. Find the generation you want to debug and click on it to view the details.
3. Click “View Raw Metadata” to display the raw metadata in JSON format.
4. In the JSON, look for the provider_responses field, which shows the HTTP status code from each provider attempt.

The provider_responses field contains an array of responses from each provider attempted during routing. Each entry includes the provider name and HTTP status code, which can help you identify permission issues, rate limits, or other errors.

Common BYOK Error Codes

When debugging BYOK issues, look for these common HTTP status codes in the provider responses:

• 400 Bad Request: The request format was invalid for the provider. Check that your model and key configuration is correct.
• 401 Unauthorized: Your API key is invalid or has been revoked. Verify your key in your provider’s console.
• 403 Forbidden: Your API key doesn’t have permission to access the requested resource. For AWS Bedrock, ensure your IAM policy includes the required bedrock:InvokeModel permissions. For Google Vertex, verify your service account has aiplatform.endpoints.predict permissions.
• 429 Too Many Requests: You’ve hit the rate limit on your provider account. Check your provider’s rate limit settings or wait before retrying.
• 500 Server Error: The provider encountered an internal error. This is typically a temporary issue on the provider’s side.

Debugging Permission Issues

If you encounter 403 errors with BYOK, the issue is often related to permissions. For AWS Bedrock, verify that:

1. Your IAM user/role has the bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream permissions.
2. The model you’re trying to access is enabled in your AWS account for the specified region.
3. Your credentials (access key and secret) are correct and active.

For Google Vertex, verify that your service account has aiplatform.endpoints.predict permissions.

You can test your provider permissions directly in the provider’s console (AWS Console, Google Cloud Console, etc.) by attempting to invoke the model there first.