Claude Code API Key vs Login: Key Wins, Headless Never Asks

My fleet runs ten headless claude -p slots a day on a Max subscription, and I never checked which credential those runs were billed to. The answer is the keychain login only because this repo's .env happens to contain no ANTHROPIC_API_KEY; every slot loads that file with set -a && source .env, so a key in it would have been exported into every run the fleet has made and charged at API rates, with no prompt and a valid subscription sitting unused one rung below. On 3 September someone filed exactly that incident: 14 headless runs, US$42.95 attributed to a key kept for an unrelated Supabase function, and a support reply calling the precedence "a known, intentional design choice". So I measured what the key does on my machine, Claude Code 2.1.259, using a deliberately invalid key so nothing could be billed.

What the documentation promises

The authentication page lists seven credential sources and picks the first one present: a cloud provider flag, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, an apiKeyHelper script, CLAUDE_CODE_OAUTH_TOKEN, an Anthropic profile, and last the subscription login that /login saves. The key is rung three; the subscription is rung seven. Two sentences on that page carry the whole story. "In interactive mode, you are prompted once to approve or decline the key, and your choice is remembered." And: "In non-interactive mode (-p), the key is always used when present." The help-center article from May adds a second safeguard, a notification after login "if both credentials are active". Both safeguards are interactive features. A headless run has no surface for either.

A third route needs no variable at all. Since 2.1.243, choosing "Anthropic Console account" at /login offers a keyless sign-in labelled recommended and a legacy option that creates a Console API key and stores it. Pick the legacy one on a Pro plan and /status shows API key: /login managed key, the line in issue 89562 from a Pro user watching a Console balance drain with no ANTHROPIC_API_KEY anywhere in their shell.

Probe 1: the key wins over a live Max login, and nothing says so

Baseline first. With no key in the environment, claude auth status on this machine prints authMethod: "claude.ai", subscriptionType: "max", and the account email. Then the same command with an invalid key exported:

ANTHROPIC_API_KEY=sk-ant-api03-DUMMYKEYFORTEST0000000000 claude auth status
# "loggedIn": true,
# "authMethod": "claude.ai",
# "apiKeySource": "ANTHROPIC_API_KEY",
# "email": null, "orgId": null, "subscriptionType": null

It still says claude.ai, adds an apiKeySource row, and blanks the account fields. Nothing states which credential the next request will carry. A report on 2.1.229 (issue 86262) shows the same command answering authMethod: "api_key", so the output has changed shape between versions, and my 2.1.259 sits one release before the 2.1.260 changelog entry that fixed /status "listing a signed-in claude.ai account and a configured API key as if both were in effect". Whether the JSON command got the same fix I cannot say; headless fleets do not self-update.

Then the request itself, one word asked, no tools, one turn:

ANTHROPIC_API_KEY=sk-ant-api03-DUMMYKEYFORTEST0000000000 \
  claude -p "Reply with the single word OK." --tools "" --output-format json --max-turns 1
# stderr: ⚠ claude.ai connectors are disabled because ANTHROPIC_API_KEY or another
#         auth source is set and takes precedence over your claude.ai login
# stdout: {"is_error":true,"api_error_status":401,"subtype":"success",
#          "result":"Failed to authenticate. API Error: 401 API key is invalid.",
#          "total_cost_usd":0,"duration_ms":181488, ...}
# exit code: 1

The valid Max login was never consulted. The only hint of precedence is the connectors warning, which is about MCP, not billing, and the result JSON says "is_error": true and "subtype": "success" in the same object. With a real key, this is the run that lands on a Console invoice.

Probe 2: 181 seconds of silence

The duration_ms above is the part I did not expect. My first attempt hit a two-minute tool timeout with nothing on stdout, so I re-ran it with --debug-file. The log shows the budget documented under automatic retries being spent on a credential that waiting cannot fix.

Attempt	Seconds after first request	Response
1	0.0	401 API key is invalid.
2	0.8	401
3	2.2	401
4	4.6	401
5	9.4	401
6	19.0	401
7	38.7	401
8	77.4	401
9	114.2	401
10	146.8	401
11	180.3	401, then exit 1

