> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Load Balance

> Intelligent API key management with weighted load balancing, model-specific filtering, and automatic failover. Distribute traffic across multiple keys for optimal performance and reliability.

## Weighted Load Balancing

Bifrost uses weighted random selection to distribute requests across multiple keys. This allows you to:

**Control Traffic Distribution:**

* Assign higher weights to premium keys with better rate limits
* Balance between production and backup keys
* Gradually migrate traffic during key rotation

**Weight Calculation Example:**

```
Key 1: Weight 0.7 (70% probability)
Key 2: Weight 0.3 (30% probability)
Total Weight: 1.0

Random selection ensures statistical distribution over time
```

**Algorithm Details:**

1. Calculate total weight of all eligible keys
2. Generate random number between 0 and total weight
3. Select key based on cumulative weight ranges
4. If selected key fails, automatic fallback to next available key

## Model Whitelisting and Filtering

Keys can be restricted to specific models for access control and cost management:

**Model Filtering Logic:**

* **Empty `models` array (`[]`)**: Denies ALL models (deny-by-default, v1.5.0+) - use `["*"]` to allow all
* **Populated `models` array**: Key only supports listed models
* **`blacklisted_models`**: Optional per-key denylist. If non-empty and the requested model appears in it, the key is excluded-even if that model is also in `models` (denylist wins over the allowlist)
* **Model mismatch**: Key is excluded from selection for that request

**Use Cases:**

* **Premium Models**: Dedicated keys for expensive models (GPT-4, Claude-3)
* **Team Separation**: Different keys for different teams or projects
* **Cost Control**: Restrict access to specific model tiers
* **Compliance**: Separate keys for different security requirements
* **Denylist**: Block specific models on a key

**Example Model Restrictions:**

Each key is created individually via `POST /api/providers/{provider}/keys`:

```json theme={null}
// Premium-only key
{
  "name": "openai-pre-key-1",
  "value": "premium-key",
  "models": ["gpt-4o", "o1-preview"],
  "weight": 1.0
}

// Standard-only key
{
  "name": "openai-std-key-1",
  "value": "standard-key",
  "models": ["gpt-4o-mini", "gpt-3.5-turbo"],
  "weight": 1.0
}

// Shared key with denylist
{
  "name": "openai-shared-key",
  "value": "env.OPENAI_API_KEY",
  "models": ["gpt-4o", "gpt-4o-mini"],
  "blacklisted_models": ["gpt-5"],
  "weight": 1.0
}
```

## Deployment Mapping (Azure & Bedrock)

For cloud providers with deployment-based routing, Bifrost validates deployment availability:

**Azure:**

* Keys must have deployment mappings for specific models
* Deployment name maps to actual Azure deployment identifier
* Missing deployment excludes key from selection

**AWS Bedrock:**

* Supports model profiles and direct model access
* Deployment mappings enable inference profile routing
* ARN configuration determines URL formation

**Deployment Validation Process:**

1. Check if provider uses deployments (Azure/Bedrock)
2. Verify deployment exists for requested model
3. Exclude keys without proper deployment mapping
4. Continue with standard weighted selection

## Custom Key Usage (By Name or ID)

Bifrost supports referencing a stored provider key by name or by ID instead of sending the raw secret. This can be useful when you want callers to reference logical key names or stable IDs and let the gateway resolve the actual secret from configured provider keys.

**When both are provided, ID takes priority over name.**

### By ID

* Header: send `x-bf-api-key-id: <key-id>` on the request. The gateway will look up the key with that ID.
* Context (Go SDK):

```go theme={null}
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyAPIKeyID, "key-uuid-1234")
```

### By Name

* Header: send `x-bf-api-key: <key-name>` on the request. The gateway will look up the named key and use its secret for the upstream provider call.
* Context (Go SDK):

```go theme={null}
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyAPIKeyName, "openai-key-1")
```

Note: Both mechanisms reference a stored key (not the raw secret). The gateway resolves the key against configured provider keys and applies model allowlists, denylists, and deployment mapping. When an explicit key ID or name is supplied, weighted selection is bypassed and the referenced key is used directly.

```bash theme={null}
# Example: request referencing a stored key name that doesn't exist
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-api-key: non_existant_key" \
  -d '{
    "model": "anthropic/claude-haiku-4-5",
    "messages": [{"role": "user", "content": "Hello, Bifrost!"}]
  }'
```

Response (example):

```json theme={null}
{"is_bifrost_error":false,"error":{"error":"no key found with name \"non_existant_key\" for provider: anthropic","message":"no key found with name \"non_existant_key\" for provider: anthropic"},"extra_fields":{"provider":"anthropic","model_requested":"claude-haiku-4-5","request_type":"chat_completion"}}
```

# Example: request referencing a stored key name that exists but no configured keys support the requested model

```bash theme={null}
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-api-key: key_with_model_disabled" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello, Bifrost!"}]
  }'
```

Response (example):

```json theme={null}
{"is_bifrost_error":false,"error":{"error":"no keys found that support model: claude-sonnet-4-5","message":"no keys found that support model: claude-sonnet-4-5"},"extra_fields":{"provider":"anthropic","model_requested":"claude-sonnet-4-5","request_type":"chat_completion"}}
```

Note: This is not a weighted selection, by providing a specific key name you are explicitly telling Bifrost which stored key to use, so weighted distribution is bypassed. The example above demonstrates the error returned when a referenced key name cannot be resolved.

## Direct Key Bypass — Removed in v1.5

<Warning>
  The "Direct Key Bypass" feature has been **removed entirely in v1.5**, on both the HTTP gateway and the Go SDK.

  * **HTTP gateway:** the `allow_direct_keys` config flag and the `Authorization` / `x-api-key` / `x-goog-api-key` header pass-through (plus the Bedrock `x-bf-bedrock-*` and Azure `x-bf-azure-endpoint` integration paths) no longer forward keys to upstream providers.
  * **Go SDK:** the `schemas.BifrostContextKeyDirectKey` context value and the `Direct Key (Go SDK Only)` API have been removed.

  All requests must use Bifrost-managed provider keys. To pin a specific key per request from the Go SDK, set `schemas.BifrostContextKeyAPIKeyID` or `schemas.BifrostContextKeyAPIKeyName` against a key managed by Bifrost (for example, one created via the providers API or returned by your `Account` implementation). See the [v1.5.0 migration guide](/migration-guides/v1.5.0) for the full rationale and migration recipes.
</Warning>