Request Options

DeepIntShield provides request options that control behavior, enable features, and pass metadata. These are set as HTTP headers (prefixed with x-bf-) on your gateway requests. Because the gateway is OpenAI-compatible, you can add them with curl, any OpenAI-compatible client, or the Python SDK via extra_headers.

Complete Reference

Header	Type	Description
x-bf-vk	string	Virtual key identifier for governance
x-bf-api-key	string	Explicit API key name selection
x-bf-api-key-id	string	Explicit API key ID selection (takes priority over name)
x-bf-session-id	string	Session ID for key stickiness
x-bf-session-ttl	duration	Session-to-key cache TTL (duration string like "30m", or seconds)
x-request-id	string	Custom request ID for tracking
x-bf-send-back-raw-response	bool	Include raw provider response
x-bf-passthrough-extra-params	bool	Enable passthrough for extra parameters
x-bf-eh-*	string	Custom headers forwarded to provider
x-bf-cache-key	string	Custom cache key
x-bf-cache-ttl	duration	Cache TTL (duration string like "5m", or seconds)
x-bf-cache-threshold	float	Similarity threshold (0.0-1.0)
x-bf-cache-type	string	Cache type
x-bf-cache-no-store	bool	Prevent caching
x-bf-mcp-include-clients	[]string	Filter MCP clients (comma-separated)
x-bf-mcp-include-tools	[]string	Filter MCP tools (comma-separated)
x-bf-prom-*	string	Prometheus metric labels

Tip

With the Python SDK, pass any of these headers through extra_headers (or default_headers when constructing the client). For example, openai.chat.completions.create(..., extra_headers={"x-bf-session-id": "user-123"}).

Request Configuration Options

These options configure how DeepIntShield processes and forwards requests.

Virtual Key

Header: x-bf-vk Type: string Required: Yes (when governance is enabled and enforced)

Specify the virtual key identifier for governance, routing, and access control.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'x-bf-vk: vk-engineering-main' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Note

With the Python SDK, the virtual key is set when you construct DeepintShield(virtual_key="sk-...") (or via DEEPINTSHIELD_VIRTUAL_KEY), so you usually don’t set x-bf-vk manually. Virtual keys can also be passed via Authorization: Bearer vk-*, x-api-key: vk-*, or x-goog-api-key: vk-* headers when the value starts with the virtual key prefix.

API Key Selection

DeepIntShield supports selecting a specific key by ID or name. When both are present, ID takes priority.

By ID

Header: x-bf-api-key-id Type: string Required: No

Explicitly select a key by its unique ID. Takes priority over name selection when both are provided.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-api-key-id: key-uuid-1234' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

By Name

Header: x-bf-api-key Type: string Required: No

Explicitly select a named API key from your configured keys.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-api-key: premium-key' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Session Stickiness (Session ID)

Header: x-bf-session-id Type: string Required: No

Bind a session to a specific API key so that requests with the same session ID consistently use the same key. Useful for predictable rate-limit buckets, cost attribution per user, and consistent model routing per session.

On the first request for a session ID, DeepIntShield selects a key and caches the binding. Subsequent requests with the same session ID reuse the cached key as long as it remains valid.

Retry and Fallback Behavior:

• Retries: Session stickiness persists across retry attempts. If a request fails and is retried, the same sticky key is used.
• Fallbacks: When falling back to a different provider (e.g., from OpenAI to Anthropic), session stickiness is disabled and a new key is selected for the fallback provider. This ensures availability when the primary provider’s keys are exhausted or failing.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-session-id: user-123-session-abc' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Session TTL

Header: x-bf-session-ttl Type: duration (value: duration string like "30m" or "1h", or seconds as integer) Required: No

Optional. Controls how long the session-to-key binding is cached. If not set, DeepIntShield uses 1 hour. The TTL is refreshed on each request so active sessions do not expire.

Accepts duration strings ("30s", "5m", "1h") or plain numbers (treated as seconds).

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-session-id: user-123-session-abc' \
--header 'x-bf-session-ttl: 30m' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Request ID

Header: x-request-id Type: string Required: No

Set a custom request ID for tracking and correlation. If not provided, DeepIntShield generates a UUID.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-request-id: req-12345-abc' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Send Back Raw Response

