OAuth and Authentication: The Full Pipeline from Keychain to Token Refresh

Setting the Stage

When you first run the claude command, the system opens a browser to guide you through OAuth login. A few seconds later the terminal displays "Login successful" and you start coding. Hours later, the token expires — but you don't notice a thing, because the system silently refreshes it in the background. When you switch to remote Bridge mode, the JWT is automatically decoded, scheduled, and refreshed 5 minutes before expiration. Behind all of this is a full-pipeline architecture covering three authentication methods: API Key, OAuth 2.0, and JWT.

The core questions this architecture must answer are:

1. Diverse credential sources: How do you unify handling of environment variable API Keys, OAuth Tokens, tokens passed via file descriptors, and JWTs in Bridge mode?
2. Secure storage: Where are tokens stored? macOS uses Keychain, Linux uses plaintext files — how do you abstract away this difference?
3. Lifecycle management: What happens when a token expires? How do you avoid race conditions when multiple processes try to refresh simultaneously?
4. Cold start optimization: macOS Keychain reads take ~32ms each, and two sequential reads cost ~65ms — how do you optimize this?

This article starts with a panoramic view of authentication methods, then progressively dives into Keychain integration, the OAuth flow, token refresh scheduling, JWT management in Bridge mode, and finally paints the complete picture of Claude Code's authentication system.

Authentication Methods Overview

Claude Code supports multiple authentication methods, with the following priority from highest to lowest:

The authentication source determination logic lives in the getAuthTokenSource() function in src/utils/auth.ts:

This function has a key constraint: managed context isolation. When Claude Desktop or CCR (Claude Code Remote) launches the CLI via OAuth, the system checks isManagedOAuthContext() to prevent falling back to the user's local apiKeyHelper or environment variable API Key, preventing cross-context credential leakage.

Three Core Authentication Modes

OAuth 2.0 is the most central authentication method and the focus of this article. Anthropic's OAuth implementation follows the RFC 7636 (PKCE) extension and supports both automatic (browser callback) and manual (paste code) authorization code acquisition methods.

macOS Keychain Integration

Storage Architecture

Token storage abstracts away platform differences through the SecureStorage interface:

On macOS, a "Keychain first, plaintext file fallback" FallbackStorage strategy is used. This isn't a simple "if A fails try B" — createFallbackStorage also handles data migration across storage backends:

There's an elegant bug fix (#30337) in this code: when Keychain write fails and falls back to file storage, if the stale Keychain entry isn't deleted, read() would preferentially return the expired refresh token from Keychain, trapping the user in a /login loop.

Keychain Read/Write Implementation

macOS Keychain reads and writes are performed through the security CLI tool. Writes face a 4096-byte stdin buffer limit:

Note that credentials are hex-encoded before being passed in — this isn't encryption, but rather to avoid special characters in JSON causing shell-level parsing issues. Using security -i (stdin mode) is a security consideration: endpoint security software like CrowdStrike monitors process command-line arguments, and stdin passing means they only see security -i rather than the actual credentials.

Caching and Stale-While-Error

The synchronous path for Keychain reads takes about ~500ms each (security CLI spawn). When many MCP connectors authenticate simultaneously, the lack of caching would block the event loop for several seconds. The system therefore implements TTL-based caching with a stale-while-error strategy:

The 30-second TTL is a deliberate trade-off: OAuth tokens typically expire on the order of hours, and the only cross-process writer is another Claude Code instance's /login or token refresh. 30 seconds of staleness is perfectly acceptable in this scenario.

startKeychainPrefetch: Cold Start Optimization

On macOS, each startup requires reading two Keychain entries: OAuth Token (~32ms) and Legacy API Key (~33ms). Sequential reads mean ~65ms of blocking. startKeychainPrefetch() parallelizes these two reads and runs them concurrently with main.tsx's module loading:

This code is called at the top of main.tsx — even before most imports:

There's a subtle module design constraint here: keychainPrefetch.ts cannot import execa. Because Bun's ESM wrapper executes the entire module initialization chain when any symbol is accessed — the execa -> human-signals -> cross-spawn chain takes ~58ms of synchronous initialization, which would completely negate the prefetch benefits. So the prefetch module uses native child_process.execFile instead.

sequenceDiagram
  participant M as main.tsx
  participant P as keychainPrefetch
  participant K1 as security CLI (OAuth)
  participant K2 as security CLI (Legacy)
  participant I as Module Imports (~65ms)

  M->>P: startKeychainPrefetch()
  P->>K1: execFile('security', [...]) non-blocking
  P->>K2: execFile('security', [...]) non-blocking

  rect rgb(30, 30, 50)
    Note over M,I: Parallel execution
    M->>I: import module chain (~65ms)
    K1-->>P: OAuth Token (~32ms)
    K2-->>P: Legacy API Key (~33ms)
  end

  P->>P: primeKeychainCacheFromPrefetch()
  M->>P: ensureKeychainPrefetchCompleted() (near-zero cost)

