ClaudeAgentSDK.AuthManager (claude_agent_sdk v0.15.0)

Copy Markdown 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} = ClaudeAgentSDK.AuthManager.setup_token()

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

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

Configuration

# config/config.exs
config :claude_agent_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() :: %ClaudeAgentSDK.AuthManager{
  expiry: DateTime.t() | nil,
  provider: atom(),
  provider_backend: module(),
  refresh_timer: reference() | nil,
  setup_operation: :ensure | :setup | :refresh | :auto_refresh | nil,
  setup_task_pid: pid() | nil,
  setup_task_ref: reference() | nil,
  setup_waiters: [{GenServer.from(), :ensure | :setup | :refresh}],
  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 | {:error, term()}

Clears stored authentication.

Useful for logout or testing.

Examples

iex> ClaudeAgentSDK.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> ClaudeAgentSDK.AuthManager.ensure_authenticated()
:ok

# In CI without token:
iex> ClaudeAgentSDK.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> ClaudeAgentSDK.AuthManager.get_token()
{:ok, "sk-ant-api03-..."}

iex> ClaudeAgentSDK.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> ClaudeAgentSDK.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> ClaudeAgentSDK.AuthManager.setup_token()
{:ok, "sk-ant-api03-..."}

iex> ClaudeAgentSDK.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> ClaudeAgentSDK.AuthManager.status()
%{
  authenticated: true,
  provider: :anthropic,
  token_present: true,
  expires_at: ~U[2025-11-07 00:00:00Z],
  time_until_expiry_hours: 720
}