Guides

Claude Code ANTHROPIC_BASE_URL and AUTH_TOKEN: set up a custom API endpoint

Published November 5, 2026 · Last checked November 5, 2026

Claude Code talks to Anthropic by default. To send it to another Anthropic-compatible endpoint, a gateway or a relay, you set two environment variables: ANTHROPIC_BASE_URL for the address and ANTHROPIC_AUTH_TOKEN for the credential. This page covers what each variable does, the places you can set them, the Windows commands, the VS Code, JetBrains and Claude Desktop differences, how to confirm it worked, and a checklist for when it does not. It follows Anthropic's Connect Claude Code to an LLM gateway page and the CoreCode docs, checked on November 5, 2026.

What the two variables do

Anthropic's environment variable reference describes them like this:

So the choice between the two credential variables is a header choice. Anthropic's gateway page says to use ANTHROPIC_AUTH_TOKEN when the gateway wants a "bearer token" or an "Authorization header", and ANTHROPIC_API_KEY when it wants an "API key" or "x-api-key". If you were not told which, start with ANTHROPIC_AUTH_TOKEN. A credential in the wrong variable reaches the endpoint in a header it does not read, and the request fails with 401.

When several credentials are present, Claude Code picks in this order: cloud provider credentials (Bedrock, Vertex, Foundry), then ANTHROPIC_AUTH_TOKEN, then ANTHROPIC_API_KEY, then apiKeyHelper, then CLAUDE_CODE_OAUTH_TOKEN, and a claude.ai login last. A gateway credential variable therefore beats a saved claude.ai login, which stays saved but unused.

One detail catches people: setting only ANTHROPIC_BASE_URL, with no credential variable, does not replace the subscription. Requests go to the new address, but a saved claude.ai login is still the credential, so its limits and billing still apply.

Where to set them

In the shell

Good for a first test. Anthropic recommends starting with shell exports, checking that they work, and only then moving the values into a file. Replace the address with your endpoint's:

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-your-key
claude

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-key"
claude

These apply only to that terminal and to programs started from it. An editor launched from the dock or Start menu does not see them. To keep them across terminals, add the same lines to ~/.zshrc, ~/.bashrc, or your PowerShell $PROFILE.

In settings.json

To apply everywhere Claude Code runs, put the variables in the env block of a settings file:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key"
  }
}

• ~/.claude/settings.json applies to all your projects. On Windows it is %USERPROFILE%\.claude\settings.json.
• .claude/settings.local.json applies to one project. Add it to your gitignore before you put a credential in it.
• Do not put the credential in a project's .claude/settings.json. That file is committed and shared with everyone who clones the repository.

If the file already has content, merge only the env block. When a shell export and a settings-file env block set the same variable, the settings-file value applies.

Anthropic's settings page lists the general precedence, highest first, as managed settings, command line, project local, shared project, then user. It also says environment variables are not a level in that stack: for pairs that have both a shell variable and a settings key, which one wins is decided pair by pair. For these two variables, the rule above is the one that is documented.

There is one startup quirk. In an interactive session, an env block in a project's .claude/settings.json or .claude/settings.local.json applies only after the first-run wizard and the folder trust prompt. If Claude Code asks you to log in even though a curl test works, set ANTHROPIC_AUTH_TOKEN somewhere it is read before first-run setup: a shell export or the user-level ~/.claude/settings.json.

On Windows

The PowerShell lines above work for the current window. To make them permanent, CoreCode's Windows guide uses setx, then you open a new terminal, because setx does not change windows that are already open:

setx ANTHROPIC_BASE_URL https://llm-gateway.example.com
setx ANTHROPIC_AUTH_TOKEN sk-your-key

The settings file route avoids the question: create %USERPROFILE%\.claude\settings.json and save it as UTF-8. PowerShell, Git Bash and the VS Code extension all read that file. Check that Notepad did not save it as settings.json.txt. Full install and error notes are in Claude Code on Windows.

