Passthrough

Overview

Passthrough integrations let you call provider-native API paths and payloads through Bifrost without route-level request/response conversion. When you use passthrough endpoints, the request still flows through Bifrost core logic. You keep Bifrost features such as logging and observability while sending provider-native paths and bodies.

Endpoints

/openai_passthrough Default provider: openai
/anthropic_passthrough Default provider: anthropic
/azure_passthrough Default provider: azure
/genai_passthrough Default provider: gemini (with automatic Vertex detection for clients configured to use Vertex)
/bedrock_passthrough Default provider: bedrock (restricted to three operations, see Bedrock Passthrough)

How It Works

Send your request to a passthrough endpoint (OpenAI, Anthropic, Azure, or GenAI passthrough).
The integration strips the passthrough prefix and forwards the remaining provider-native path/body.
Bifrost picks the provider key. Client-supplied provider credentials (authorization, api-key, x-api-key, x-goog-api-key) are stripped from the request, and Bifrost selects a key from its own key config for the resolved provider and model.
Bifrost handles provider execution through core inference and plugin pipelines.
Response status, headers, and body are returned as passthrough output (for both stream and non-stream requests).

Authenticate to Bifrost with your Bifrost virtual key, not your provider API key. Passthrough is not a credential proxy — provider keys in the incoming request are never forwarded upstream. Bifrost always injects the key it selects from its configured keys.

When the URL path names a model (for example models/{model} or a deployment path), Bifrost uses that model. Otherwise, for JSON bodies, it reads the model from the top-level model key, the same key the provider reads. Virtual-key model restrictions apply to whichever model was resolved. A JSON body must carry that key at most once, spelled exactly model (lowercase), with a string value; a body that repeats it (in any letter case), spells it differently, gives it a non-string value, or is not valid JSON while sent as application/json is rejected with 400. Bodies without a model key and multipart bodies are unaffected.

Claude Code OAuth sign-in (Authorization: Bearer sk-ant-oat…) is handled separately on the regular /anthropic route, where Bifrost forwards the caller’s token instead of selecting a key. Point Claude Code there — no passthrough endpoint needed. See Claude Code authentication.

Provider Selection Rules

OpenAI Passthrough

Uses openai as the default provider.

Anthropic Passthrough

Uses anthropic as the default provider.

Azure Passthrough

Uses azure as the default provider.
Requires an Azure key with endpoint configured.
api-version handling varies by route:
- /openai/deployments/ routes: if the caller omits api-version, Bifrost injects a default (2025-04-01-preview). Pass your own api-version to override — for example, to pin to a GA version or use a specific preview version.

Bedrock Passthrough

Uses bedrock as the default provider.

Not a general AWS proxy. Bifrost forwards only the Bedrock operations it has no native route for, and refuses every other path, method or malformed identifier with a 400 before any request is built:

Operation	Method and path (after `/bedrock_passthrough`)	AWS service host
InvokeAgent	`POST /agents/{agentId}/agentAliases/{agentAliasId}/sessions/{sessionId}/text`	`bedrock-agent-runtime`
Retrieve (knowledge base)	`POST /knowledgebases/{knowledgeBaseId}/retrieve`	`bedrock-agent-runtime`
ApplyGuardrail	`POST /guardrail/{guardrailId}/version/{version}/apply`	`bedrock-runtime`

