Run claude in a project and it opens a browser to sign in to your Claude account, or run claude auth login directly. Claude Code also accepts ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, an apiKeyHelper script, and a long-lived CLAUDE_CODE_OAUTH_TOKEN from claude setup-token. When several are present it uses the first match in a fixed precedence order, and environment credentials outrank your subscription login. Run /status to see which one is active. Claude Code requires a Pro, Max, Team, Enterprise or Console account; the free Claude plan does not include it, as of August 2026.
- Sign in with
claude auth login, or just runclaudeand follow the browser. ANTHROPIC_API_KEYin the environment outranks your subscription login./statusis the only reliable answer to "how am I being billed right now".claude setup-tokenmints a one-year token for machines with no browser.- That token can make model requests only: no Remote Control, no claude.ai connectors.
- Credentials live in the macOS Keychain, or a
0600file on Linux and Windows.
The five ways in
How each one bills and where each one belongs.
| Method | Bills as | Set up with | Right for |
|---|---|---|---|
| Browser login | Your subscription | claude auth login or /login | Normal interactive work |
| API key | Per token | ANTHROPIC_API_KEY | CI, automation, spiky usage |
| Bearer token | Whatever the gateway bills | ANTHROPIC_AUTH_TOKEN | An LLM gateway or proxy in front |
| Credential helper | Depends on what it returns | apiKeyHelper in settings | Short-lived keys from a vault |
| Long-lived token | Your subscription | claude setup-token | Headless machines you own |
A cloud provider is the sixth path and sits outside this list: with Amazon Bedrock, Google Cloud Agent Platform or Microsoft Foundry configured, the provider credential is used and no browser login happens at all.
The precedence order, exactly
When more than one credential is present, Claude Code picks the first match walking down this list. It does not warn you that it skipped the others.
- Cloud provider credentials, when
CLAUDE_CODE_USE_BEDROCK,CLAUDE_CODE_USE_VERTEXorCLAUDE_CODE_USE_FOUNDRYis set. ANTHROPIC_AUTH_TOKEN, sent as anAuthorization: Bearerheader. For gateways that authenticate with bearer tokens.ANTHROPIC_API_KEY, sent asX-Api-Key. Interactively you are asked once to approve or decline it and the answer is remembered. Under-pit is always used when present.apiKeyHelperscript output, for rotating credentials.CLAUDE_CODE_OAUTH_TOKEN, the long-lived token fromclaude setup-token.- Subscription OAuth credentials from
/login. The default for Pro, Max, Team and Enterprise.
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_USE_|CLAUDE_CODE_OAUTH)'
grep -rn "ANTHROPIC_API_KEY" ~/.zshrc ~/.bashrc ~/.profile 2>/dev/null
claude auth status --textSigning in normally
Start it in a project
cd ~/code/your-project
claude
# or sign in without starting a session
claude auth loginOn first launch a browser window opens. If it does not, press <kbd>c</kbd> to copy the login URL to the clipboard and open it yourself. claude auth login also takes --email to prefill, --sso to force SSO, and --console to sign in with an Anthropic Console account for API billing.
Finish in the browser, or paste the code
Sign in to the account holding your subscription and approve. The tab hands the credential back over a local callback and the terminal prints Login successful.
If the browser shows a login code instead of returning you to the terminal, paste it at the Paste code here if prompted prompt. That happens whenever the browser cannot reach the local callback server, which is normal in WSL2, over SSH, and inside containers. It is not a failure.
Confirm what you got
/statusThis is the habit worth forming. The Login method row names the account, and a separate API key row appears when a key is in use. Thirty seconds here is cheaper than finding out from an invoice.
/logout # inside a session, or: claude auth logout
claude auth login # sign in as someone else
# a stale key overriding your subscription
unset ANTHROPIC_API_KEY
claude
# scriptable: exit code 0 if logged in, 1 if not
claude auth statusMachines with no browser
A build agent or a bare server has no browser to complete the flow with. Generate the credential where a browser exists and carry it over.
# on your laptop
claude setup-token
# on the server
export CLAUDE_CODE_OAUTH_TOKEN="<token>"
claudeclaude setup-token opens the same browser authorization as /login, prints a one-year token, and does not save it anywhere. Copy it at that moment or mint another. It requires a Pro, Max, Team or Enterprise plan.
What the long-lived token can and cannot do, as of August 2026.
| Capability | Long-lived token | Full browser login |
|---|---|---|
| Model requests | Yes | Yes |
| Locally configured MCP servers | Yes | Yes |
| Remote Control sessions | No | Yes |
| claude.ai connectors | No | Yes |
Read by --bare mode | No | Not applicable |
Where credentials live
| Platform | Location |
|---|---|
| macOS | The encrypted macOS Keychain |
| Linux | ~/.claude/.credentials.json, file mode 0600 |
| Windows | %USERPROFILE%\.claude\.credentials.json, restricted by the profile directory permissions |
Any, with CLAUDE_CONFIG_DIR set | The same file under that directory instead (Linux and Windows) |
Claude Code owns that file through /login and /logout. Hand-editing it is not a supported way to move a credential between machines, and it is not where you change the API endpoint: that is ANTHROPIC_BASE_URL.
Rotating credentials with apiKeyHelper
For short-lived keys out of a vault, point the apiKeyHelper setting at a script that prints one. Claude Code calls it after five minutes or on an HTTP 401, and CLAUDE_CODE_API_KEY_HELPER_TTL_MS overrides that interval. If the script takes longer than ten seconds it shows a warning with the elapsed time, which is a hint that the script is doing too much work per call.
When login fails
| Symptom | Cause | Fix |
|---|---|---|
| Metered despite a subscription | ANTHROPIC_API_KEY set and approved | unset it, then check every shell profile |
| Browser never returns to the terminal | Callback unreachable: WSL2, SSH, container | Paste the login code at the prompt |
| Login loop, never completes | Proxy or firewall between you and the callback | Copy the URL manually; check HTTPS_PROXY |
Login expired · Please run /login | The stored login aged out | Run /login; the warning starts three days ahead |
| Prompted to log in every launch | Credential store not persisting | claude doctor; check Keychain access |
Invalid API key | Malformed, revoked, or trailing whitespace | Re-copy the key, then regenerate it |
| Signed in, requests still fail | Possibly a service incident | Check the Anthropic status page |
| Exits at startup complaining about the organization | forceLoginOrgUUID in managed settings | Sign in to the organization your admin pinned |
Two of those deserve a sentence more. The expiry warning reads Your login expires in 3 days · run /login to renew and never blocks a request, so it is easy to scroll past; a background or Remote Control session that outlives the login simply stops making progress. And organizations can pin login with forceLoginMethod and forceLoginOrgUUID in managed settings, which also blocks sessions authenticated by ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or apiKeyHelper, because organization membership cannot be verified for an environment credential.
Questions people ask
Run claude in a project directory and follow the browser prompt, or run claude auth login directly. Inside a session, /login signs you in again and /logout signs you out.
Because ANTHROPIC_API_KEY outranks a subscription login in the credential precedence order once you have approved it. Unset the variable, check your shell profiles for an export you forgot, and confirm with /status.
Run /status inside a session and read the Login method row. An API key row appears when a key is in use. From a script, claude auth status prints JSON and exits 0 when logged in and 1 when not.
Run claude setup-token on a machine that has a browser and set CLAUDE_CODE_OAUTH_TOKEN on the server. The token lasts a year, is printed once and never saved, and requires a Pro, Max, Team or Enterprise plan.
No. Claude Code requires a Pro, Max, Team, Enterprise or Console account, or access through Amazon Bedrock, Google Cloud Agent Platform or Microsoft Foundry, as of August 2026.
Because the browser cannot reach the local callback server, which is normal in WSL2, over SSH and inside containers. Paste the code at the Paste code here if prompted line. The login completes exactly the same way.
Run /logout, then claude auth login as the other account. The credential store holds one login per operating-system user, so switching replaces the previous one rather than adding to it.
In the encrypted macOS Keychain on macOS, and in a 0600 .credentials.json file under ~/.claude on Linux or %USERPROFILE%\.claude on Windows. Setting CLAUDE_CONFIG_DIR moves that file.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.