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?
answer
- a fixed ranking, not the newest login
- provider switches sit at the top
- environment key outranks the /login subscription
- approved once interactively, always under -p
- /status shows the credential in force
basics
~10 sClaude 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 sClaude 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# 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/nullgo deeper
Remember that /status shows which credential is active and that an exported ANTHROPIC_API_KEY can take over from your subscription.
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.
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.
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