Roll out an LLM gateway for your organization changedllm-gateway-rollout
Nearest release: v2.1.284, published 16 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 28 Sep 2026 00:42 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 28 Sep 2026 23:37 UTC.
Upstream edited
Recorded here
Lines+25added
Lines−25removed
From line
45
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits12to this page, all time
The whole hunk
from line 45, old and new numbered
/
from line 45
4545
4646The steps involve three different credentials, and the checkpoints name them by placeholder so you can tell which one is at fault when something fails:
4747
48| Credential | Who holds it | Placeholder in checkpoints |
49| :-------------------------------- | :--------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |
50| Provider credential | The gateway, which forwards it to the upstream provider | Configured on the gateway; never appears in client commands |
51| Gateway administrative credential | You, if your gateway product issues one for its admin or test interface | `<gateway-key>` |
52| Developer key | Each developer, issued by the gateway in [Issue developer credentials](#issue-developer-credentials) | `<developer-key>` |
48| Credential | Who holds it | Placeholder in checkpoints |
49| :- | :- | :- |
50| Provider credential | The gateway, which forwards it to the upstream provider | Configured on the gateway; never appears in client commands |
51| Gateway administrative credential | You, if your gateway product issues one for its admin or test interface | `<gateway-key>` |
52| Developer key | Each developer, issued by the gateway in [Issue developer credentials](#issue-developer-credentials) | `<developer-key>` |
5353
5454### Confirm the gateway routes your models
5555
from line 159
159159
160160The same set of variables applies whichever path you choose. Most rollouts only need `ANTHROPIC_BASE_URL` and a credential; include the conditional rows when your gateway setup calls for them.
161161
162| Variable or setting | What it does | Include when |
163| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
164| `ANTHROPIC_BASE_URL` | Sends Claude Code's API requests to the gateway instead of `api.anthropic.com` | Always |
165| `apiKeyHelper`, or a credential in `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` | Authenticates each request to the gateway. The helper runs a command to fetch the key; the variables hold a static key, sent as `Authorization: Bearer` and `x-api-key` respectively | Always; one of the three |
166| `ANTHROPIC_CUSTOM_HEADERS` | Adds extra HTTP headers to every API request | Your gateway requires a tenant or routing header on every request |
167| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | Sends the [gateway hint headers](/docs/en/llm-gateway-protocol#gateway-hint-headers), which classify each request for routing and scheduling decisions at the gateway. Requires Claude Code v2.1.273 or later | Your gateway reads the hint headers |
168| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Queries the gateway's `/v1/models` at startup and adds the returned names to the `/model` picker | Your gateway serves `/v1/models` and you want developers' pickers populated from it |
169| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Stops Claude Code sending pre-release capability headers and body fields. [Disable pre-release capabilities](/docs/en/llm-gateway-protocol#disable-pre-release-capabilities) covers the exact scope | Your gateway forwards to an Amazon Bedrock or Google Cloud's Agent Platform upstream that rejects beta fields. See [Gateway requirements](#gateway-requirements) |
170| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` or `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | Restores [fast mode](/docs/en/fast-mode) when its availability check, which calls `api.anthropic.com` directly rather than following `ANTHROPIC_BASE_URL`, fails, is intercepted, or is skipped for lack of an Anthropic credential | Your organization uses fast mode, and developers authenticate with `ANTHROPIC_AUTH_TOKEN` alone, with a gateway-issued key in `ANTHROPIC_API_KEY` or from an `apiKeyHelper`, or your network blocks or intercepts direct requests to `api.anthropic.com`; [use fast mode behind proxies and LLM gateways](/docs/en/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) covers which of the two variables matches your configuration |
171| `ANTHROPIC_MODEL` or [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/en/model-config) | Set which model name Claude Code requests for the main session and for background traffic | Your gateway routes model names that don't match Claude Code's defaults, or you route [background functionality](/docs/en/costs#background-token-usage) to a different model. Route both the override names and the built-in model IDs Claude Code requests when no override is set, since some background sub-calls request a built-in ID regardless of the override; [model configuration](/docs/en/model-config) covers which model each part of a session uses |
172| `ANTHROPIC_BEDROCK_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL`, `ANTHROPIC_FOUNDRY_BASE_URL`, or `ANTHROPIC_AWS_BASE_URL` with the [variables for that provider](/docs/en/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | Point Claude Code at the gateway through a provider-specific base URL. Amazon Bedrock and Google Cloud's Agent Platform also switch to those providers' native request format | Your gateway fronts Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or the Claude Platform on AWS; see [API formats](/docs/en/llm-gateway-protocol#api-formats) |
162| Variable or setting | What it does | Include when |
163| :- | :- | :- |
164| `ANTHROPIC_BASE_URL` | Sends Claude Code's API requests to the gateway instead of `api.anthropic.com` | Always |
165| `apiKeyHelper`, or a credential in `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` | Authenticates each request to the gateway. The helper runs a command to fetch the key; the variables hold a static key, sent as `Authorization: Bearer` and `x-api-key` respectively | Always; one of the three |
166| `ANTHROPIC_CUSTOM_HEADERS` | Adds extra HTTP headers to every API request | Your gateway requires a tenant or routing header on every request |
167| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | Sends the [gateway hint headers](/docs/en/llm-gateway-protocol#gateway-hint-headers), which classify each request for routing and scheduling decisions at the gateway. Requires Claude Code v2.1.273 or later | Your gateway reads the hint headers |
168| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Queries the gateway's `/v1/models` at startup and adds the returned names to the `/model` picker | Your gateway serves `/v1/models` and you want developers' pickers populated from it |
169| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Stops Claude Code sending pre-release capability headers and body fields. [Disable pre-release capabilities](/docs/en/llm-gateway-protocol#disable-pre-release-capabilities) covers the exact scope | Your gateway forwards to an Amazon Bedrock or Google Cloud's Agent Platform upstream that rejects beta fields. See [Gateway requirements](#gateway-requirements) |
170| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` or `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | Restores [fast mode](/docs/en/fast-mode) when its availability check, which calls `api.anthropic.com` directly rather than following `ANTHROPIC_BASE_URL`, fails, is intercepted, or is skipped for lack of an Anthropic credential | Your organization uses fast mode, and developers authenticate with `ANTHROPIC_AUTH_TOKEN` alone, with a gateway-issued key in `ANTHROPIC_API_KEY` or from an `apiKeyHelper`, or your network blocks or intercepts direct requests to `api.anthropic.com`; [use fast mode behind proxies and LLM gateways](/docs/en/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) covers which of the two variables matches your configuration |
171| `ANTHROPIC_MODEL` or [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/docs/en/model-config) | Set which model name Claude Code requests for the main session and for background traffic | Your gateway routes model names that don't match Claude Code's defaults, or you route [background functionality](/docs/en/costs#background-token-usage) to a different model. Route both the override names and the built-in model IDs Claude Code requests when no override is set, since some background sub-calls request a built-in ID regardless of the override; [model configuration](/docs/en/model-config) covers which model each part of a session uses |
172| `ANTHROPIC_BEDROCK_BASE_URL`, `ANTHROPIC_VERTEX_BASE_URL`, `ANTHROPIC_FOUNDRY_BASE_URL`, or `ANTHROPIC_AWS_BASE_URL` with the [variables for that provider](/docs/en/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway) | Point Claude Code at the gateway through a provider-specific base URL. Amazon Bedrock and Google Cloud's Agent Platform also switch to those providers' native request format | Your gateway fronts Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or the Claude Platform on AWS; see [API formats](/docs/en/llm-gateway-protocol#api-formats) |
173173
174174#### Distribute through managed settings
175175
from line 254
254254
255255After rollout, three kinds of change reach the gateway over time. Each has a symptom to watch for and an action to take.
256256
257| Change | Symptom when the gateway hasn't kept up | Action |
258| :--------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
257| Change | Symptom when the gateway hasn't kept up | Action |
258| :- | :- | :- |
259259| New Claude Code releases add `anthropic-beta` values and request body fields | Developers report `400` errors naming a new field after they update Claude Code; see [feature pass-through](/docs/en/llm-gateway-protocol#feature-pass-through) | Forward `anthropic-*` headers and request bodies verbatim rather than allowlisting; test new Claude Code releases against the gateway before they reach developers, checking the areas in [Plan Claude Code version upgrades](#plan-claude-code-version-upgrades) |
260| New Claude models become available | Developers selecting a new model name get `404`; the `/model` picker doesn't list it | Add the model name to the gateway's routing configuration, then re-run the [routing check](#confirm-the-gateway-routes-your-models). If you distribute `ANTHROPIC_MODEL` or the default-model variables, update the managed settings |
261| Credentials expire or need rotation | All developer requests start failing with `401` from the upstream | Rotate the gateway's provider credential on its own schedule; developer keys rotate at the gateway, and an [`apiKeyHelper`](/docs/en/llm-gateway-connect#rotate-credentials-with-apikeyhelper) handles per-developer rotation without redistributing settings |
260| New Claude models become available | Developers selecting a new model name get `404`; the `/model` picker doesn't list it | Add the model name to the gateway's routing configuration, then re-run the [routing check](#confirm-the-gateway-routes-your-models). If you distribute `ANTHROPIC_MODEL` or the default-model variables, update the managed settings |
261| Credentials expire or need rotation | All developer requests start failing with `401` from the upstream | Rotate the gateway's provider credential on its own schedule; developer keys rotate at the gateway, and an [`apiKeyHelper`](/docs/en/llm-gateway-connect#rotate-credentials-with-apikeyhelper) handles per-developer rotation without redistributing settings |
262262
263263When sizing per-key rate limits, account for the client [retrying transient failures](/docs/en/errors#automatic-retries), including `429` responses, up to 10 times with backoff, honoring `Retry-After`. Keep the [compatibility guide](/docs/en/llm-gateway-protocol) as the reference for what each Claude Code release sends.
264264
from line 268
268268
269269When you test a release, new headers or request fields that the gateway rejects appear as the `400` errors described in [Maintain the gateway](#maintain-the-gateway). The table below covers version-dependent changes that don't produce an error, with the setting that keeps each one constant across upgrades.
270270
271| Area | What can change when developers upgrade | Setting that keeps it constant |
272| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
273| Feature-flag defaults | Sessions that [don't fetch feature flags from Anthropic](/docs/en/env-vars#features-that-need-feature-flag-fetching), such as sessions on a cloud provider or with telemetry turned off, use the flag defaults built into the installed version. When a release changes one of those defaults, the behavior changes for those developers as soon as they upgrade | The version pin itself, `requiredMaximumVersion` or `DISABLE_UPDATES` |
274| Model capability assumptions | A model ID that the installed version doesn't recognize, such as the gateway alias `prod-opus`, runs on default assumptions for [adaptive reasoning](/docs/en/model-config#adaptive-reasoning-and-fixed-thinking-budgets), the effort parameter, and the [context window](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id) until a later version recognizes the ID or you map it | Route Anthropic model IDs at the gateway, or add a [`modelOverrides`](/docs/en/model-config#override-model-ids-per-version) entry that maps the Anthropic model ID to your alias. On a cloud provider connection, you can instead [declare a pinned model's capabilities](/docs/en/model-config#customize-pinned-model-display-and-capabilities) |
275| Default model and aliases | The model that new sessions start on by default, and the models that aliases such as `opus` and `sonnet` resolve to, are [built into each version](/docs/en/model-config#pin-models-for-third-party-deployments) and can change when developers upgrade | [`ANTHROPIC_DEFAULT_MODEL`](/docs/en/model-config#set-a-default-model-for-new-sessions) for the model new sessions start on, and the [`ANTHROPIC_DEFAULT_*_MODEL` variables](/docs/en/model-config#environment-variables), such as `ANTHROPIC_DEFAULT_OPUS_MODEL`, for what each alias resolves to. `ANTHROPIC_DEFAULT_MODEL` requires Claude Code v2.1.236 or later |
271| Area | What can change when developers upgrade | Setting that keeps it constant |
272| :- | :- | :- |
273| Feature-flag defaults | Sessions that [don't fetch feature flags from Anthropic](/docs/en/env-vars#features-that-need-feature-flag-fetching), such as sessions on a cloud provider or with telemetry turned off, use the flag defaults built into the installed version. When a release changes one of those defaults, the behavior changes for those developers as soon as they upgrade | The version pin itself, `requiredMaximumVersion` or `DISABLE_UPDATES` |
274| Model capability assumptions | A model ID that the installed version doesn't recognize, such as the gateway alias `prod-opus`, runs on default assumptions for [adaptive reasoning](/docs/en/model-config#adaptive-reasoning-and-fixed-thinking-budgets), the effort parameter, and the [context window](/docs/en/model-config#correct-the-window-for-a-gateway-or-custom-model-id) until a later version recognizes the ID or you map it | Route Anthropic model IDs at the gateway, or add a [`modelOverrides`](/docs/en/model-config#override-model-ids-per-version) entry that maps the Anthropic model ID to your alias. On a cloud provider connection, you can instead [declare a pinned model's capabilities](/docs/en/model-config#customize-pinned-model-display-and-capabilities) |
275| Default model and aliases | The model that new sessions start on by default, and the models that aliases such as `opus` and `sonnet` resolve to, are [built into each version](/docs/en/model-config#pin-models-for-third-party-deployments) and can change when developers upgrade | [`ANTHROPIC_DEFAULT_MODEL`](/docs/en/model-config#set-a-default-model-for-new-sessions) for the model new sessions start on, and the [`ANTHROPIC_DEFAULT_*_MODEL` variables](/docs/en/model-config#environment-variables), such as `ANTHROPIC_DEFAULT_OPUS_MODEL`, for what each alias resolves to. `ANTHROPIC_DEFAULT_MODEL` requires Claude Code v2.1.236 or later |
276276
277277## Related resources
278278
No line in this hunk matches that.