Identifiers follow the character sets AWS documents for each parameter: agent, alias, knowledge-base and guardrail ids are alphanumeric, a session id may also contain ., _, : and - (but never consists only of dots), and a guardrail version is DRAFT or a number from 1 to 8 digits. An ARN is not accepted in place of an id.
The host comes from the key’s region (or its endpoints overrides). Credentials in the incoming request are never forwarded. InvokeAgent and Retrieve are always signed with the key’s AWS credentials (SigV4, service bedrock), because AWS does not accept Bedrock API keys for Agents Runtime operations: a key that holds only an API key is refused with a 400 for those two operations, so select a key that has an access key and secret key or a role (for example with x-bf-api-key). ApplyGuardrail sends the key’s Bedrock API key as a bearer token when it has one, and is SigV4-signed otherwise.
The AWS status and body come back unchanged, together with the response headers Bifrost forwards, including Content-Type and X-Amzn-* such as X-Amzn-Errortype and X-Amzn-Requestid. Transport-level headers (for example Content-Length, Content-Encoding, Transfer-Encoding, Connection and Date) and credential-bearing ones (Set-Cookie, anything that looks like an API key or secret, and X-Amzn-Oidc-*) are removed, so an upstream ResourceNotFoundException still reaches the caller with its exception type. InvokeAgent is forwarded to the client as AWS produces it, so a long agent run is not buffered and is not bound by the gateway’s whole-response timeout (only a stalled connection ends it, via the stream idle timeout). Retrieve and ApplyGuardrail are returned as a single response.

GenAI Passthrough

Uses gemini by default.
Automatically switches to vertex when Vertex patterns are detected, such as:
- URL path containing /projects/{PROJECT_ID}/locations/{LOCATION}/
- Request body model containing a Vertex resource path
- OAuth token pattern typically used for Vertex (Bearer ya29...)

Usage Examples

OpenAI Passthrough

Python SDK
cURL

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/openai_passthrough/v1",
    api_key="<YOUR-BIFROST-VIRTUAL-KEY>"  # Replace with your actual Bifrost virtual key.
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "hello from passthrough"}]
)

print(response.choices[0].message.content)

curl -X POST "http://localhost:8080/openai_passthrough/v1/chat/completions" \
  -H "content-type: application/json" \
  -H "authorization: Bearer <YOUR-BIFROST-VIRTUAL-KEY>" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role":"user","content":"hello from passthrough"}]
  }'

Anthropic Passthrough

Python SDK
cURL

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:8080/anthropic_passthrough",
    api_key="<YOUR-BIFROST-VIRTUAL-KEY>"  # Replace with your actual Bifrost virtual key.
)

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "hello from passthrough"}]
)

print(response.content[0].text)

curl -X POST "http://localhost:8080/anthropic_passthrough/v1/messages" \
  -H "content-type: application/json" \
  -H "x-api-key: <YOUR-BIFROST-VIRTUAL-KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"hello from passthrough"}]
  }'

Azure Passthrough

Azure OpenAI SDK
OpenAI SDK
Anthropic SDK (Anthropic on Azure)
cURL

from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="http://localhost:8080/azure_passthrough",
    api_key="<YOUR-BIFROST-VIRTUAL-KEY>",  # Replace with your actual Bifrost virtual key.
    api_version="2024-10-21",  # passed through as-is in the query string
)

response = client.chat.completions.create(
    model="gpt-4o",  # your Azure deployment name
    messages=[{"role": "user", "content": "hello from azure passthrough"}]
)

print(response.choices[0].message.content)

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/azure_passthrough/openai/v1/",
    api_key="<YOUR-BIFROST-VIRTUAL-KEY>",  # Replace with your actual Bifrost virtual key.
)

response = client.responses.create(
    model="gpt-4.1",  # your Azure deployment name
    input="hello from azure passthrough",
)

print(response.output_text)

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:8080/azure_passthrough",
    api_key="<YOUR-BIFROST-VIRTUAL-KEY>",  # Replace with your actual Bifrost virtual key.
)

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "hello from azure passthrough"}]
)

print(response.content[0].text)

curl -X POST "http://localhost:8080/azure_passthrough/openai/deployments/gpt-4o/chat/completions?api-version=2025-04-01-preview" \
  -H "content-type: application/json" \
  -H "api-key: <YOUR-BIFROST-VIRTUAL-KEY>" \
  -d '{
    "messages": [{"role": "user", "content": "hello from azure passthrough"}]
  }'

Bedrock Passthrough

curl -X POST "http://localhost:8080/bedrock_passthrough/knowledgebases/KB12345678/retrieve" \
  -H "Content-Type: application/json" \
  -d '{"retrievalQuery":{"text":"what is bifrost"}}'