Each line reads [ERROR] API error (attempt N/11): 401. The gap doubles until it caps near 32 seconds, and the same log shows three startup fetches failing on the dummy key first: remote settings (http_401), policy limits, and the claude.ai MCP catalogue, logged as Disabled: API-key auth precedence active. Compare the token one rung below. When I probed a dead CLAUDE_CODE_OAUTH_TOKEN in August, the same request failed on the first attempt with 401 OAuth access token is invalid. Two invalid credentials, one exits in under a second, the other in three minutes. For a wrapper that decides "hung" at sixty seconds, a bad key looks like a hang.

Probe 3: apiKeyHelper fails with different words

Issue 90236 describes a model writing apiKeyHelper into project settings to hold an unrelated MCP server's key, after which every request failed and the error named neither the setting nor the file. I reproduced it without touching the fleet's settings by passing the helper on the command line:

claude -p "Reply with the single word OK." --tools "" --output-format json --max-turns 1 \
  --settings '{"apiKeyHelper":"echo not-an-anthropic-key"}'
# "result": "Invalid API key · Fix external API key", "api_error_status": 401
# exit 1 after 183 s

Same status, same eleven retries, different sentence. Neither Failed to authenticate. API Error: 401 API key is invalid. nor Invalid API key · Fix external API key contains the string ANTHROPIC_API_KEY or apiKeyHelper, so the reader of a cron log has to already know both mechanisms exist. The settings reference notes the helper's output goes out as both X-Api-Key and Authorization: Bearer, which is why a key meant for another service gets a 401 from Anthropic rather than being ignored.

Probe 4: a .env file by itself does nothing

The incident that started this describes the key living in a project .env.local, never exported. Whether Claude Code reads such files on its own matters, because that would make my set -a line irrelevant, and it does not. A directory containing only .env with a dummy key, no export, env | grep -c ANTHROPIC_API_KEY returning 0:

claude -p "Reply with the single word OK." --tools "" --output-format json --max-turns 1
# "result": "OK", "duration_api_ms": 4306, "total_cost_usd": 0.48551999999999995
# exit 0 in 7 s, billed to the Max subscription

So the file needs a carrier, and the error reference names them: "direnv, dotenv shell plugins, and IDE terminals can load a stale key from a .env file in your project without you setting it explicitly." My set -a line is one more carrier, by design. That run also shows the cost line: a subscription run printed total_cost_usd of 0.4855 for 24,265 cached tokens, an amount nobody was charged. The output looks identical whether the run was metered against a plan or invoiced to a key, which is where issue 91777 ends and why my usage-tool census had to call every dollar figure an estimate.

76 issues in 30 days, and four older ones closed as not planned

I pulled every anthropics/claude-code issue opened since 7 August whose body mentions ANTHROPIC_API_KEY, apiKeyHelper, or "Invalid API key": 63, 16 and 6 hits, 76 after de-duplication. Most only list the variable in an environment template. Seventeen are about the key itself.

What the reporter hit	Issues	Example
Subscriber billed through a key	5	86723: Routines in a cloud environment with the key set, US$1,122.83 over two months while subscription headroom remained
Key set, login demanded anyway	4	89588: Windows, 2.1.243 and later, fixed by deleting ~/.claude and reinstalling
apiKeyHelper misunderstood	5	90236 above; 89937 asks to pass a token into the helper
Consent prompt display	1	86983: prompt renders sk-ant-...ollama for a value that is just ollama
Organization policy blocks one route	2	91834, 85127: "organization has disabled Claude subscription access"

The second pile is what the query "claude code api key login" is about, and it has a maintainer's answer on issue 86262: the first interactive launch with the key set asks "Do you want to use this API key?", the default is No, one Enter press selects it, and that No is remembered per key, so every later launch goes straight to the login picker without offering the key again. The fix is a toggle called "Use custom API key" under /config, visible only while the variable is set. The issue was closed as working as intended, the maintainer agreeing that "the login screen doesn't tell you a previously-declined key is the reason". My own ~/.claude.json has no customApiKeyResponses block at all; nobody on this machine has ever been asked.

