Cloudflare AI Gateway × Claude Code — Requirement Analysis

Cloudflare AI Gateway × Claude Code

Mapping the stated requirements to platform capabilities — what is available today, what is achievable now, and what is on the roadmap.
Context. Over 1,400 engineers are expected to use Claude Code through AI Gateway daily. This document groups the requirements and states the recommended approach and current status for each.
TODAY Native, generally available CLOSED BETA Available now via early-access program ROADMAP Native capability in development
Foundational note — protocol ≠ model. Claude Code speaks only the Anthropic Messages API and connects to the gateway's Anthropic endpoint, which today is a transparent pass-through to Anthropic (Claude) models. Cross-provider and dynamic routing are exposed on the OpenAI-compatible schema, which Claude Code does not speak. This is the root reason several items below are "roadmap" for Claude Code specifically, even though the underlying gateway capability already exists.

FLOWHow a request flows through AI Gateway

Claude Code
on the device — no provider key stored locally
↓
cf-aig-authorization — CF AI Gateway token, authenticates to the gateway
cf-aig-metadata — JSON tags (user/team, ≤5 keys) → written to the log
Cloudflare AI Gateway
Validates token, then applies: Logging & analytics · Rate / token limits · Caching · Guardrails / DLP
↓
Attaches provider credentials — one of two modes:
Unified Billing — CF-held credits, single bill  ·  BYOK — key kept in Secrets Store, resolved per request
LLM provider
Anthropic Model only by default
Note — configuring device environment variables

Plan A — Static token + templated metadata TODAY · NO IAA

  • Push the base URL and cf-aig-authorization: Bearer <shared token> to all devices uniformly via MDM.
  • Template metadata with MDM variable substitution (Jamf / Intune $EMAIL, etc.): expand cf-aig-metadata: {"user":"$EMAIL"} into a per-user value at deploy time.

Plan B — Identity-Aware Access + apiKeyHelper CLOSED BETA · RECOMMENDED

  • Push an identical managed-settings.json to every device: only the base URL + apiKeyHelper. No static secret on the device.
  • Each user authenticates via SSO → apiKeyHelper fetches a short-lived token per session (TTL via CLAUDE_CODE_API_KEY_HELPER_TTL_MS).
  • user/team attribution is derived automatically from the authenticated SSO identity (cf-aig-identity) → no need to template per-user metadata, and it cannot be spoofed.

BASELINEAvailable today, out of the box

Once Claude Code points at the gateway's Anthropic endpoint, the following apply automatically:

TODAYUnified Billing — a single Cloudflare bill; provider keys are not distributed to devices.
TODAYFull request logging & analytics — tokens, cost and request volume per request.
TODAYCustom metadata, caching, guardrails, rate/token limiting
TODAYModel sourcing options for Claude models — Unified Billing, Bring-Your-Own-Key, Amazon Bedrock, Google Vertex AI.
Setup guide

AModel switching & dynamic routing

Requirements covered
  • Use multiple LLM providers / models within Claude Code.
  • Let users switch freely among an approved set of models.
  • Dynamic routing based on user metadata and usage, from a virtual model endpoint.
  • Automatic fallback to another approved model when a premium model's budget/quota is exceeded — with no client-side change.

Approach AI Gateway provides Dynamic Routing — virtual model endpoints, conditional routing on metadata, and per-route rate/budget limits with automatic fallback. These deliver central model control, metadata/usage-based routing, and client-transparent budget fallback as platform features. Today they are invoked through the OpenAI-compatible schema; because Claude Code speaks the Anthropic Messages schema, it cannot invoke them directly yet. Enabling Claude Code to drive multiple providers requires bidirectional Anthropic↔other-provider translation, which is in development.

