skip to content

When several credentials are present, how does Claude Code choose one, and why can a stray ANTHROPIC_API_KEY move a subscriber onto API billing?

level: seniorimportance: must knowfreq 22%

answer

  1. a fixed ranking, not the newest login
  2. provider switches sit at the top
  3. environment key outranks the /login subscription
  4. approved once interactively, always under -p
  5. /status shows the credential in force

basics

~10 s

Claude Code takes the highest credential in a fixed order: cloud provider switch, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN, profiles, then the /login subscription. An approved ANTHROPIC_API_KEY therefore beats a subscription and bills its Console organization.

solid answer

~40 s

Claude Code ranks credentials: a cloud provider selected with `CLAUDE_CODE_USE_BEDROCK`, `_VERTEX` or `_FOUNDRY`; then `ANTHROPIC_AUTH_TOKEN` (sent as a Bearer header, for LLM gateways); `ANTHROPIC_API_KEY` (sent as `X-Api-Key`); `apiKeyHelper` output; `CLAUDE_CODE_OAUTH_TOKEN`; Anthropic profile and federation credentials; and last the `/login` subscription, the default for Pro, Max, Team and Enterprise users. So a subscriber with an old key in their shell profile who approved it at the one-time prompt is on that key's Console organization, billed per token - and if that organization is disabled, requests fail. Under `claude -p` the key is used whenever present, with no prompt. Check `/status` (an `API key` row instead of a `Login method` row), then `unset ANTHROPIC_API_KEY` and remove it from the profile.

code

bash · 4 lines
bash
# Inside Claude Code, run /status first: an 'API key' row means the key is in force.
# Then drop the key for this shell and from the profile that sets it:
unset ANTHROPIC_API_KEY
grep -n 'ANTHROPIC_API_KEY' ~/.zshrc ~/.bashrc ~/.profile 2>/dev/null

go deeper

for a junior

Remember that /status shows which credential is active and that an exported ANTHROPIC_API_KEY can take over from your subscription.

for a middle

Walk through the ranking from provider switches down to /login, and the difference between the one-time interactive approval and -p always using the key.

for a senior

Diagnose a billing or disabled-organization surprise from /status, trace the key to a shell profile, and know where the order does not apply, such as cloud sessions.

for a principal

Decide how a team distributes credentials so the intended one is always highest, and how leftover keys and gateway tokens are audited out.