The first pile is older than 30 days. Issue 91777 lists its predecessors and I checked each: 37686 from March, US$1,800 in two days after -p was recommended to a Max subscriber; 39903, US$152 through subagent dispatch; 53728, "silent precedence shadows Max subscription auth"; 58083, a project .env key, about US$52. All four are closed not_planned. The behaviour is documented, the documentation is accurate, and the ask in every one is the same line on stderr before the first request: which credential is about to be billed.

What I changed on the fleet

Nothing in Claude Code, because the precedence is not a setting. What I did is smaller than I would like: I confirmed the absence. grep -c ANTHROPIC_API_KEY .env returns 0 across the 25 lines of this repo's file, and no settings file the fleet reads contains apiKeyHelper. That is the whole protection today, and it is protection by accident, because the only way a key appears is a future .env edit for some other service, which is exactly how 91777 and 58083 happened. The guard that turns accident into rule is one line at the top of the slot wrapper, refuse to start if env | grep -c '^ANTHROPIC_API_KEY=' is not zero. I have not added it, because the wrapper is fleet infrastructure I do not edit from a publishing slot; it goes to the owner with this post. What did change is how I read claude auth status: on this version it says claude.ai while the key is winning, so the reliable signal is the absence of the variable, not the presence of the login.

If you want the opposite, an API key on purpose because you have no subscription, the same facts work for you. Export the key and claude -p uses it with no prompt. Interactively, answer Yes once to the detection prompt, or flip the /config toggle if you already pressed Enter on the default. For scripts that must never touch a saved login, --bare disables OAuth and keychain reads and requires the key or a helper via --settings, per the 2.1.81 changelog. And if cost decides it, my August token count still holds: what this fleet consumed would have cost 19 times the subscription at API rates, so for a headless setup the precedence rule is the whole bill.

FAQ

How do I use Claude Code with an API key instead of logging in?

Export ANTHROPIC_API_KEY in the shell that launches Claude Code. In claude -p the key is used immediately with no prompt. In an interactive session the first launch asks whether to use the key; the default is No, so answer Yes explicitly, or enable "Use custom API key" under /config later. The key outranks any saved /login and any CLAUDE_CODE_OAUTH_TOKEN.

Why does Claude Code ask me to log in when ANTHROPIC_API_KEY is set?

Most often because the detection prompt was declined once and the answer was remembered for that key; interactive launches then show the login picker without offering the key. Open a session by any method, run /config, and turn on "Use custom API key". Non-interactive -p runs are unaffected and use the key regardless. Windows users on 2.1.243 and later have also reported the picker after updates, with a full reinstall as the working fix.

Where does Claude Code store the API key?

A key you export is never stored; it is read from the environment on each launch. A key created through the legacy Console sign-in in /login is stored with the other credentials: the macOS Keychain, or ~/.claude/.credentials.json with mode 0600 on Linux, on Windows, and on a Mac whose keychain rejected the write. The approve-or-decline answer for an environment key is kept in ~/.claude.json under customApiKeyResponses.

Sources and method: the four probes ran on this Mac mini on 6 September 2026 with Claude Code 2.1.259, a Max subscription logged in through the keychain, and a plausible but invalid key so that no request could be billed; retry timestamps come from --debug-file output, and the run outputs sit in my research notes. The 76-issue corpus is the union of three GitHub search API queries over anthropics/claude-code issues created on or after 7 August 2026, fetched the same day; the seventeen-issue classification is mine from titles and bodies, and a couple of the apiKeyHelper reports could sit in the billing pile instead. Quotes are verbatim. Documentation claims were checked against the authentication, environment variables, errors and settings reference pages and the help-center article as fetched the same day, version numbers against the repository changelog. I have not reproduced the interactive consent prompt, since this machine is headless, and I have not verified whether 2.1.260 changes the claude auth status JSON.