Request Options

DeepIntShield provides request options that control behavior, enable features, and pass metadata. In the gateway, these are set via HTTP headers (prefixed with x-bf-). In the Go SDK, they are set via context keys. This document covers both approaches.

Complete Reference

Context Key	Header	Type	Description
DeepIntShieldContextKeyVirtualKey	x-bf-vk	string	Virtual key identifier for governance
DeepIntShieldContextKeyAPIKeyName	x-bf-api-key	string	Explicit API key name selection
DeepIntShieldContextKeyAPIKeyID	x-bf-api-key-id	string	Explicit API key ID selection (takes priority over name)
DeepIntShieldContextKeySessionID	x-bf-session-id	string	Session ID for key stickiness (requires KV store)
DeepIntShieldContextKeySessionTTL	x-bf-session-ttl	time.Duration	Session-to-key cache TTL (duration string or seconds)
DeepIntShieldContextKeyRequestID	x-request-id	string	Custom request ID for tracking
DeepIntShieldContextKeySendBackRawResponse	x-bf-send-back-raw-response	bool	Include raw provider response
DeepIntShieldContextKeyPassthroughExtraParams	x-bf-passthrough-extra-params	bool	Enable passthrough for extra parameters
DeepIntShieldContextKeyExtraHeaders	x-bf-eh-*	map[string][]string	Custom headers forwarded to provider
DeepIntShieldContextKeyDirectKey	-	schemas.Key	Direct key credentials (Go SDK only)
DeepIntShieldContextKeySkipKeySelection	-	bool	Skip key selection process (Go SDK only)
DeepIntShieldContextKeyURLPath	-	string	Custom URL path appended to provider base URL (Go SDK only)
DeepIntShieldContextKeyUseRawRequestBody	-	bool	Use raw request body (Go SDK only, requires RawRequestBody field)
semanticcache.CacheKey	x-bf-cache-key	string	Custom cache key
semanticcache.CacheTTLKey	x-bf-cache-ttl	time.Duration	Cache TTL (duration string or seconds)
semanticcache.CacheThresholdKey	x-bf-cache-threshold	float64	Similarity threshold (0.0-1.0)
semanticcache.CacheTypeKey	x-bf-cache-type	string	Cache type
semanticcache.CacheNoStoreKey	x-bf-cache-no-store	bool	Prevent caching
mcp-include-clients	x-bf-mcp-include-clients	[]string	Filter MCP clients (comma-separated).
mcp-include-tools	x-bf-mcp-include-tools	[]string	Filter MCP tools (comma-separated)
maxim.TraceIDKey	x-bf-maxim-trace-id	string	Maxim trace ID
maxim.GenerationIDKey	x-bf-maxim-generation-id	string	Maxim generation ID
maxim.TagsKey	x-bf-maxim-*	map[string]string	Maxim tags (custom tag names)
DeepIntShieldContextKey(labelName)	x-bf-prom-*	string	Prometheus metric labels

Request Configuration Options

These options configure how DeepIntShield processes and forwards requests.

Virtual Key

Context Key: DeepIntShieldContextKeyVirtualKey
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.

Gateway (cURL)

curl --location 'http://localhost:8080/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!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyVirtualKey, "vk-engineering-main")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Note

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

Context Key: DeepIntShieldContextKeyAPIKeyID 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.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--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!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyAPIKeyID, "key-uuid-1234")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

By Name

Context Key: DeepIntShieldContextKeyAPIKeyName Header: x-bf-api-key Type: string Required: No

Explicitly select a named API key from your configured keys.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-api-key: premium-key' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyAPIKeyName, "premium-key")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Session Stickiness (Session ID)

Context Key: DeepIntShieldContextKeySessionID
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 in the KV store. 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.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--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!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeySessionID, "user-123-session-abc")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Session TTL

Context Key: DeepIntShieldContextKeySessionTTL
Header: x-bf-session-ttl
Type: time.Duration (header 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).

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--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!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeySessionID, "user-123-session-abc")
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeySessionTTL, 30*time.Minute)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Request ID

