Forward Client Headers to LLM API

Control which model groups can forward client headers to the underlying LLM provider APIs.

Overview

By default, LiteLLM does not forward client headers to LLM provider APIs for security reasons. However, you can selectively enable header forwarding for specific model groups using the forward_client_headers_to_llm_api setting.

How it Works

LiteLLM does not forward all client headers to the LLM provider. Instead, it uses an allowlist approach: only headers matching specific rules are forwarded. Sensitive headers (like your LiteLLM API key) are therefore never accidentally sent to upstream providers.

Header Allowlist Rules

The following rules determine which headers are forwarded (see _get_forwardable_headers in litellm/proxy/litellm_pre_call_utils.py):

Rule	Example	Forwarded?
Headers starting with `x-`	`x-trace-id`, `x-custom-header`, `x-request-source`	Yes
`anthropic-beta` header	`anthropic-beta: prompt-caching-2024-07-31`	Yes
Headers starting with `x-stainless-*`	`x-stainless-lang`, `x-stainless-arch`	No (causes OpenAI SDK issues)
Standard HTTP headers	`Authorization`, `Content-Type`, `Host`	No
Other provider headers	`Accept`, `User-Agent`	No

Additional Header Mechanisms

Mechanism	Description	Reference
`x-pass-` prefix	Headers prefixed with `x-pass-` are always forwarded with the prefix stripped, regardless of settings. E.g., `x-pass-anthropic-beta: value` → `anthropic-beta: value`. Works for all pass-through endpoints.	Source code
`openai-organization`	Forwarded only when `forward_openai_org_id: true` is set in `general_settings`.	Forward OpenAI Org ID
User information headers	When `add_user_information_to_llm_headers: true`, LiteLLM adds `x-litellm-user-id`, `x-litellm-org-id`, etc.	User Information Headers
Vertex AI pass-through	Uses a separate, stricter allowlist: only `anthropic-beta` and `content-type`.	Source code

Configuration

Enable Globally

general_settings:
  forward_client_headers_to_llm_api: true

Forward LLM Provider Authentication Headers

New in v1.82+: By default, LiteLLM strips authentication headers like x-api-key, x-goog-api-key, and api-key from client requests for security (these are typically used to authenticate with the proxy itself). However, you can enable forwarding of these LLM provider authentication headers to allow Bring Your Own Key (BYOK) scenarios where clients send their own API keys to the LLM provider.

Configuration

Add forward_llm_provider_auth_headers: true to your general_settings:

general_settings:
  forward_client_headers_to_llm_api: true
  forward_llm_provider_auth_headers: true  # 👈 Enable BYOK

Which Headers Are Forwarded

When forward_llm_provider_auth_headers: true, the following LLM provider authentication headers are preserved and forwarded:

Header	Provider	Example
`x-api-key`	Anthropic, Azure AI, Databricks	`x-api-key: sk-ant-api03-...`
`x-goog-api-key`	Google AI Studio	`x-goog-api-key: AIza...`
`api-key`	Azure OpenAI	`api-key: your-azure-key`
`ocp-apim-subscription-key`	Azure APIM	`ocp-apim-subscription-key: your-key`

Important Security Note

The proxy's Authorization header (used for proxy authentication) is never forwarded to LLM providers, even with this setting enabled. This ensures your proxy authentication remains secure.

Use Case: Client-Side API Keys (BYOK)

This feature enables scenarios where:

Clients bring their own LLM provider API keys instead of using keys configured in the proxy
Multi-tenant applications where each tenant has their own Anthropic/OpenAI account
Development environments where developers use their personal API keys through a shared proxy

Example: Anthropic BYOK

# proxy_config.yaml
model_list:
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      # No api_key configured! Will use client's key

general_settings:
  forward_client_headers_to_llm_api: true
  forward_llm_provider_auth_headers: true  # Enable BYOK