primeKeychainCacheFromPrefetch only writes to the cache if it hasn't been touched — if a sync read() or update() has already executed, the prefetch result is discarded to preserve authoritativeness:

OAuth 2.0 Flow

PKCE Authorization Code Flow

Claude Code implements the full OAuth 2.0 Authorization Code Flow with PKCE (RFC 7636). The core implementation lives in the src/services/oauth/ directory, consisting of four files:

• crypto.ts — PKCE cryptographic primitives (code_verifier, code_challenge, state)
• client.ts — OAuth client (URL building, token exchange, refresh, profile fetching)
• auth-code-listener.ts — Local HTTP server that captures the authorization code callback
• index.ts — OAuthService class orchestrating the entire flow

The PKCE cryptography is quite concise:

The code_verifier is 32 bytes of random data, and the code_challenge is its SHA-256 hash. This ensures that even if the authorization code is intercepted, an attacker cannot complete the token exchange — because they don't have the original code_verifier.

Dual-Path Authorization: Automatic vs Manual

OAuthService.startOAuthFlow() supports two authorization code acquisition methods simultaneously:

The key difference between automatic and manual flows lies in the redirect_uri:

In the automatic flow, the OAuth provider redirects the user to http://localhost:{port}/callback?code=AUTH_CODE&state=STATE, and the local AuthCodeListener captures this request.

AuthCodeListener: Local Callback Server

AuthCodeListener is a temporary HTTP server whose lifecycle covers exactly one authorization flow:

An important design detail: the server does not immediately respond to the /callback request. It extracts the authorization code first, then stores the ServerResponse in pendingResponse. This allows the outer OAuthService to decide whether to redirect to a success or error page after completing the token exchange:

OAuth Scope System

Claude Code's OAuth scopes define a layered permission model:

The user:inference scope is the key indicator of whether a user is a Claude.ai subscriber (Pro/Max/Team/Enterprise). The shouldUseClaudeAIAuth() function checks this scope to determine the authentication path:

Token Storage and Refresh

Token Read Path

getClaudeAIOAuthTokens() is the single entry point for reading OAuth tokens in the system, wrapped with memoize to avoid redundant Keychain reads:

Note that tokens from environment variables and file descriptors have no refreshToken or expiresAt — they are "inference-only" short-lived tokens whose lifecycle is managed by an external system.

Token Expiration Detection

Expiration detection uses a 5-minute buffer to ensure refresh is triggered before the token actually expires:

Multi-Process Safe Token Refresh

Token refresh is the most complex part of the entire authentication system. Consider this scenario: a user is running 3 claude processes simultaneously, and their tokens all expire at the same time. If all three try to refresh, only one refresh token is valid (the server rotates them), and the other two will fail.

The solution is file locking + double-checking:

The essence of the triple-check pattern: the first check is the fast path (in-memory cache), the second check avoids unnecessary lock contention (async Keychain read), and the third check is the final confirmation after acquiring the lock. Random backoff (1000 + Math.random() * 1000) ensures multiple processes don't retry at the exact same moment.

Scope Expansion During Token Refresh

The scope handling during refresh has a noteworthy design:

For Claude.ai subscription users, the current scopes are not passed during refresh — instead the default CLAUDE_AI_OAUTH_SCOPES are used. This allows expanding scopes (e.g., adding user:file_upload) without requiring the user to re-login. The backend controls which scopes can be acquired via refresh through an ALLOWED_SCOPE_EXPANSIONS allowlist.

Optimized Profile Information Fetching

Every token refresh could potentially be accompanied by a /api/oauth/profile call to fetch subscription type and rate limits. But at full deployment this call runs roughly 7M times per day. To address this, skip logic was introduced:

The comments in this code document a subtle race condition: in the CLAUDE_CODE_OAUTH_REFRESH_TOKEN re-login path, installOAuthTokens executes performLogout() after returning, which clears secure storage. If null is returned as subscriptionType at this point, saveOAuthTokensIfNeeded would permanently lose the paying user's subscription type. This is avoided by passing through the existing value (existing?.subscriptionType).

JWT in Bridge Mode

JWT Decoding

In Bridge mode, the server-issued worker JWT is used for session authentication. jwtUtils.ts provides JWT decoding without signature verification — because verification is the server's responsibility, and the client only needs to read the exp claim to schedule refreshes:

