Claude Authorization Code: How Authentication Works in Claude Code

Claude Code uses an OAuth 2.0 authorization code flow to authenticate users. When you run the CLI for the first time, it opens your browser, you approve access on Anthropic's consent screen, and the CLI receives a short-lived authorization code that it exchanges for access and refresh tokens — no API key required.

This guide covers how the OAuth flow works step by step, where tokens are stored on each operating system, how auto-refresh keeps you logged in, and alternative authentication methods for CI/CD and cloud environments.

How the OAuth Authorization Flow Works

Claude Code's authentication follows the standard OAuth 2.0 authorization code grant, the same pattern used by GitHub CLI, Heroku CLI, and other developer tools. The flow has four steps that happen in seconds.

First, you run claude in your terminal. The CLI starts a local HTTP server on a random port to listen for the callback. Second, your default browser opens to Anthropic's consent page at console.anthropic.com, where you log in (if needed) and approve the requested permissions. Third, after approval, Anthropic's server redirects to localhost with a one-time authorization code in the URL query string. Fourth, the CLI exchanges that code for an access token and a refresh token via a server-to-server request, then stores both tokens securely.

The authorization code itself is ephemeral — it expires within seconds and can only be used once. The access token that replaces it is what Claude Code uses for API calls. According to Anthropic's Claude Code documentation, this is the default and recommended authentication method for interactive use.

Token Storage by Operating System

Claude Code stores OAuth credentials differently depending on the operating system, using the most secure option available on each platform.

On macOS, you can verify stored credentials by opening Keychain Access and searching for "claude-code." On Linux, the credentials file is a JSON object containing the access token, refresh token, and expiration timestamp. As noted in the Claude Code security documentation, the CLI sets restrictive file permissions (600) on the credentials file to prevent other users on the same machine from reading it.

Auto-Refresh and Session Persistence

Claude Code automatically refreshes expired access tokens using the stored refresh token, so you do not need to log in again after your initial authentication.

When an access token expires (typically after a set period determined by Anthropic's server), the CLI detects the expiration before making the next API call and uses the refresh token to obtain a new access token. This happens silently — you will not see a browser window or any interruption.

You only need to re-authenticate in three situations: you explicitly run claude logout, Anthropic revokes the refresh token server-side (rare, typically only during security incidents), or the credential store is manually deleted or corrupted.

Alternative Authentication Methods

Claude Code supports several authentication methods beyond the default OAuth flow, designed for different environments and use cases.

API Key Authentication: Set the ANTHROPIC_API_KEY environment variable to bypass OAuth entirely. This is the recommended approach for CI/CD pipelines, Docker containers, and any headless environment where opening a browser is not possible. You can generate API keys from the Anthropic Console.

Amazon Bedrock: If your organization uses Claude through AWS Bedrock, Claude Code can authenticate using your AWS credentials (environment variables, IAM roles, or AWS profiles). Set CLAUDE_CODE_USE_BEDROCK=1 along with your AWS credential configuration.

Google Vertex AI: Similarly, if you access Claude through Google Cloud's Vertex AI, Claude Code supports authentication via Google Cloud credentials. Set CLAUDE_CODE_USE_VERTEX=1 and configure your Google Cloud project and region.

Troubleshooting Common Auth Issues

Authentication failures in Claude Code typically fall into a few categories, each with a straightforward fix.

Browser does not open: If the CLI cannot open a browser (common in SSH sessions or remote servers), use the API key method instead. Set ANTHROPIC_API_KEY in your shell profile or pass it inline.

Callback fails (port conflict): The CLI starts a local HTTP server to receive the OAuth callback. If another process is using the assigned port, the callback may fail. Close the conflicting process or restart the CLI to retry with a different port.

HTTP 500 during login: Server-side errors during the OAuth exchange are usually temporary. Wait a few minutes and try again. If the issue persists, check Anthropic's status page for outages. For a detailed walkthrough, see our guide to fixing Claude Code OAuth 500 errors.

Token expired and not refreshing: If you encounter repeated authentication prompts, the refresh token may have been invalidated. Run claude logout followed by claude login to start a fresh OAuth flow. For persistent login failures, see our Claude Code login troubleshooting guide.

Limitations and Tradeoffs

The OAuth flow requires a browser, which makes it unusable in purely headless environments without the API key fallback. On Linux, the credentials file approach is less secure than macOS Keychain — any process running as your user can read the file. If you share a machine with other users, ensure the file permissions on ~/.claude/.credentials.json are set to 600.

API key authentication, while convenient for automation, does not support account-level features like usage dashboards tied to your Anthropic console login. It also requires manual key rotation — there is no auto-refresh mechanism for API keys. When not to use OAuth: if you are running Claude Code in a container, ephemeral CI runner, or any non-interactive context, skip OAuth and use ANTHROPIC_API_KEY directly.

Related Guides

• Claude Code: Complete Setup and Usage Guide
• How to Fix Claude Code OAuth Error 500
• Claude Code Login Not Working: Troubleshooting Guide

Frequently Asked Questions

What is a Claude authorization code?

A Claude authorization code is a temporary code issued during the OAuth 2.0 login flow when you authenticate Claude Code. After you approve access in your browser, Anthropic's server sends this code back to the CLI, which exchanges it for an access token and a refresh token. You never need to copy or paste the code manually — the CLI handles the entire exchange automatically.

Where does Claude Code store tokens?

On macOS, Claude Code stores OAuth tokens in the system Keychain under the service name 'claude-code'. On Linux, tokens are saved in a JSON credentials file at ~/.claude/.credentials.json. On Windows (via WSL), the Linux storage path applies. You can verify stored credentials on macOS by opening Keychain Access and searching for 'claude-code'.

Do I need to re-authenticate every time I use Claude Code?

No. Claude Code stores a refresh token that automatically obtains new access tokens when the current one expires. You only need to re-authenticate if you explicitly log out with 'claude logout', if the refresh token is revoked server-side, or if the credential store is cleared. Under normal use, a single login persists across sessions.

Can I use an API key instead of OAuth?

Yes. You can set the ANTHROPIC_API_KEY environment variable to bypass the OAuth flow entirely. This is common in CI/CD pipelines, Docker containers, and headless servers where a browser-based login is not practical. Claude Code also supports authentication through Amazon Bedrock and Google Vertex AI using their respective credential systems.