Header Rules

Nexus provides powerful header transformation capabilities for managing HTTP headers when communicating with LLM providers. This allows you to forward headers from clients, add authentication headers, remove sensitive information, and transform headers for provider compatibility.

Overview

Header rules enable you to:

Forward headers from incoming client requests to providers
Insert static headers for authentication or tracking
Remove sensitive or internal headers before sending to providers
Rename headers for provider compatibility while preserving originals

Configuration Syntax

Headers are configured as an array of rules under each provider. Each rule specifies a transformation type and its parameters:


[[llm.providers.openai.headers]]
rule = "forward"  # Rule type: forward, insert, remove, or rename_duplicate
name = "x-user-id"  # Specific header name
# OR
pattern = "^x-custom-"  # Regex pattern to match multiple headers

Rule Types

Forward Rule

Forwards headers from incoming client requests to the provider. Useful for passing user context, session information, or request IDs.


# Forward a specific header
[[llm.providers.openai.headers]]
rule = "forward"
name = "x-request-id"

# Forward with rename and default value
[[llm.providers.openai.headers]]
rule = "forward"
name = "x-trace-id"
rename = "provider-trace-id"  # Optional: rename the header
default = "{{ env.DEFAULT_TRACE }}"  # Optional: default if not present

# Forward headers matching a pattern
[[llm.providers.openai.headers]]
rule = "forward"
pattern = "^x-org-"  # Forward all headers starting with "x-org-"

Insert Rule

Adds static headers to all requests sent to the provider. Perfect for API versioning, authentication tokens, or feature flags.


# Add a static header
[[llm.providers.anthropic.headers]]
rule = "insert"
name = "x-api-version"
value = "2024-01"

# Use environment variables
[[llm.providers.anthropic.headers]]
rule = "insert"
name = "x-api-key"
value = "{{ env.SECONDARY_API_KEY }}"

# Add provider-specific features
[[llm.providers.openai.headers]]
rule = "insert"
name = "OpenAI-Beta"
value = "assistants=v2"

Remove Rule

Removes headers before sending requests to the provider. Essential for security and preventing header conflicts.


# Remove a specific header
[[llm.providers.google.headers]]
rule = "remove"
name = "cookie"

# Remove headers matching a pattern
[[llm.providers.google.headers]]
rule = "remove"
pattern = "^x-internal-"  # Remove all internal headers

Rename Duplicate Rule

Duplicates a header with a new name while preserving the original header. This creates two headers with the same value. Useful when you need to pass the same value under different header names for compatibility.


# Duplicate a header (keeps both original and new)
[[llm.providers.anthropic.headers]]
rule = "rename_duplicate"
name = "authorization"
rename = "x-original-auth"
# Results in both headers present:
# - authorization: Bearer abc123
# - x-original-auth: Bearer abc123

# With default value if original header doesn't exist
[[llm.providers.anthropic.headers]]
rule = "rename_duplicate"
name = "x-user-token"
rename = "x-backup-token"
default = "Bearer {{ env.DEFAULT_TOKEN }}"
# If x-user-token exists: both x-user-token and x-backup-token have its value
# If x-user-token missing: both headers are set to the default value

Pattern Matching

Use regular expressions to match multiple headers at once:


# Forward all custom headers
[[llm.providers.openai.headers]]
rule = "forward"
pattern = "^x-custom-"

# Remove all debug headers
[[llm.providers.openai.headers]]
rule = "remove"
pattern = "^x-debug-"

# Forward all headers except those starting with "internal-"
[[llm.providers.openai.headers]]
rule = "forward"
pattern = "^(?!internal-).*"

Processing Order

Headers start with an empty set and are processed sequentially in the exact order they appear in your configuration file. Each rule operates on the current state of the headers:

forward and insert rules override any existing headers with the same name
rename_duplicate creates a copy while preserving the original
remove deletes headers from the current set

Sequential Processing Example


# Starting point: headers = {}

# 1. Insert a static header
[[llm.providers.openai.headers]]
rule = "insert"
name = "x-api-version"
value = "2024-01"
# Result: headers = {"x-api-version": "2024-01"}

# 2. Forward all user headers (will override existing headers!)
[[llm.providers.openai.headers]]
rule = "forward"
pattern = "^x-user-"
# If client sends x-user-id=123, x-user-role=admin
# Result: headers = {"x-api-version": "2024-01", "x-user-id": "123", "x-user-role": "admin"}

# 3. Duplicate a header for backup
[[llm.providers.openai.headers]]
rule = "rename_duplicate"
name = "x-user-id"
rename = "x-original-user-id"
# Result: headers = {"x-api-version": "2024-01", "x-user-id": "123", "x-user-role": "admin", "x-original-user-id": "123"}

# 4. Remove sensitive user data
[[llm.providers.openai.headers]]
rule = "remove"
name = "x-user-role"
# Result: headers = {"x-api-version": "2024-01", "x-user-id": "123", "x-original-user-id": "123"}