Context Key: DeepIntShieldContextKeyRequestID
Header: x-request-id
Type: string
Required: No

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

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-request-id: req-12345-abc' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyRequestID, "req-12345-abc")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Send Back Raw Response

Context Key: DeepIntShieldContextKeySendBackRawResponse
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.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-send-back-raw-response: true' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeySendBackRawResponse, true)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

// Access raw response
if response.ChatResponse != nil {
    rawResp := response.ChatResponse.ExtraFields.RawResponse
}

The raw response appears in extra_fields.raw_response:

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

Passthrough Extra Parameters

Context Key: DeepIntShieldContextKeyPassthroughExtraParams
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) will be merged directly into the request sent to the provider.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--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
    }
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyPassthroughExtraParams, true)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
    Params: &schemas.ChatParameters{
        ExtraParams: map[string]interface{}{
            "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

Direct Key (Go SDK Only)

Context Key: DeepIntShieldContextKeyDirectKey
Header: - (not available via HTTP)
Type: schemas.Key
Required: No

Bypass key selection and provide credentials directly. Useful for dynamic key scenarios.

directKey := schemas.Key{
    Value:  "sk-direct-api-key",
    Models: []string{"gpt-4o"},
    Weight: 1.0,
}
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyDirectKey, directKey)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o",
    Input:    messages,
})

Skip Key Selection (Go SDK Only)

Context Key: DeepIntShieldContextKeySkipKeySelection
Header: - (not available via HTTP)
Type: bool
Required: No

Skip the key selection process entirely and pass an empty key to the provider. Useful for providers that don’t require authentication or when using ambient credentials.

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeySkipKeySelection, true)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Custom URL Path (Go SDK Only)

Context Key: DeepIntShieldContextKeyURLPath
Header: - (not available via HTTP)
Type: string
Required: No

Append a custom path to the provider’s base URL. Useful for accessing provider-specific endpoints.

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyURLPath, "/custom/endpoint")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Raw Request Body (Go SDK Only)

Context Key: DeepIntShieldContextKeyUseRawRequestBody
Header: - (not available via HTTP)
Type: bool
Required: No

Send a raw request body instead of DeepIntShield’s standardized format. The provider receives your payload as-is. You must both enable the context key AND set the RawRequestBody field on your request.

// Prepare your raw JSON payload
rawPayload := []byte(`{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "custom_field": "provider-specific-value"
}`)

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyUseRawRequestBody, true)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider:       schemas.OpenAI,
    Model:          "gpt-4o",
    RawRequestBody: rawPayload,
})

Note

When using raw request body, DeepIntShield bypasses its request conversion and sends your payload directly to the provider. You’re responsible for ensuring the payload matches the provider’s expected format.

Custom Headers

Extra Headers (x-bf-eh-*)

Context Key: DeepIntShieldContextKeyExtraHeaders
Header Pattern: x-bf-eh-{header-name}
Type: map[string][]string
Required: No

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

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--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!"}]
}'

Go SDK

extraHeaders := map[string][]string{
    "user-id":     {"user-123"},
    "tracking-id": {"trace-456"},
}
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKeyExtraHeaders, extraHeaders)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

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

Context Key: semanticcache.CacheKey
Header: x-bf-cache-key
Type: string
Required: No

Specify a custom cache key for semantic cache lookups.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-key: custom-key-123' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheKey, "custom-key-123")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Cache TTL

Context Key: semanticcache.CacheTTLKey
Header: x-bf-cache-ttl
Type: time.Duration (header value: duration string like "30s" or "5m", or seconds as integer)
Required: No

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

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-ttl: 300' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheTTLKey, 5*time.Minute)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

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

Cache Threshold

Context Key: semanticcache.CacheThresholdKey
Header: x-bf-cache-threshold
Type: float64 (range: 0.0 to 1.0)
Required: No