RequirementStatusNotes
Multiple providers/models in Claude CodeROADMAP Native path in development. Today, Claude Code natively reaches Claude models only.
Free switch within an approved setTODAY ROADMAP Switching models is available today (client-side). Central enforcement of the approved set is on the roadmap (identity-based model access).
Dynamic routing by metadata + usage (virtual endpoint)ROADMAP Capability exists in Dynamic Routing; reaching it from Claude Code's Anthropic endpoint is on the roadmap. A third-party protocol-translation proxy, or self-authored code on a Worker, may be needed as an alternative.
Auto budget/quota fallback, client-transparentROADMAP Native Dynamic Routing feature (budget-limit node + fallback), already client-transparent — but reachable only via the OpenAI schema today. Native for Claude Code is on the roadmap. A third-party protocol-translation proxy, or self-authored code on a Worker, may be needed as an alternative.
Setup guide

BLogging & analytics (per user / team)

Requirements covered
  • View usage, cost and request volume per user or team, via AI Gateway logging/analytics.

Approach AI Gateway logs token usage, cost and request volume per request, and supports custom metadata. Tag each request with a user/team identifier, then filter or group by it in logs and analytics.

RequirementStatusNotes
Usage / cost / volume per user or teamTODAY Achievable today via custom metadata (cf-aig-metadata): tag user/team, then filter and group.
Trusted, non-spoofable identity attributionCLOSED BETA Verified user/team from SSO is delivered by identity-aware access (in closed beta). Today, client-supplied metadata is used instead.

CAPI-token / credential management

Requirements covered
  • Avoid distributing/hard-coding long-lived API keys onto end-user devices or into configuration files.

Approach With Unified Billing or BYOK, the provider API key lives server-side and is never distributed to devices — the device carries a Cloudflare gateway token, not the provider key. Combined with identity-aware access (Theme E), devices can rely solely on short-lived SSO tokens, with no long-lived secret at all.

RequirementStatusNotes
Provider API key not on device / not hard-codedTODAY Achievable today via Unified Billing / BYOK — provider credentials remain server-side.
No long-lived secret on the device at allCLOSED BETA Delivered via identity-aware access (short-lived SSO tokens) — see Theme E. In closed beta.

DUsage limits (rate / token / budget)

Requirements covered
  • Apply rate limiting per user, not only at the gateway or API-key level.

Approach AI Gateway provides gateway-level rate limiting today. Finer-grained per-user/team limits and budget caps are delivered through metadata-key-based controls. An identity-based spend-limit capability is on the roadmap, which will natively enforce limits per identity.

RequirementStatusNotes
Gateway-level rate limitingTODAY Available today; applied uniformly across the whole gateway.
Per-user/per-team rate & token/budget limitsROADMAP Native identity-aware spend limits are in development. Achievable today through metadata-key-based controls.

EIdentity-Aware Access

Requirements covered
  • Issue short-lived credentials dynamically, per user.
  • Combine Claude Code's apiKeyHelper with a Cloudflare Access token, so that users authenticated through Cloudflare Access obtain a temporary token.

Approach Cloudflare Access sits in front of the gateway. Users authenticate through your IdP (SSO), and the gateway receives a verified identity on every request. Claude Code integrates via apiKeyHelper running a Cloudflare Access login, which yields a short-lived Access token per session, with ANTHROPIC_BASE_URL pointed at the Access-protected gateway — no long-lived key on the device, and identity flows into logs.

Apply / learn more
RequirementStatusNotes
Per-user dynamically issued short-lived credentialsCLOSED BETA Yes — this is precisely what identity-aware access provides (SSO login flow). In closed beta.
Claude Code apiKeyHelper + Cloudflare Access tokenCLOSED BETA Yes — this is the documented Claude Code setup pattern for identity-aware access. In closed beta.
Per-user model allowlists & identity-aware spend limitsROADMAP The identity front-door (authentication & attribution) is the first phase; per-user policy enforcement is a later phase.

NEXTRecommended path

PhaseWhat to do
Phase 1 — TodayRun Claude Code on Claude models through the gateway's Anthropic endpoint with Unified Billing. Use custom metadata for per-user/team usage and cost reporting. Add a lightweight proxy where per-user policy, central model control, or budget fallback is needed today.
Phase 2 — As capabilities landAdopt identity-aware access (SSO short-lived tokens, no device secret, trusted attribution), then central identity-based model governance and cost/smart routing — consolidating the Phase 1 proxy responsibilities onto native gateway features.
Source: Cloudflare AI Gateway official documentation. Status reflects current understanding and may change as features develop.