createTokenRefreshScheduler

This is the core component in Bridge mode — a generic token refresh scheduler used by both the standalone bridge and the REPL bridge:

The scheduler's core is the "generation counter" pattern, used to solve races between async refreshes and rescheduling:

Every time schedule() or cancel() is called, the generation for the corresponding session is incremented. The async doRefresh() checks whether the generation still matches after completing — if it doesn't, the schedule has been superseded and the current refresh should be abandoned:

Usage in the REPL bridge:

Failure Retry and Bailout

The scheduler implements a capped retry mechanism, with a maximum of 3 consecutive failures:

/login and /logout Commands

/login Flow

The /login command renders a ConsoleOAuthFlow component that guides the user through OAuth authorization. After successful login, a series of reset and refresh operations are triggered:

The authVersion increment is a clever React pattern — changing a number triggers all hooks that listen for auth changes (such as MCP server lists) to re-execute.

/logout Flow

Logout must execute cleanup operations in a specific order:

The critical ordering: telemetry must be flushed before credentials are cleared, otherwise subsequent telemetry events would lose org context. The lazy import for flushTelemetry is another performance optimization — the OpenTelemetry package is about 1.1MB and isn't loaded at startup.

clearAuthRelatedCaches clears all authentication-related in-memory caches:

Security Considerations

Credential Passing Security

On macOS, credentials are passed via security -i (stdin) rather than command-line arguments, preventing endpoint detection and response (EDR) software from logging credentials. Fallback to argv only occurs when the payload exceeds the stdin buffer limit.

CSRF Protection

The state parameter in the OAuth flow is used not only for standard CSRF protection but also to correlate automatic and manual flows:

Keychain Lock Detection

In SSH sessions, the macOS Keychain may be in a locked state. The system detects this condition and displays a prompt to the user in the UI:

The result is cached because the Keychain lock state doesn't change during a CLI session, and execaSync takes about 27ms each time — in virtual scroll message remount scenarios, every message would re-trigger the detection.

Multi-Layer Token Storage Protection

Token storage forms a security gradient:

1. macOS Keychain (highest security): OS-level encrypted storage requiring user password to unlock
2. Plaintext file fallback (Linux/Keychain unavailable): Stored in ~/.claude/ directory, protected by file permissions
3. Environment variable tokens (externally managed): Not stored; the caller is responsible for security

Portable Patterns

Claude Code's authentication system supports several "portable" scenarios:

Host-Container Sharing

When the .claude directory is shared between host and container, the container typically cannot access the macOS Keychain. createFallbackStorage handles this migration — deleting the file storage copy on first successful Keychain write, and vice versa:

Environment Isolation

Different CLAUDE_CONFIG_DIR values map to different Keychain service names:

This ensures that credentials from different config directories (such as staging, local, custom OAuth URL) don't interfere with each other. OAUTH_FILE_SUFFIX is empty in production, -staging-oauth for staging, and -local-oauth for local.

SSH Remote Authentication

When claude ssh starts a remote session, API calls are proxied through a Unix Socket tunnel. The remote end doesn't directly hold credentials — instead, it points to a local auth-injecting proxy via the ANTHROPIC_UNIX_SOCKET environment variable. In this scenario, CLAUDE_CODE_OAUTH_TOKEN serves as a placeholder, only to inform the remote end that the current user is an OAuth subscriber so the correct beta header is sent.

Summary

Claude Code's authentication architecture demonstrates the balance a production-grade system strikes between security, performance, and usability:

• Unified multi-source handling: getAuthTokenSource() and getClaudeAIOAuthTokens() abstract 6+ credential sources into a unified token interface
• Platform-adaptive storage: The SecureStorage interface + FallbackStorage pattern implements a "Keychain first, file fallback" progressive enhancement
• Cold start optimization: startKeychainPrefetch() parallelizes ~65ms of sequential Keychain reads into the module loading phase, achieving near-zero cost
• Multi-process safety: Triple-check + file lock + random backoff ensures multiple Claude Code instances don't race to refresh the same token
• Bridge JWT scheduling: The generation counter pattern elegantly solves race conditions in async refresh
• Defense in depth: stdin credential passing, PKCE authorization code protection, Keychain lock detection, flushing telemetry before clearing credentials during logout

Every layer has carefully designed fallback and error recovery strategies. In particular, stale-while-error (continuing to use old data when Keychain reads fail) and scope expansion on refresh (automatically acquiring new scopes during refresh) reflect a mature system's thorough consideration of edge cases.