Header: x-bf-send-back-raw-response Type: bool (header value: "true") Required: No

Include the original provider response alongside DeepIntShield’s standardized response format.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-send-back-raw-response: true' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

The raw response appears in extra_fields.raw_response:

{
    "choices": [],
    "usage": {},
    "extra_fields": {
        "provider": "openai",
        "raw_response": {
            "//": "Original provider response here"
        }
    }
}

Passthrough Extra Parameters

Header: x-bf-passthrough-extra-params Type: bool (header value: "true") Required: No

Enable passthrough mode for extra parameters. When enabled, any parameters in extra_params (or provider-specific extra parameter fields) are merged directly into the request sent to the provider.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-passthrough-extra-params: true' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}],
    "extra_params": {
        "custom_param": "value",
        "another_param": 123
    }
}'

Note

• Only works for JSON requests, not multipart/form-data requests
• Parameters already handled by DeepIntShield are not duplicated
• Nested parameters are merged recursively with existing structures

Custom Headers

Extra Headers (x-bf-eh-*)

Header Pattern: x-bf-eh-{header-name} Type: string Required: No

Pass custom headers to providers. The x-bf-eh- prefix is stripped before forwarding.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-eh-user-id: user-123' \
--header 'x-bf-eh-tracking-id: trace-456' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

The headers x-bf-eh-user-id and x-bf-eh-tracking-id are forwarded to the provider as user-id and tracking-id respectively.

Example use cases:

• User identification: x-bf-eh-user-id, x-bf-eh-tenant-id
• Request tracking: x-bf-eh-correlation-id, x-bf-eh-trace-id
• Custom metadata: x-bf-eh-department, x-bf-eh-cost-center
• A/B testing: x-bf-eh-experiment-id, x-bf-eh-variant

Semantic Cache Options

These options control semantic caching behavior.

Cache Key

Header: x-bf-cache-key Type: string Required: No

Specify a custom cache key for semantic cache lookups.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-cache-key: custom-key-123' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Cache TTL

Header: x-bf-cache-ttl Type: duration (value: duration string like "30s" or "5m", or seconds as integer) Required: No

Set a custom time-to-live for cached responses.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-cache-ttl: 300' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Accepts duration strings ("30s", "5m", "1h") or plain numbers (treated as seconds).

Cache Threshold

Header: x-bf-cache-threshold Type: float (range: 0.0 to 1.0) Required: No

Set the similarity threshold for semantic cache matching.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-cache-threshold: 0.85' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Cache Type

Header: x-bf-cache-type Type: string Required: No

Specify the cache type for this request.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-cache-type: semantic' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Cache No Store

Header: x-bf-cache-no-store Type: bool (header value: "true") Required: No

Prevent caching of this request/response.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-cache-no-store: true' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

MCP (Model Context Protocol) Options

These options control MCP client and tool filtering.

Include Clients

Header: x-bf-mcp-include-clients Type: []string (comma-separated values) Required: No

Filter MCP clients to include only the specified ones.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-mcp-include-clients: client1,client2' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Include Tools

Header: x-bf-mcp-include-tools Type: []string (comma-separated values) Required: No

Filter MCP tools to include only the specified ones.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-mcp-include-tools: tool1,tool2' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Prometheus Options

Header Pattern: x-bf-prom-{label-name} Type: string Required: No

Add custom labels to Prometheus metrics. The x-bf-prom- prefix is stripped and the remainder becomes the label name.

curl --location 'https://app.deepintshield.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-bf-your-virtual-key' \
--header 'x-bf-prom-environment: production' \
--header 'x-bf-prom-team: engineering' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Security Denylist

DeepIntShield maintains a security denylist of headers that are never forwarded to providers, regardless of configuration:

• proxy-authorization
• cookie
• host
• content-length
• connection
• transfer-encoding
• x-api-key (when used via x-bf-eh-*)
• x-goog-api-key (when used via x-bf-eh-*)
• x-bf-api-key (when used via x-bf-eh-*)
• x-bf-vk (when used via x-bf-eh-*)

Related Documentation

• Gateway Provider Configuration - Configure providers and headers
• What is an Integration - Connect the Python SDK and other clients to the gateway
• Virtual Keys - Virtual key usage and governance
• Semantic Cache - Caching configuration