anthropic-auth

A Rust library for Anthropic/Claude OAuth 2.0 authentication with PKCE support.

Provides both synchronous (blocking) and asynchronous (runtime-agnostic) APIs for authenticating with Anthropic's OAuth 2.0 endpoints.

Features

• ✅ Sync & Async APIs - Choose blocking or async based on your needs
• ✅ Runtime Agnostic - Async API works with tokio, async-std, smol, etc.
• ✅ PKCE Support - Secure SHA-256 PKCE authentication flow
• ✅ Two OAuth Modes - Max (subscription) or Console (API key creation)
• ✅ Fully Configurable - Custom client IDs, redirect URIs, ports
• ✅ Browser Integration - Auto-open browser for authorization (default enabled)
• ✅ Callback Server - Optional local server for automatic callback handling
• ✅ API Key Creation - Create API keys via Console OAuth
• ✅ No Token Storage - You control how/where to persist tokens

Installation

[dependencies]
anthropic-auth = "0.1"

Quick Start (Sync API)

Claude Pro/Max Subscription

use anthropic_auth::{OAuthClient, OAuthConfig, OAuthMode};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = OAuthClient::new(OAuthConfig::default())?;
    let flow = client.start_flow(OAuthMode::Max)?;
    
    println!("Visit: {}", flow.authorization_url);
    // User visits URL and gets response in format: "code#state"
    let response = "l0pnTslNFOmTgp28REMrbt4wyLNR25SJePqjk4CAHjoen0TJ#FgE6g_6khGKFFhXAw3tULPM00CPaqgE3Cq6id79Surg";
    
    // Library automatically parses and validates the state
    let tokens = client.exchange_code(response, &flow.state, &flow.verifier)?;
    println!("Got access token!");
    
    // Later, refresh if needed
    if tokens.is_expired() {
        let new_tokens = client.refresh_token(&tokens.refresh_token)?;
    }
    
    Ok(())
}

API Key Creation

use anthropic_auth::{OAuthClient, OAuthConfig, OAuthMode};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = OAuthClient::new(OAuthConfig::default())?;
    let flow = client.start_flow(OAuthMode::Console)?;
    
    println!("Visit: {}", flow.authorization_url);
    // User authorizes and you receive: "code#state"
    let response = "code123#state456";
    
    let tokens = client.exchange_code(response, &flow.state, &flow.verifier)?;
    
    // Create API key
    let api_key = client.create_api_key(&tokens.access_token)?;
    println!("API Key: {}", api_key);
    
    Ok(())
}

Quick Start (Async API)

use anthropic_auth::{AsyncOAuthClient, OAuthConfig, OAuthMode};

#[tokio::main]  // or async-std, smol, etc.
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AsyncOAuthClient::new(OAuthConfig::default())?;
    let flow = client.start_flow(OAuthMode::Max)?;
    
    println!("Visit: {}", flow.authorization_url);
    // User authorizes and you receive: "code#state"
    let response = "code123#state456";
    
    let tokens = client.exchange_code(response, &flow.state, &flow.verifier).await?;
    println!("Got access token!");
    
    Ok(())
}

OAuth Modes

Max Mode (Claude Pro/Max Subscription)

Use this mode if you have a Claude Pro or Claude Max subscription:

let flow = client.start_flow(OAuthMode::Max)?;

• Authorization endpoint: https://claude.ai/oauth/authorize
• Provides access tokens for Claude API with your subscription
• Best for personal use with existing subscription

Console Mode (API Key Creation)

Use this mode to create API keys programmatically:

let flow = client.start_flow(OAuthMode::Console)?;
// ... get tokens ...
let api_key = client.create_api_key(&tokens.access_token)?;

• Authorization endpoint: https://console.anthropic.com/oauth/authorize
• Creates API keys that can be used independently
• Useful for programmatic access

Feature Flags

Enable async API:

[dependencies]
anthropic-auth = { version = "0.1", features = ["async"] }

Enable callback server (full automation):

[dependencies]
anthropic-auth = { version = "0.1", features = ["callback-server"] }
tokio = { version = "1", features = ["full"] }

Custom Configuration

use anthropic_auth::{OAuthClient, OAuthConfig};

let config = OAuthConfig::builder()
    .client_id("my-client-id")
    .redirect_port(8080)  // Custom port
    .build();

let client = OAuthClient::new(config)?;

Examples

See the examples/ directory for complete working examples:

• max_subscription_sync.rs - Claude Pro/Max OAuth (sync)
• console_api_key_sync.rs - API key creation (sync)

Run examples with:

cargo run --example max_subscription_sync
cargo run --example console_api_key_sync

Authorization Response Format

Anthropic returns authorization responses in the format code#state. The library parses this automatically and validates the state for CSRF protection:

// User receives: "abc123#xyz789"
// Library parses it and validates state matches flow.state
let tokens = client.exchange_code("abc123#xyz789", &flow.state, &flow.verifier)?;

// Or if you've already separated them:
let tokens = client.exchange_code("abc123", &flow.state, &flow.verifier)?;

Important: The state parameter is used for CSRF protection. The library validates that the state returned by Anthropic matches the state originally sent in the authorization URL.

API Overview

Sync API (blocking)

let client = OAuthClient::new(config)?;

// Start flow (generates PKCE and state, returns auth URL)
let flow = client.start_flow(OAuthMode::Max)?;

// Exchange code for tokens (parses "code#state" format automatically)
let tokens = client.exchange_code("code#state", &flow.state, &flow.verifier)?;

// Refresh expired tokens
let new_tokens = client.refresh_token(&tokens.refresh_token)?;

// Create API key (Console mode only)
let api_key = client.create_api_key(&tokens.access_token)?;

Async API (runtime-agnostic)

let client = AsyncOAuthClient::new(config)?;

// Start flow (still sync - no I/O)
let flow = client.start_flow(OAuthMode::Max)?;

// Async methods
let tokens = client.exchange_code("code#state", &flow.state, &flow.verifier).await?;
let new_tokens = client.refresh_token(&tokens.refresh_token).await?;
let api_key = client.create_api_key(&tokens.access_token).await?;

Browser Integration

use anthropic_auth::open_browser;

let flow = client.start_flow(OAuthMode::Max)?;
open_browser(&flow.authorization_url)?;  // Opens user's default browser

Token Storage

This library intentionally does not handle token persistence. You should store tokens securely based on your application's needs.

Recommended approaches:

• System Keychain: Use keyring crate
• Encrypted Files: Encrypt tokens before writing to disk
• Environment Variables: For development/testing only