Claude Code LLM Gateway: Routing, Credentials, and Headers

A gateway gives an organisation one place to manage five things:

• Credentials: the provider key stays on the gateway. Developers hold a gateway credential, and offboarding someone revokes one key.
• Usage tracking: usage is attributed by developer or team, whichever provider served the request.
• Cost controls: budgets and rate limits are enforced in one place.
• Audit logging: every model request can be logged for compliance.
• Provider switching: change the upstream in the gateway's configuration, without touching laptops, as long as the gateway exposes one Anthropic-format endpoint whatever the upstream.

The cost is that the gateway becomes infrastructure you operate, and it has to keep up with Claude Code. New capabilities arrive as new anthropic-beta header values and new request fields. A gateway that strips or rejects them breaks the matching features, sometimes with an error and sometimes silently.

Billing changes too. While a gateway credential (or an apiKeyHelper) is active, requests carry that credential instead of a developer's claude.ai login, so subscription usage limits do not apply and the traffic is billed per token to whoever owns the key the gateway forwards, such as your Console organisation or your Bedrock account. Setting only ANTHROPIC_BASE_URL without a gateway credential routes traffic through the gateway but still bills the developer's subscription.

Every connection needs two variables: the gateway's base URL and a credential. Which credential variable you use decides which HTTP header carries it:

• ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer .... Use it when the gateway team says "bearer token" or "Authorization header".
• ANTHROPIC_API_KEY is sent as x-api-key: .... Use it when they say "API key" or "x-api-key".
• apiKeyHelper is a command whose output is sent in both headers. Use it when the credential rotates or comes from a vault.

A credential in the wrong variable reaches the gateway in a header it does not read, and you get 401.

Test with shell exports first, before Claude Code is involved:

1export ANTHROPIC_BASE_URL=https://llm-gateway.example.com2export ANTHROPIC_AUTH_TOKEN=sk-gateway-key3 4curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \5  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \6  -H "anthropic-version: 2023-06-01" \7  -H "content-type: application/json" \8  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

A JSON body starting with {"id":"msg_ means the URL and credential work. An "unknown model" error also proves the credential works, since the gateway authenticated the request before rejecting the model. A 401 means switch to the other credential variable.

Then start claude from the same shell and run /status. The Anthropic base URL row should show the gateway, and an Auth token or API key row should name your variable. If you see a Login method row with a claude.ai account instead, the credential did not reach the session.

For an organisation, the sequence is the same whichever gateway product you run:

1. Deploy the gateway and give it the provider credential. 2. Issue each developer their own gateway credential, so usage is attributed and offboarding revokes one key. 3. Distribute the base URL through a managed settings file and the credential through your secrets tooling, so developers configure nothing. 4. Have each developer check /status before they depend on it.

For rotating credentials, an apiKeyHelper is a command that prints the current key. Claude Code caches its output for five minutes by default (CLAUDE_CODE_API_KEY_HELPER_TTL_MS changes that) and sends it in both credential headers:

1{2  "apiKeyHelper": "~/bin/get-gateway-key.sh",3  "env": {4    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",5    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "900000"6  }7}

The helper must print nothing but the key; since v2.1.227 a banner or log line alongside it makes the helper fail.

To make the gateway the only allowed destination on managed machines, set allowedProviders to ["customEndpoint"] in the managed settings file and put the gateway's ANTHROPIC_BASE_URL in that file's env block (Claude Code v2.1.285 or later). Claude Code then refuses sessions pointed anywhere else, including Anthropic directly or a developer's own proxy.

An Anthropic-format gateway serves POST /v1/messages (Claude Code sends /v1/messages?beta=true, so match on the path) and optionally /v1/messages/count_tokens. Without token counting, Claude Code falls back to a character-based estimate of context use.

The rules from Anthropic's compatibility guide:

• Forward anthropic-version and anthropic-beta unchanged. Do not allowlist individual beta values; the set changes with every release.
• Forward request body fields unchanged, as an open list. Many capabilities are a pair: a beta header plus a body field. Strip one half and you get a hard 400; strip both and the feature turns off quietly.
• Keep cache_control markers wherever they appear, and do not flatten block-form system content into a string. Breaking this produces no error; every turn is just billed as uncached input.
• Stream without buffering. Claude Code reads server-sent events as they arrive and expects the full sequence through message_stop. A gateway that buffers stalls the client, and one that drops SSE ping events can trip the idle timeout during long thinking pauses.
• Forward error bodies unmodified. Claude Code's automatic recovery, such as retrying without a rejected capability, matches on the upstream's error wording.

Headers you may consume rather than forward include the credential headers and x-claude-code-session-id, which identifies all requests from one session. On requests from subagents, x-claude-code-agent-id identifies the agent, which helps attribute the cost of parallel agents.

Most gateway problems show up in one of two places: at authentication, as 401 or an unexpected login screen, or on the first real request, as a 400 naming a field the upstream does not accept. The curl test from the connect section separates them. If curl works and Claude Code does not, the problem is in how Claude Code receives the configuration, or in fields that only real sessions send.

The WAF case is worth remembering because it is confusing. A short curl test passes, but real prompts contain XML-style tags and source code that match cross-site-scripting body rules, so a firewall in front of the gateway blocks them before the gateway logs anything.

A gateway carries model requests. It is not a full egress control for Claude Code:

• Background traffic such as version checks, telemetry, and release notes goes to Anthropic and to services like GitHub, outside the gateway path. Since v2.1.246, Claude Code does not attach the gateway credential to that traffic. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 turns most of it off, but it also disables auto-updates, so plan another update path.
• The fast-mode availability check and the WebFetch domain safety check call api.anthropic.com directly. On a network that blocks it, /fast reports a connectivity error while inference keeps working. skipWebFetchPreflight: true turns the WebFetch check off.
• Tools Claude runs are not model requests at all. A curl or npm install in the Bash tool uses the machine's normal network. Use the sandbox's network allowlist for that.

And the gateway only controls what reaches it. A developer who unsets the variables talks to Anthropic directly, unless managed settings pin allowedProviders and the network blocks other routes.

Use a gateway you control, or a local LiteLLM proxy pointed at your own API key.

1. Export ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, run the curl test, and confirm a msg_ response. 2. Swap the token into ANTHROPIC_API_KEY instead and rerun curl with the Authorization header. Note the 401; this is the most common misconfiguration. 3. Start claude, run /status, and confirm the base URL and credential rows. 4. Ask Claude a question that reads a few files, then check the gateway logs for the x-claude-code-session-id header and the anthropic-beta values it received. 5. Move the two variables into ~/.claude/settings.json, open a new terminal without the exports, and confirm /status still shows the gateway.

Pass criterion: the curl test and a real session both succeed, you can find one session's requests in the gateway logs by session ID, and you can say which header your gateway reads the credential from.