curl -X POST "http://localhost:8080/bedrock_passthrough/guardrail/gr1a2b3c4d5e/version/DRAFT/apply" \
  -H "Content-Type: application/json" \
  -d '{"source":"INPUT","content":[{"text":{"text":"hello"}}]}'

GenAI Passthrough (Gemini)

Python SDK
cURL

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(
    api_key="<YOUR-BIFROST-VIRTUAL-KEY>",  # Replace with your actual Bifrost virtual key.
    http_options=HttpOptions(base_url="http://localhost:8080/genai_passthrough")
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="hello from passthrough"
)

print(response.text)

curl -X POST "http://localhost:8080/genai_passthrough/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "content-type: application/json" \
  -H "x-goog-api-key: <YOUR-BIFROST-VIRTUAL-KEY>" \
  -d '{
    "contents":[{"parts":[{"text":"hello from passthrough"}]}]
  }'

GenAI Passthrough (Vertex-style request)

Python SDK
cURL

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(
    vertexai=True,
    api_key="<YOUR-BIFROST-VIRTUAL-KEY>",  # Replace with your actual Bifrost virtual key.
    http_options=HttpOptions(base_url="http://localhost:8080/genai_passthrough")
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="hello from vertex passthrough"
)

print(response.text)

curl -X POST "http://localhost:8080/genai_passthrough/v1/projects/my-project/locations/us-central1/publishers/google/models/gemini-2.5-flash:generateContent" \
  -H "content-type: application/json" \
  -H "authorization: Bearer <YOUR-BIFROST-VIRTUAL-KEY>" \
  -d '{
    "contents":[{"parts":[{"text":"hello from vertex passthrough"}]}]
  }'

Notes

Use passthrough when you need a provider endpoint that is not directly supported by Bifrost integration routes yet.
Provider key selection is done by Bifrost, not by the caller. On every passthrough endpoint, the client’s authorization, api-key, x-api-key, and x-goog-api-key headers are dropped before the request leaves Bifrost, and the upstream auth header (including Azure’s api-key / OAuth token) is set from the Bifrost key config.
The only exception is direct API keys, which need both the server-side allow_direct_keys setting and a per-request x-bf-direct-key: true header. Without both, a raw provider key in the request is ignored.
For Azure /openai/deployments/ routes, Bifrost injects api-version=2025-04-01-preview when the caller does not supply one. Supply your own api-version query parameter to use a different version (e.g. 2024-10-21 for the latest GA, or a newer preview).

Runbooks

CLI Agents & Editors

SDKs & Frameworks

Identity Providers (SSO)

Content Safety (Guardrails)

Observability

Vector Databases

Overview

Endpoints

How It Works

Provider Selection Rules

OpenAI Passthrough

Anthropic Passthrough

Azure Passthrough

Bedrock Passthrough

GenAI Passthrough

Usage Examples

OpenAI Passthrough

Anthropic Passthrough

Azure Passthrough

Bedrock Passthrough

GenAI Passthrough (Gemini)

GenAI Passthrough (Vertex-style request)

Notes

​Overview

​Endpoints

​How It Works

​Provider Selection Rules

​OpenAI Passthrough

​Anthropic Passthrough

​Azure Passthrough

​Bedrock Passthrough

​GenAI Passthrough

​Usage Examples

​OpenAI Passthrough

​Anthropic Passthrough

​Azure Passthrough

​Bedrock Passthrough

​GenAI Passthrough (Gemini)

​GenAI Passthrough (Vertex-style request)

​Notes

Overview

Endpoints

How It Works

Provider Selection Rules

OpenAI Passthrough

Anthropic Passthrough

Azure Passthrough

Bedrock Passthrough

GenAI Passthrough

Usage Examples

OpenAI Passthrough

Anthropic Passthrough

Azure Passthrough

Bedrock Passthrough

GenAI Passthrough (Gemini)

GenAI Passthrough (Vertex-style request)

Notes