For Claude Code, see Claude Code BYOK. Use ANTHROPIC_CUSTOM_HEADERS="x-litellm-api-key: $LITELLM_API_KEY" to pass your LiteLLM key. A configured Anthropic API key is sent as x-api-key and needs forward_llm_provider_auth_headers above to be forwarded; /login instead sends an OAuth token as Authorization: Bearer <token>, which LiteLLM forwards regardless of this setting. From LiteLLM v1.105.0, each spend log row records which credential the upstream call used in metadata.used_client_oauth_token (true for a forwarded OAuth token, false for the deployment's configured key, never the token itself), filterable on the Logs page Credential dropdown or with GET /spend/logs/ui?used_client_oauth_token=true.

Client request:

# Authorization: Proxy authentication (stripped)
# x-api-key: Client's Anthropic key (forwarded!)
curl -X POST "http://localhost:4000/v1/messages" \
  -H "Authorization: Bearer sk-proxy-auth-123" \
  -H "x-api-key: sk-ant-api03-YOUR-KEY..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'

Example: Google AI Studio BYOK

model_list:
  - model_name: gemini-3.1-pro-preview
    litellm_params:
      model: gemini/gemini-3.1-pro-preview
      # No api_key configured

general_settings:
  forward_client_headers_to_llm_api: true
  forward_llm_provider_auth_headers: true

Client request:

curl -X POST "http://localhost:4000/v1/chat/completions" \
  -H "Authorization: Bearer sk-proxy-auth-123" \
  -H "x-goog-api-key: AIza..." \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Example: custom Anthropic-compatible `api_base`

Use this when the models sit behind your own gateway that speaks the Anthropic Messages API and each user holds their own token for it. A wildcard route passes whatever model the caller names through to the gateway, so newly available models need no config change. Only forward_llm_provider_auth_headers is required here

model_list:
  - model_name: "my-gateway/*"
    litellm_params:
      model: "anthropic/*"
      api_base: "https://gateway.example.com/anthropic"
      # No api_key: each request supplies its own

general_settings:
  forward_llm_provider_auth_headers: true

Authenticate to LiteLLM with Authorization: Bearer or x-litellm-api-key, and put the user's gateway token in x-api-key:

curl -X POST "http://localhost:4000/v1/chat/completions" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "x-api-key: $USER_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-gateway/claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

LiteLLM drops the my-gateway/ prefix and calls https://gateway.example.com/anthropic/v1/messages with "model": "claude-sonnet-4-5" and x-api-key: $USER_GATEWAY_TOKEN. Requests to /v1/messages and /v1/chat/completions both reach the gateway this way. The token always goes out as x-api-key, so the gateway must accept that header. To list the gateway's models on /v1/models, see Model Discovery

Which key reaches the provider

A forwarded provider header takes precedence over the deployment's api_key for that request. When a request carries no provider key, LiteLLM falls back to the deployment's api_key, then to the provider's environment variable on the proxy host (for example ANTHROPIC_API_KEY), and the call runs on that key without any error. To require every caller to bring their own key, leave both unset; a request without one then fails with Missing Anthropic API Key before anything is sent to the provider

Do not send the LiteLLM key in x-api-key. LiteLLM accepts it there as proxy authentication and then removes it, so it is not forwarded and the request falls back as described above

Security Considerations

When to Use This Feature:

Internal tools where you trust all clients
Development/testing environments
Multi-tenant apps with proper client authentication
Scenarios where you want clients to use their own API keys

When NOT to Use:

Public APIs where you don't trust all clients
When you want centralized billing/cost control
When you need to enforce rate limits at the proxy level

Backward Compatibility

For backward compatibility, if you have forward_client_headers_to_llm_api: true but don't explicitly set forward_llm_provider_auth_headers, the behavior is:

Default: LLM provider auth headers are NOT forwarded (safe default)
Explicit true: LLM provider auth headers ARE forwarded (BYOK enabled)

# Safe default - auth headers NOT forwarded
general_settings:
  forward_client_headers_to_llm_api: true

# BYOK enabled - auth headers ARE forwarded
general_settings:
  forward_client_headers_to_llm_api: true
  forward_llm_provider_auth_headers: true  # 👈 Opt-in required

Enable for a Model Group

Add the forward_client_headers_to_llm_api setting under model_group_settings in your configuration:

model_list:
  - model_name: gpt-5.6-luna
    litellm_params:
      model: openai/gpt-5.6-luna
      api_key: "your-api-key"
  - model_name: "wildcard-models/*"
    litellm_params:
      model: "openai/*"
      api_key: "your-api-key"

litellm_settings:
  model_group_settings:
    forward_client_headers_to_llm_api:
      - gpt-5.6-luna
      - wildcard-models/*

Supported Model Patterns

The configuration supports various model matching patterns:

1. Exact Model Names

forward_client_headers_to_llm_api:
  - gpt-5.6-luna
  - claude-sonnet-5

2. Wildcard Patterns

forward_client_headers_to_llm_api:
  - "openai/*"          # All OpenAI models
  - "anthropic/*"       # All Anthropic models
  - "wildcard-group/*"  # All models in wildcard-group

3. Team Model Aliases

If your team has model aliases configured, the forwarding will work with both the original model name and the alias.

Forwarded Headers

When enabled for a model group, LiteLLM forwards the following types of headers:

Custom Headers (x- prefix)

Any header starting with x- (except x-stainless-* which can cause OpenAI SDK issues)
Examples: x-custom-header, x-request-id, x-trace-id

Provider-Specific Headers

Anthropic: anthropic-beta headers
OpenAI: openai-organization (when enabled via forward_openai_org_id: true)

User Information Headers (Optional)

When add_user_information_to_llm_headers is enabled, LiteLLM adds:

x-litellm-user-id
x-litellm-org-id
Other user metadata as x-litellm-* headers

Security Considerations

⚠️ Important Security Notes:

Sensitive Data: Only enable header forwarding for trusted model groups, as headers may contain sensitive information
API Keys: Never include API keys or secrets in forwarded headers
PII: Be cautious about forwarding headers that might contain personally identifiable information
Provider Limits: Some providers have restrictions on custom headers

Example Use Cases

1. Request Tracing

Forward tracing headers to track requests across your system:

curl -X POST "https://your-proxy.com/v1/chat/completions" \
  -H "Authorization: Bearer your-key" \
  -H "x-trace-id: abc123" \
  -H "x-request-source: mobile-app" \
  -d '{
    "model": "gpt-5.6-luna",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

2. Custom Metadata

Pass custom metadata to your LLM provider:

curl -X POST "https://your-proxy.com/v1/chat/completions" \
  -H "Authorization: Bearer your-key" \
  -H "x-customer-id: customer-123" \
  -H "x-environment: production" \
  -d '{
    "model": "gpt-5.6-luna", 
    "messages": [{"role": "user", "content": "Hello"}]
  }'

3. Anthropic Beta Features

Enable beta features for Anthropic models:

curl -X POST "https://your-proxy.com/v1/chat/completions" \
  -H "Authorization: Bearer your-key" \
  -H "anthropic-beta: tools-2024-04-04" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Complete Configuration Example

model_list:
  # Fixed model with header forwarding
  - model_name: byok-fixed-gpt-4o-mini
    litellm_params:
      model: openai/gpt-5.6-luna
      api_base: "https://your-openai-endpoint.com"
      api_key: "your-api-key"
      
  # Wildcard model group with header forwarding
  - model_name: "byok-wildcard/*"
    litellm_params:
      model: "openai/*"
      api_base: "https://your-openai-endpoint.com"
      api_key: "your-api-key"
      
  # Standard model without header forwarding
  - model_name: standard-gpt-4o
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: "your-api-key"

litellm_settings:
  # Enable user info headers globally (optional)
  add_user_information_to_llm_headers: true
  
  model_group_settings:
    forward_client_headers_to_llm_api:
      - byok-fixed-gpt-4o-mini
      - byok-wildcard/*
      # Note: standard-gpt-4o is NOT included, so no headers forwarded

general_settings:
  # Enable OpenAI organization header forwarding (optional)
  forward_openai_org_id: true

Testing Header Forwarding

To test if headers are being forwarded:

Enable Debug Logging: Set set_verbose: true in your config
Check Provider Logs: Monitor your LLM provider's request logs
Use Webhook Sites: For testing, you can use webhook.site URLs as api_base to see forwarded headers

Troubleshooting

Headers Not Being Forwarded

Check Model Name: Ensure the model name in your request matches the configuration
Verify Pattern Matching: Wildcard patterns must match exactly
Review Logs: Enable verbose logging to see header processing

Provider Errors

Invalid Headers: Some providers reject unknown headers
Header Limits: Providers may have limits on header count/size
Authentication: Ensure forwarded headers don't conflict with authentication

Request Headers - Complete list of supported request headers
Response Headers - Headers returned by LiteLLM
Team Model Aliases - Configure model aliases for teams
Model Access Control - Control which users can access which models

API Reference

The header forwarding is controlled by the ModelGroupSettings configuration:

class ModelGroupSettings(BaseModel):
    forward_client_headers_to_llm_api: Optional[List[str]] = None

Where each string in the list can be:

An exact model name (e.g., "gpt-5.6-luna")
A wildcard pattern (e.g., "openai/*")
A model group name (e.g., "my-model-group/*")

Overview​

How it Works​

Header Allowlist Rules​

Additional Header Mechanisms​

Configuration​

Enable Globally​

Forward LLM Provider Authentication Headers​

Configuration​

Which Headers Are Forwarded​

Use Case: Client-Side API Keys (BYOK)​

Example: Anthropic BYOK​

Example: Google AI Studio BYOK​

Example: custom Anthropic-compatible api_base​

Which key reaches the provider​

Security Considerations​

Backward Compatibility​

Enable for a Model Group​

Supported Model Patterns​

1. Exact Model Names​

2. Wildcard Patterns​

3. Team Model Aliases​

Forwarded Headers​

Custom Headers (x- prefix)​

Provider-Specific Headers​

User Information Headers (Optional)​

Security Considerations​

Example Use Cases​

1. Request Tracing​

2. Custom Metadata​

3. Anthropic Beta Features​

Complete Configuration Example​

Testing Header Forwarding​

Troubleshooting​

Headers Not Being Forwarded​

Provider Errors​

Related Features​

API Reference​

Overview

How it Works

Header Allowlist Rules

Additional Header Mechanisms

Configuration

Enable Globally

Forward LLM Provider Authentication Headers

Configuration

Which Headers Are Forwarded

Use Case: Client-Side API Keys (BYOK)

Example: Anthropic BYOK

Example: Google AI Studio BYOK

Example: custom Anthropic-compatible `api_base`

Which key reaches the provider

Security Considerations

Backward Compatibility

Enable for a Model Group

Supported Model Patterns

1. Exact Model Names

2. Wildcard Patterns

3. Team Model Aliases

Forwarded Headers

Custom Headers (x- prefix)

Provider-Specific Headers

User Information Headers (Optional)

Security Considerations

Example Use Cases

1. Request Tracing

2. Custom Metadata

3. Anthropic Beta Features

Complete Configuration Example

Testing Header Forwarding

Troubleshooting

Headers Not Being Forwarded

Provider Errors

Related Features

API Reference