Use Authentication Precedence to Debug Login Issues
Claude Code checks credentials in a specific order. When something isn't working, knowing this order saves you from chasing the wrong problem.
# Precedence (highest to lowest):
# 1. Cloud provider env vars (CLAUDE_CODE_USE_BEDROCK, _VERTEX, _FOUNDRY)
# 2. ANTHROPIC_AUTH_TOKEN (Bearer header for proxies/gateways)
# 3. ANTHROPIC_API_KEY (X-Api-Key header for direct API)
# 4. apiKeyHelper script output (dynamic/rotating credentials)
# 5. OAuth credentials from /login (subscription users)
The most common gotcha: you have an active Claude Pro/Max subscription but also have ANTHROPIC_API_KEY set in your shell profile. The API key wins, and if it belongs to an expired org, authentication fails silently. Fix it with:
unset ANTHROPIC_API_KEY
Then run /status in Claude Code to confirm which auth method is active. If you need to switch from API key back to subscription permanently, check your .bashrc or .zshrc for any exports.
The apiKeyHelper setting runs a script that returns a key, useful for vault-based credential management. It refreshes every 5 minutes by default, or immediately on a 401 response.
When login breaks, check what's higher in the precedence list. Something is probably shadowing your real credentials.
Log in to leave a comment.
The autoUpdatesChannel setting pins Claude Code to a stable release track that skips versions with major regressions.
The language setting makes Claude respond in your preferred language by default, across every session and project.
The attribution setting lets you customize or completely remove Claude's Co-Authored-By trailer from git commits and pull requests.