Set the similarity threshold for semantic cache matching.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-threshold: 0.85' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheThresholdKey, 0.85)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Cache Type

Context Key: semanticcache.CacheTypeKey
Header: x-bf-cache-type
Type: semanticcache.CacheType (string)
Required: No

Specify the cache type for this request.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-type: semantic' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheTypeKey, semanticcache.CacheTypeSemantic)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Cache No Store

Context Key: semanticcache.CacheNoStoreKey
Header: x-bf-cache-no-store
Type: bool (header value: "true")
Required: No

Prevent caching of this request/response.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-no-store: true' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheNoStoreKey, true)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

MCP (Model Context Protocol) Options

These options control MCP client and tool filtering.

Include Clients

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

Filter MCP clients to include only the specified ones.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-mcp-include-clients: client1,client2' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKey("mcp-include-clients"), []string{"client1", "client2"})

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Include Tools

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

Filter MCP tools to include only the specified ones.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-mcp-include-tools: tool1,tool2' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKey("mcp-include-tools"), []string{"tool1", "tool2"})

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Maxim Observability Options

These options enable Maxim observability integration and tag propagation.

Maxim Trace ID

Context Key: maxim.TraceIDKey
Header: x-bf-maxim-trace-id
Type: string
Required: No

Set the Maxim trace ID for distributed tracing.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-maxim-trace-id: trace-12345' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, maxim.TraceIDKey, "trace-12345")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Maxim Generation ID

Context Key: maxim.GenerationIDKey
Header: x-bf-maxim-generation-id
Type: string
Required: No

Set the Maxim generation ID for request correlation.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-maxim-generation-id: gen-12345' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, maxim.GenerationIDKey, "gen-12345")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Maxim Tags (x-bf-maxim-*)

Context Key: maxim.TagsKey
Header Pattern: x-bf-maxim-{tag-name}
Type: map[string]string
Required: No

Add custom tags to Maxim traces. Any header starting with x-bf-maxim- that isn’t a reserved header becomes a tag.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-maxim-environment: production' \
--header 'x-bf-maxim-team: engineering' \
--header 'Content-Type: application/json' \
--data '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
}'

Go SDK

tags := map[string]string{
    "environment": "production",
    "team":        "engineering",
}
ctx := context.Background()
ctx = context.WithValue(ctx, maxim.TagsKey, tags)

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

Prometheus Options

Context Key: DeepIntShieldContextKey(labelName)
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.

Gateway (cURL)

curl --location 'http://localhost:8080/v1/chat/completions' \
--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!"}]
}'

Go SDK

ctx := context.Background()
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKey("environment"), "production")
ctx = context.WithValue(ctx, schemas.DeepIntShieldContextKey("team"), "engineering")

response, err := client.ChatCompletionRequest(schemas.NewDeepIntShieldContext(ctx, schemas.NoDeadline), &schemas.DeepIntShieldChatRequest{
    Provider: schemas.OpenAI,
    Model:    "gpt-4o-mini",
    Input:    messages,
})

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-*)

Internal Context Keys

Caution

These context keys are read-only and set when request is completed. Do not set these values.

The following context keys are set by DeepIntShield internally.

• DeepIntShieldContextKeySelectedKeyID - The selected provider key ID.
• DeepIntShieldContextKeySelectedKeyName - The selected provider key name.
• DeepIntShieldContextKeyNumberOfRetries - Number of retry attempts made.
• DeepIntShieldContextKeyFallbackIndex - Index of fallback provider used.
• DeepIntShieldContextKeyFallbackRequestID - Request ID for fallback attempts.
• DeepIntShieldContextKeyStreamEndIndicator - Indicates if stream completed.
• DeepIntShieldContextKeyIntegrationType - Format type of integration used.
• DeepIntShieldContextKeyUserAgent - User agent from request.

Related Documentation

• Gateway Provider Configuration - Configure providers and headers
• Go SDK Context Keys - Programmatic context key usage
• Virtual Keys - Virtual key usage and governance
• Semantic Cache - Caching configuration