Pass-through Proxy

Pass-through mode lets you route AI requests through the gateway without billing or format conversion. Requests are forwarded as-is to the upstream provider — the gateway only authenticates, logs usage, and estimates cost for observability.

This is useful when your developers already have their own provider API keys (e.g. Claude Code Max, Codex, Cursor) and you want centralized usage tracking without changing their workflow.

How It Works

Developer → Gateway (auth + log) → Upstream Provider (e.g. api.anthropic.com)

Setup

1. Enable Pass-through on the Project

In your project settings, add the passthrough configuration:

// Project settings (JSONB)
{
  "passthrough": {
    "enabled": true,
    "provider": "anthropic",
    "base_url": "https://api.anthropic.com"
  }
}

2. Create a Pass-through API Key

Create an API key with mode: "passthrough" in the permissions:

// API key permissions (JSONB)
{
  "models": "*",
  "endpoints": "*",
  "mode": "passthrough"
}

Only keys with mode: "passthrough" can access the pass-through proxy. Standard keys continue to use the managed proxy pipeline.

3. Configure the Developer's Environment

The developer sets two environment variables. Their existing Authorization header (provider API key) is preserved and forwarded to the upstream provider.

export ANTHROPIC_BASE_URL="https://gateway.assistant-billing.dev"
export ANTHROPIC_CUSTOM_HEADERS="x-ab-api-key: sk_ab_live_xyz789"

Request Flow

1. Developer sends a request with x-ab-api-key header
2. Gateway authenticates the pass-through key (rate limits apply, no budget check)
3. Request is forwarded to base_url + path (e.g. https://api.anthropic.com/v1/messages)
4. Headers forwarded: Authorization, Content-Type, anthropic-version, anthropic-beta, Accept, x-api-key
5. Headers stripped: x-ab-api-key, Host, all x-ab-* headers
6. Response is streamed back to the developer
7. Usage is extracted from the response (SSE stream or JSON body)
8. Cost is estimated and logged — no wallet deduction

Response Headers

Pass-through responses include the same observability headers as managed mode:

Analytics

Pass-through requests appear in the dashboard analytics alongside managed requests. They are tagged with metadata.mode = "passthrough" in the request logs, so you can filter and compare the two modes.

• Request count, tokens, latency — tracked normally
• Cost — estimated for reporting, but not deducted from the wallet
• Provider — shows the configured passthrough.provider value

Limitations

• Single upstream provider per project — the base_url applies to all pass-through requests. To proxy multiple providers, use separate projects.
• No routing or fallback — requests are forwarded as-is. Model routing, fallback chains, and provider strategies only apply in managed mode.
• No request/response transformation — the gateway does not modify the request or response body.
• No caching — Cloudflare AI Gateway caching is not used for pass-through requests.
• Cost is estimated — pricing is based on the model name from the request body. If the model is not in the pricing database, cost will not be reported.