VS Code, JetBrains and Claude Desktop

VS Code and Cursor

The CoreCode IDE guide shares ~/.claude/settings.json between the CLI and the extension: write the env block there, tick Disable Login Prompt in the extension settings, then quit VS Code completely and reopen it. Variables exported in a terminal are not seen if you launch VS Code from the desktop; start it from a terminal with code . or use the settings file.

Anthropic's gateway page gives a different route: set claudeCode.environmentVariables in VS Code's own user settings (Preferences: Open User Settings (JSON)). It notes that the extension checks credentials from that setting before launching, while values in ~/.claude/settings.json reach the spawned process but not the extension's own login check:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-key" }
  ]
}

If the extension keeps showing a sign-in screen after one route, try the other. See Claude Code in VS Code, Cursor and JetBrains for the full steps.

JetBrains

The JetBrains plugin does not bundle Claude Code. It runs the command-line version in the IDE terminal, so the CLI configuration above is the configuration.

Claude Desktop

The desktop app reads its gateway from its own third-party inference configuration, not from ANTHROPIC_BASE_URL or settings.json. To set it by hand, open Help, Troubleshooting, Enable Developer Mode, let the app restart, then open Developer, Configure Third-Party Inference and enter the gateway base URL. CoreCode's Desktop guide also fills in the gateway API key, keeps the credential kind at Static API key and the auth scheme at bearer, and notes that the Test connection button can fail for reasons unrelated to your settings. See Connect Claude Desktop. With a gateway configuration active, Anthropic notes that Remote Control is unavailable.

Check that it is working

Two checks, in this order.

First, with the variables exported in your shell, send a one-token request straight to the endpoint. This separates "the endpoint or key is wrong" from "Claude Code is not picking up my settings":

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

A JSON response starting with {"id":"msg_ means the address and credential work. An error naming an unknown model still proves they work, because the endpoint authenticated you before rejecting the model name. A 401 means the credential was rejected; try the other credential variable. Note that this request appends /v1/messages to $ANTHROPIC_BASE_URL, and the examples on Anthropic's page and in CoreCode's docs give the base URL without a path, for example https://corecode.live.

Second, start claude from the same shell, send a message, and run /status. Anthropic's page says to look for two lines. The Anthropic base URL line shows your endpoint, and only appears when an address is set. An Auth token or API key line naming the variable you set means the credential is active rather than a saved claude.ai login. CoreCode's docs call the first line Base URL. For a quick end-to-end test, claude -p "reply ok" should print a reply.

When it is not working

Other error texts and causes are in Errors and the FAQ.

Using CoreCode as the endpoint

CoreCode is a relay answered by official Claude accounts. Claude Code points at it with ANTHROPIC_BASE_URL=https://corecode.live, and the key you create in the console goes in ANTHROPIC_AUTH_TOKEN. The exact steps, including the recommended settings and the group to create the key in, are in Claude Code. If you are weighing a subscription against pay-as-you-go keys first, read Claude Code subscription vs API. Anthropic does not endorse, maintain or audit third-party gateway products, so check any endpoint you use against its own documentation and test it with the curl request above before you rely on it.

FAQ

Sources

• Claude Code: Connect Claude Code to an LLM gateway (credential variables and headers, shell and settings-file setup, settings-file value wins, /status check, curl test, VS Code, desktop app, troubleshooting table; checked November 5, 2026)
• Claude Code: Other LLM gateways (setting only the base URL does not replace a subscription login; Anthropic does not endorse third-party gateways; checked November 5, 2026)
• Claude Code: Environment variables (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY; checked November 5, 2026)
• Claude Code: Authentication (authentication precedence; checked November 5, 2026)
• Claude Code: Settings (settings files and precedence; checked November 5, 2026)
• CoreCode docs: Claude Code, Windows, VS Code and JetBrains, Claude Desktop, Errors