ClaudeCodeSDK.AuthManager (claude_code_sdk v0.2.2)

View Source

Manages authentication tokens for Claude Code SDK.

Provides automatic token acquisition, validation, refresh, and persistence. Eliminates the need for manual claude login in automated environments.

Features

  • Automatic token setup via claude setup-token
  • Persistent storage across application restarts
  • Token expiry detection and automatic refresh
  • Multi-provider support (Anthropic, AWS Bedrock, GCP Vertex)
  • Graceful fallback to ANTHROPIC_API_KEY environment variable

Usage

# One-time setup (interactive, requires Claude subscription)
{:ok, token} = ClaudeCodeSDK.AuthManager.setup_token()

# Subsequent calls automatically use stored token
ClaudeCodeSDK.query("Hello")  # ✅ Authenticated

# Manual refresh if needed
{:ok, token} = ClaudeCodeSDK.AuthManager.refresh_token()

Configuration

# config/config.exs
config :claude_code_sdk,
  auth_storage: :file,  # :file | :application_env | :custom
  auth_file_path: "~/.claude_sdk/token.json",
  auto_refresh: true,
  refresh_before_expiry: 86_400_000  # 1 day in ms

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_auth()

Clears stored authentication.

ensure_authenticated()

Ensures authentication is valid and available.

get_token()

Retrieves the current authentication token.

refresh_token()

Forces a token refresh.

setup_token()

Sets up a new authentication token interactively.

start_link(opts \\ [])

Starts the AuthManager GenServer.

status()

Returns current authentication status.

Types

t()

@type t() :: %ClaudeCodeSDK.AuthManager{
  expiry: DateTime.t() | nil,
  provider: atom(),
  refresh_timer: reference() | nil,
  storage_backend: module(),
  token: String.t() | nil
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_auth()

@spec clear_auth() :: :ok

Clears stored authentication.

Useful for logout or testing.

Examples

iex> ClaudeCodeSDK.AuthManager.clear_auth()
:ok

ensure_authenticated()

@spec ensure_authenticated() :: :ok | {:error, term()}

Ensures authentication is valid and available.

Checks authentication in order of precedence:

  1. ANTHROPIC_API_KEY environment variable
  2. Valid stored token
  3. Automatic token setup (if interactive)

Returns :ok if authenticated, {:error, reason} otherwise.

Examples

iex> ClaudeCodeSDK.AuthManager.ensure_authenticated()
:ok

# In CI without token:
iex> ClaudeCodeSDK.AuthManager.ensure_authenticated()
{:error, :authentication_required}

get_token()

@spec get_token() :: {:ok, String.t()} | {:error, :not_authenticated}

Retrieves the current authentication token.

Returns the token if valid, error otherwise.

Examples

iex> ClaudeCodeSDK.AuthManager.get_token()
{:ok, "sk-ant-api03-..."}

iex> ClaudeCodeSDK.AuthManager.get_token()
{:error, :not_authenticated}

refresh_token()

@spec refresh_token() :: {:ok, String.t()} | {:error, term()}

Forces a token refresh.

Useful for testing or manual token rotation.

Examples

iex> ClaudeCodeSDK.AuthManager.refresh_token()
{:ok, "sk-ant-api03-..."}

setup_token()

@spec setup_token() :: {:ok, String.t()} | {:error, term()}

Sets up a new authentication token interactively.

Executes claude setup-token which requires:

  • Claude subscription
  • Interactive terminal access
  • Browser for OAuth flow

Examples

iex> ClaudeCodeSDK.AuthManager.setup_token()
{:ok, "sk-ant-api03-..."}

iex> ClaudeCodeSDK.AuthManager.setup_token()
{:error, "claude setup-token failed: not subscribed"}

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the AuthManager GenServer.

Automatically loads existing tokens from storage on startup.

status()

@spec status() :: map()

Returns current authentication status.

Examples

iex> ClaudeCodeSDK.AuthManager.status()
%{
  authenticated: true,
  provider: :anthropic,
  token_present: true,
  expires_at: ~U[2025-11-07 00:00:00Z],
  time_until_expiry_hours: 720
}