Library
Claude Code Documentation (June 2026) · 4 of 15
Claude Code Documentation (June 2026)
ai MEDIUM

Authentication

Claude Code Documentation (June 2026) Anthropic
authentication credentials precedence ci-token

Key Principle

Claude Code logs in via browser on first launch, stores credentials per-platform, and — load-bearing — picks among multiple present credentials in a strict precedence order where the first match wins (Section: Authentication). The precedence is the part that bites people: an env var you forgot about silently overrides your subscription.

Why This Matters

A stale ANTHROPIC_API_KEY outranks subscription OAuth, so auth silently fails if the key belongs to a disabled/expired org. Knowing the exact order is the difference between a five-second fix and an hour of confusion (p. 12).

Good Examples

Account types (which login to use) (Section: Logging in):

  • Claude Pro / Max — log in with your Claude.ai account.
  • Claude for Teams / Enterprise — log in with the Claude.ai account your admin invited. Enterprise adds SSO, domain capture, role-based permissions, compliance API, and managed (org-wide) settings.
  • Claude Console — log in with Console credentials (admin invites first). Roles: Claude Code (only creates Claude Code API keys) or Developer (any API key).
  • Cloud providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry) — set required env vars before running claude; no browser login.

Code-paste fallback (local callback server unreachable — WSL2, SSH, containers): press c to copy the login URL, paste into a browser; paste any login code back at Paste code here if prompted.

Credential storage — Claude Code manages .credentials.json via /login and /logout (Section: Credential storage):

  • macOS — encrypted macOS Keychain.
  • Linux — ~/.claude/.credentials.json, mode 0600.
  • Windows — %USERPROFILE%\.claude\.credentials.json (inherits user-profile ACLs).
  • If CLAUDE_CONFIG_DIR is set (Linux/Windows), .credentials.json lives there instead.
  • Route requests through a custom endpoint with ANTHROPIC_BASE_URL.

Authentication precedence (exact order, first match wins) (Section: Authentication precedence):

  1. Cloud provider credentials — when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, or CLAUDE_CODE_USE_FOUNDRY is set.
  2. ANTHROPIC_AUTH_TOKEN — sent as Authorization: Bearer. For an LLM gateway/proxy authenticating with bearer tokens.
  3. ANTHROPIC_API_KEY — sent as X-Api-Key. Direct Anthropic API with a Console key. Interactive: prompted once (remembered; toggle in /config). Non-interactive (-p): always used when present.
  4. apiKeyHelper output — dynamic/rotating credentials (e.g. short-lived vault tokens).
  5. CLAUDE_CODE_OAUTH_TOKEN — long-lived OAuth token from claude setup-token. For CI/scripts without browser login.
  6. Subscription OAuth from /login — default for Pro, Max, Team, Enterprise.

Custom credential helper (apiKeyHelper): a settings key naming a shell script that returns an API key — for dynamic/rotating credentials. Called after 5 min or on HTTP 401; override the interval with CLAUDE_CODE_API_KEY_HELPER_TTL_MS. If it takes >10 s, Claude Code warns in the prompt bar (Section: Custom credential scripts).

Long-lived CI token (Section: Long-lived token for CI):

claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN=your-token

Walks through OAuth and prints a one-year token (does not save it anywhere). Requires a Pro, Max, Team, or Enterprise plan.

Counterpoints

  • The classic failure: active subscription plus a stale ANTHROPIC_API_KEY → the key wins (rule 3 beats rule 6) and auth fails if it belongs to a disabled/expired org. Fix: unset ANTHROPIC_API_KEY to fall back to the subscription; confirm with /status (p. 12).
  • Scope gotcha: apiKeyHelper, ANTHROPIC_API_KEY, and ANTHROPIC_AUTH_TOKEN apply to terminal CLI sessions only. Claude Desktop and cloud sessions use OAuth exclusively and ignore the helper and API-key env vars (p. 12).
  • Claude Code on the Web always uses subscription credentials — ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN in the sandbox do not override them (p. 12).
  • The claude setup-token token is inference-scoped only — cannot establish Remote Control sessions. Bare mode (--bare) does not read it — authenticate --bare scripts with ANTHROPIC_API_KEY or an apiKeyHelper instead (p. 12).

Key Commands & Config

claude · /login · /logout · /config · /status
claude setup-token            # prints a one-year CLAUDE_CODE_OAUTH_TOKEN
Env: ANTHROPIC_AUTH_TOKEN · ANTHROPIC_API_KEY · CLAUDE_CODE_OAUTH_TOKEN
     ANTHROPIC_BASE_URL · CLAUDE_CONFIG_DIR · CLAUDE_CODE_API_KEY_HELPER_TTL_MS
     CLAUDE_CODE_USE_BEDROCK · CLAUDE_CODE_USE_VERTEX · CLAUDE_CODE_USE_FOUNDRY
Settings: apiKeyHelper
Headers: Authorization: Bearer · X-Api-Key
Paths: ~/.claude/.credentials.json (0600) · %USERPROFILE%\.claude\.credentials.json
Precedence: cloud-provider > ANTHROPIC_AUTH_TOKEN > ANTHROPIC_API_KEY >
            apiKeyHelper > CLAUDE_CODE_OAUTH_TOKEN > subscription OAuth

Rules of Thumb

  • When auth misbehaves on a subscription, first unset ANTHROPIC_API_KEY and check /status.
  • Use apiKeyHelper for rotating credentials; use claude setup-token for CI without a browser.
  • Remember env-var auth is CLI-only — Desktop/cloud always use OAuth.

Related References