Pointing Claude Code at
a custom API endpoint
From Anthropic's gateway documentation (checked 2026-09-02): two variables are enough — ANTHROPIC_BASE_URL for the endpoint and ANTHROPIC_AUTH_TOKEN for the credential, which is what puts the key in the Authorization header. They can also live in the env block of settings.json. Anthropic-hosted web and cloud sessions do not go through a gateway, and variables set there are not applied.
Four things to know
The minimum configuration
ANTHROPIC_BASE_URL points at the endpoint and ANTHROPIC_AUTH_TOKEN supplies the credential. In most cases that is all you need.
Where the credential lands
The documentation is explicit: this environment variable is what puts the key into the Authorization header that the gateway reads.
The second place to configure
If you would rather not use environment variables, put the same keys in the env block of settings.json — the shape maps one to one.
Web and cloud sessions
The documentation states that Anthropic-hosted products always use Anthropic's API, and gateway variables set in a cloud session's environment configuration are not applied.
Why those two variables are enough
Claude Code's egress is configurable: ANTHROPIC_BASE_URL decides where requests go and ANTHROPIC_AUTH_TOKEN decides what credential travels with them. The documentation puts the second one plainly — that environment variable is the step that places the key in the Authorization header, and the header is exactly what a gateway reads. So as long as your endpoint speaks the Anthropic protocol and authenticates on the Authorization header, the integration works with no client code changes.
The two documented forms (checked 2026-09-02)
The first form is environment variables: set ANTHROPIC_BASE_URL to your endpoint and ANTHROPIC_AUTH_TOKEN to the credential. The second is the env block in settings.json, using the same key names. The documentation also describes apiKeyHelper: a command Claude Code runs to fetch your gateway credential instead of reading it from a static environment variable, which suits credentials that need rotating. Two further sections — adding gateway models to the model picker, and turning off traffic outside the gateway path — are worth reading for an enterprise deployment.
Three steps to connect
Set the two variables: ANTHROPIC_BASE_URL to the endpoint and ANTHROPIC_AUTH_TOKEN to the credential. Try it in a clean shell first rather than writing straight into your global configuration.
Send one minimal request to confirm it works, and check that the model echoed in the response is the one you requested — that also tells you whether a rewriting layer sits in between.
Once it is stable, make it permanent: move it into the env block of settings.json, or inject it in CI from your secret store (the documented CI shape passes the credential from secrets into ANTHROPIC_AUTH_TOKEN). If the credential needs rotating, switch to apiKeyHelper.
Documented by Anthropic vs ask your endpoint provider
Documented by Anthropic
① What ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN each do. ② That the credential travels in the Authorization header. ③ That the env block of settings.json is an equivalent second form. ④ That apiKeyHelper fetches the credential via a command instead of a static variable. ⑤ That Anthropic-hosted web and cloud sessions do not go through a gateway and variables set there are not applied.
Ask your endpoint provider
Whether the base URL should carry a path suffix, which model ids are served, whether 1M context and caching are supported, and what the concurrency ceiling is — all of that depends on the endpoint you are connecting to, and Anthropic's documentation will not answer it for them. On a 404, the path portion of your base URL is the first thing to check against their documentation; on a 401, confirm the credential is travelling in the Authorization header and not somewhere else.
Two places to configure
Environment variables
Fastest to change and right for the first working attempt. The downside is that it is easy to lose — a new terminal or a different CI runner and it is gone — and the credential sits in the process environment. Good for validation and one-off tasks.
The env block in settings.json
Travels with the configuration rather than depending on your current shell, so it suits making things permanent. The credential is still written to disk in the clear, so if it needs rotating or should not be on disk, use apiKeyHelper instead: a command Claude Code calls to fetch the credential when it needs one.
The three usual sticking points
① Set but not taking effect: confirm the variable is visible to the process you are actually running, and that it is not shadowed by a same-named key in settings.json — when both exist, the effective load order decides. ② Not taking effect on web or cloud sessions: this is documented behaviour, because those are Anthropic-hosted products that always use Anthropic's own API. ③ Account-identity features behaving oddly: the documentation notes that a session authenticated with ANTHROPIC_AUTH_TOKEN can get an availability-check result that disagrees with the organisation's setting, because that check requires a claude.ai login or an Anthropic API key.
On QCode
We provide an Anthropic-protocol-compatible endpoint, configured with exactly the two variables above. Once connected, do two things straight away: send one minimal request and check that the echoed model matches what you requested, and reconcile usage against the bill once to confirm the deduction basis matches your expectation. Both take minutes, and they keep "connected to the wrong thing" and "priced differently than I assumed" from surfacing after you have scaled up.
FAQ
What is the minimum set of variables?
Two: ANTHROPIC_BASE_URL for the endpoint and ANTHROPIC_AUTH_TOKEN for the credential. The documentation states that the latter is the variable that places the key in the Authorization header.
Should the base URL include a path suffix?
That depends on the endpoint you are connecting to; Anthropic's documentation does not answer it for them. The quickest way to settle it is to follow the provider's documentation and send one minimal request — if you get a 404, the path portion is the first thing to check.
Can I avoid environment variables entirely?
Yes — put the same keys in the env block of settings.json. If the credential needs rotating, or you would rather it not sit on disk in the clear, use apiKeyHelper instead: a command Claude Code runs to fetch the credential.
Why does it not take effect on the web version?
This is documented behaviour: Anthropic-hosted products such as the web version always use Anthropic's own API and are not part of a gateway deployment, so gateway variables set in a cloud session's environment configuration are not applied. If traffic must stay on your gateway, do not rely on that path.
How do I configure it in CI?
The documented shape passes the credential from your secret store into ANTHROPIC_AUTH_TOKEN, with the base URL set as usual. Do not put the credential into a configuration file in the repository — that is no different from hard-coding it.
What is the first thing to verify once it connects?
That the model echoed in the response is the one you requested. If it carries a prefix, suffix or provider name that was not in your request, a rewriting layer sits in between. Not necessarily bad, but it determines how you should attribute what you later see on the bill.
Sources
What the two environment variables do, that the credential travels in the Authorization header, the settings.json env block form, the definition of apiKeyHelper, and that Anthropic-hosted products always use Anthropic's API while gateway variables set in a cloud session's environment configuration are not applied: Anthropic's documentation "Connect Claude Code to an LLM gateway" (code.claude.com/docs/en/llm-gateway-connect, fetched 2026-09-02). The path shape, available models and limits of any specific endpoint depend on the provider you connect to; this page does not answer for them.
Two variables, tried in a clean shell first
Once it works, verify the echoed model and reconcile usage before you commit it to configuration.
Further reading
Cline with an OpenAI-compatible endpoint
How custom endpoint configuration looks in a different class of client.
How to judge whether an AI API relay is worth using
What to verify once connected: the echoed model, cache hits and usage reconciliation.
Claude Code complete guide
From installation through the everyday workflow.
The documentation quoted here was fetched on 2026-09-02 and may be updated. The path shape, model set and limits of any specific endpoint are governed by that provider's documentation; client behaviour is governed by Anthropic's own documentation.