## The ranking A developer's machine often carries more than one credential: a claude.ai login from `/login`, a Console key exported years ago, a token for CI. Claude Code does not pick the newest one; it walks a **fixed order** and uses the first source that is present. | Rank | Source | Notes | |---|---|---| | 1 | **Cloud provider** - `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX` or `CLAUDE_CODE_USE_FOUNDRY` | requests go to that provider with its own credentials | | 2 | `ANTHROPIC_AUTH_TOKEN` | sent as `Authorization: Bearer`; meant for an LLM gateway or proxy | | 3 | `ANTHROPIC_API_KEY` | sent as `X-Api-Key`; a Claude Console key | | 4 | `apiKeyHelper` | a settings key naming a script that prints a key, for rotating credentials | | 5 | `CLAUDE_CODE_OAUTH_TOKEN` | the long-lived token from `claude setup-token` | | 6 | Anthropic profile and federation credentials | e.g. a profile named in `ANTHROPIC_PROFILE` | | 7 | **`/login` subscription** | the default for Pro, Max, Team and Enterprise | One thing sits outside the list: a signed-in **Claude apps gateway** session is treated as a provider selection and outranks even the cloud-provider switches. Organisations can also force a login method through managed settings; that is the managed-policy material. ## Why a stray key changes the bill The subscription is at the **bottom** of the list. Anything above it wins, and `ANTHROPIC_API_KEY` is above it. The approval step softens this only in interactive mode: 1. **Interactive session**: the first time Claude Code sees the key it asks you to approve or decline it, and remembers the answer. Approve once - perhaps months ago, on a different project - and every later session uses the key. The **Use custom API key** toggle in `/config` changes the choice, and it appears only while the variable is set. 2. **Non-interactive (`claude -p`)**: the key is **always used when present**. There is no prompt and no remembered decline. The consequences: - Requests bill **per token to the key's Console organization**, not to the plan. - If that organization is disabled or the key is expired - say a key from a previous employer - requests fail with an error such as `This organization has been disabled`, although the subscription itself is fine. - Features that need a claude.ai login are lost: Remote Control, for example, does not accept API keys. ## Diagnosing and fixing it - Run **`/status`**. A subscription shows a `Login method` row naming the plan; a key shows an `API key` row. When both are configured, `/status` marks the one that is not in use. - Run `unset ANTHROPIC_API_KEY` to fall back to the subscription for the current shell. - Remove the `export ANTHROPIC_API_KEY=...` line from `~/.zshrc`, `~/.bashrc` or `~/.profile` (on Windows, the PowerShell profile and user environment variables) so it does not return. The same reasoning applies one rung higher: an `ANTHROPIC_AUTH_TOKEN` left over from a gateway experiment beats both the key and the subscription. ## The helper and the token in more detail - `apiKeyHelper` runs its command through the system shell and sends the output as both the `X-Api-Key` and `Authorization: Bearer` headers. Claude Code caches the value for five minutes by default (`CLAUDE_CODE_API_KEY_HELPER_TTL_MS` changes that) and reruns the helper when a request fails with `401` or `403`. - A helper defined in **project or local settings** does not run in an interactive session until you accept the workspace trust prompt. - `CLAUDE_CODE_OAUTH_TOKEN` interacts with `/login`: running `/login` while it is set switches only the current session; new sessions read the variable again until you remove it. ## Where the order does not apply - **Cloud sessions** (Claude Code on the web) always use your subscription; an `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` set in the cloud environment does not override it. - **Claude Desktop** does not read these variables or call `apiKeyHelper`; it uses OAuth, apart from a desktop session running a third-party inference configuration. The CLI and the surfaces that wrap it - the VS Code extension, the Agent SDK, GitHub Actions - do read them. - A **profile** written by `ant auth login` ranks at position 6 only when you name it in `ANTHROPIC_PROFILE`; otherwise a working `/login` credential beats it. ## The rule to remember The credential that bills you is not the one you logged in with most recently; it is the highest one present. `/status` is the only reliable way to see it.

  • You declined the ANTHROPIC_API_KEY prompt interactively. Why does a `claude -p` script on the same machine still use the key?
    The approve-or-decline choice applies to interactive sessions. In non-interactive mode, `-p`, Claude Code always uses `ANTHROPIC_API_KEY` when it is present, so a script inherits the key from the shell regardless of what you chose at the prompt. Unset it in the script's environment to use the subscription.
  • When would you deliberately set ANTHROPIC_AUTH_TOKEN rather than ANTHROPIC_API_KEY?
    When requests go through an LLM gateway or proxy that authenticates with bearer tokens rather than Anthropic API keys. `ANTHROPIC_AUTH_TOKEN` is sent as the `Authorization: Bearer` header and ranks above `ANTHROPIC_API_KEY`, so it wins if both are set.
  • Does setting ANTHROPIC_API_KEY in a cloud session's environment switch that session to API billing?
    No. Cloud sessions always use your subscription credentials; an `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` set in the cloud environment does not override them. The precedence list governs the CLI and the surfaces that wrap it.

A key ring the door always tries in the same order: the first key that fits opens it, even if you meant to use the one at the bottom.

  • Claude Code uses whichever account you logged in with most recently
  • The /login subscription outranks an environment API key
  • Declining the key prompt also stops claude -p from using it
  • A disabled-organization error means the subscription itself has lapsed
  • An API key set in a cloud session's environment overrides the subscription