claude-code-oauth

Use your Claude Max/Pro subscription via OAuth. This package implements the same authentication flow used by Claude Code, allowing you to make API calls without a separate API key.

Requirements

• Claude Max or Claude Pro subscription
• Python 3.10+

Installation

pip install claude-code-oauth

Quick Start

1. Login (one-time)

claude-auth login

This opens your browser to authenticate with your Claude account. After authorization, paste the code shown on the callback page.

2. Use in Code

Async usage:

from claude_code_oauth import ClaudeClient

async with ClaudeClient() as client:
    response = await client.message("What is 2+2?")
    print(response.content)

Sync usage:

from claude_code_oauth import ClaudeClient

with ClaudeClient() as client:
    response = client.message_sync("What is 2+2?")
    print(response.content)

Multi-turn Conversations

from claude_code_oauth import ClaudeClient

messages = [
    {"role": "user", "content": "My name is Alice."},
    {"role": "assistant", "content": "Nice to meet you, Alice!"},
    {"role": "user", "content": "What's my name?"},
]

with ClaudeClient() as client:
    response = client.message_sync(messages)
    print(response.content)  # "Your name is Alice."

Custom System Prompt

with ClaudeClient() as client:
    response = client.message_sync(
        "Explain quantum computing",
        system="You are a physics professor. Use simple analogies.",
        max_tokens=1000,
        temperature=0.5,
    )

CLI Commands

# Authenticate with Claude
claude-auth login

# Check authentication status
claude-auth status

# Clear stored credentials
claude-auth logout

# Show package info
claude-auth info

CLI Options

# Use Claude Pro instead of Claude Max
claude-auth login --pro

# Don't open browser automatically
claude-auth login --no-browser

# Use custom token storage path
claude-auth login --path ~/.my-tokens/claude.json

How It Works

Claude Max/Pro subscriptions can authenticate via OAuth using the same flow as Claude Code. This package:

1. Generates PKCE challenge for secure auth
2. Opens browser for user authorization
3. Exchanges code for access/refresh tokens
4. Stores tokens securely (~/.claude-code-oauth/tokens.json with 0600 permissions)
5. Auto-refreshes expired tokens
6. Injects required system prompt prefix for OAuth validation

API Reference

ClaudeClient

from claude_code_oauth import ClaudeClient

client = ClaudeClient(
    token_store=None,  # Use default token store
    model="claude-sonnet-4-20250514",  # Default model
    timeout=120.0,  # Request timeout in seconds
)

Methods

• message(content, *, model=None, system=None, max_tokens=4096, temperature=0.7) - Async message
• message_sync(...) - Sync version
• close() / aclose() - Close HTTP clients

TokenStore

from claude_code_oauth import TokenStore, get_auth_status

# Custom token path
store = TokenStore("~/.my-app/tokens.json")

# Check status
status = get_auth_status()  # "authenticated" | "expired" | "not_authenticated"

Programmatic Login

from claude_code_oauth import login, login_sync

# Async
await login(use_claude_max=True, token_path=None)

# Sync
login_sync(use_claude_max=True, token_path=None)

OAuth Details

This package uses the same OAuth flow as Claude Code:

• Client ID: Public Claude Code client
• Scopes: org:create_api_key user:profile user:inference
• Token endpoint: https://console.anthropic.com/v1/oauth/token
• Auth endpoints:
  • Claude Max: https://claude.ai/oauth/authorize
  • Claude Pro: https://console.anthropic.com/oauth/authorize

System Prompt Prefix

OAuth tokens require this exact prefix as the first system block:

You are Claude Code, Anthropic's official CLI for Claude.

This is automatically injected by ClaudeClient. Your custom system prompts are appended after this prefix.

Development

# Clone and install
git clone https://github.com/minzique/claude-code-oauth
cd claude-code-oauth
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check . && ruff format .

License

MIT