# 5. Insert to override the forwarded value
[[llm.providers.openai.headers]]
rule = "insert"
name = "x-user-id"
value = "sanitized"
# Final result: headers = {"x-api-version": "2024-01", "x-user-id": "sanitized", "x-original-user-id": "123"}

Common Patterns

Ensure Static Headers Can't Be Overridden

Insert critical headers AFTER forwarding to ensure they have the correct value:


# Forward user headers first
[[llm.providers.api.headers]]
rule = "forward"
pattern = ".*"

# Then override with required values
[[llm.providers.api.headers]]
rule = "insert"
name = "x-api-version"
value = "v2"  # This will override any x-api-version from the client

Forward then Filter

Forward everything, then remove specific headers:


[[llm.providers.api.headers]]
rule = "forward"
pattern = "^x-"  # Forward all x- headers

[[llm.providers.api.headers]]
rule = "remove"
name = "x-internal-secret"  # Remove this specific one

Selective Forwarding with Defaults

Insert defaults first, then forward (forwarded headers will override defaults):


# Set defaults
[[llm.providers.api.headers]]
rule = "insert"
name = "x-tenant-id"
value = "default-tenant"

# Forward user headers (will override x-tenant-id if provided)
[[llm.providers.api.headers]]
rule = "forward"
pattern = "^x-tenant-"

Security Considerations

Protected Headers

Nexus automatically protects sensitive headers by default. These headers are never forwarded unless explicitly configured:

authorization
x-api-key
api-key
cookie
set-cookie
x-nexus-* (internal Nexus headers)

Explicit Forwarding

To forward protected headers, you must explicitly include them:


# Explicitly forward authorization (use with caution!)
[[llm.providers.custom.headers]]
rule = "forward"
name = "authorization"

Best Practices

Never forward authentication headers unless absolutely necessary
Use environment variables for sensitive values
Remove internal headers before sending to external providers
Validate header patterns to avoid accidental exposure
Test header rules in development before production

Advanced Examples

Multi-Tenant Configuration

Forward tenant information while adding provider authentication:


[llm.providers.openai]
type = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"

# Forward tenant context
[[llm.providers.openai.headers]]
rule = "forward"
pattern = "^x-tenant-"

# Add internal tracking
[[llm.providers.openai.headers]]
rule = "insert"
name = "x-gateway"
value = "nexus"

# Remove internal headers
[[llm.providers.openai.headers]]
rule = "remove"
pattern = "^x-internal-"

API Migration

Handle header differences between API versions:


[llm.providers.legacy_api]
type = "openai"
base_url = "https://legacy.api.com"
api_key = "{{ env.LEGACY_KEY }}"

# Forward modern header as legacy format
[[llm.providers.legacy_api.headers]]
rule = "forward"
name = "x-request-id"
rename = "RequestID"

# Add required legacy headers
[[llm.providers.legacy_api.headers]]
rule = "insert"
name = "API-Version"
value = "1.0"

# Remove unsupported headers
[[llm.providers.legacy_api.headers]]
rule = "remove"
pattern = "^x-feature-"

Development vs Production

Different header rules for environments:


[llm.providers.openai]
type = "openai"
api_key = "{{ env.OPENAI_API_KEY }}"

# Forward debug headers in development
[[llm.providers.openai.headers]]
rule = "forward"
pattern = "^x-debug-"
# In production config, this rule would be omitted

# Add environment identifier
[[llm.providers.openai.headers]]
rule = "insert"
name = "x-environment"
value = "{{ env.ENVIRONMENT }}"  # "development" or "production"

Integration with Authentication

Header rules work seamlessly with Nexus authentication methods:

With Token Forwarding


[llm.providers.openai]
type = "openai"
forward_token = true  # Forward client's OpenAI token

# Still add custom headers
[[llm.providers.openai.headers]]
rule = "insert"
name = "x-nexus-client"
value = "{{ env.CLIENT_ID }}"

With Multiple API Keys


[llm.providers.anthropic]
type = "anthropic"
api_key = "{{ env.PRIMARY_KEY }}"

# Add secondary key as backup
[[llm.providers.anthropic.headers]]
rule = "insert"
name = "x-backup-key"
value = "{{ env.SECONDARY_KEY }}"

Troubleshooting

Headers Not Appearing

Check rule syntax - ensure rule field is specified
Verify header names are correct (case-sensitive)
Check processing order - later rules may override earlier ones
Enable debug logging to see header transformations

Pattern Matching Issues

Test regex patterns with online tools
Remember patterns are case-sensitive
Use ^ and $ anchors appropriately
Escape special characters properly

Security Warnings

If you see warnings about protected headers:

Review if forwarding is truly necessary
Consider using different header names
Ensure you're not exposing credentials
Document the security implications

Performance Considerations

Minimize regex patterns - Specific names are faster than patterns
Order rules efficiently - Put most common rules first
Avoid excessive rules - Each rule adds processing overhead
Use patterns sparingly - Only when matching multiple headers

Next Steps

Configure Provider Authentication with headers
Set up Token Forwarding for user keys
Implement Rate Limiting with header-based rules