# `ClaudeAgentSDK.AuthManager`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.21.0/lib/claude_agent_sdk/auth_manager.ex#L1)

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

# `t`

```elixir
@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
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clear_auth`

```elixir
@spec clear_auth() :: :ok | {:error, term()}
```

Clears stored authentication.

Useful for logout or testing.

## Examples

    iex> ClaudeAgentSDK.AuthManager.clear_auth()
    :ok

# `ensure_authenticated`

```elixir
@spec ensure_authenticated(keyword()) :: :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`

```elixir
@spec get_token(keyword()) ::
  {:ok, String.t()}
  | {:error, :not_authenticated | :governed_token_unavailable | term()}
```

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`

```elixir
@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`

```elixir
@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`

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

Starts the AuthManager GenServer.

Automatically loads existing tokens from storage on startup.

# `status`

```elixir
@spec status(keyword()) :: 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
    }

---

*Consult [api-reference.md](api-reference.md) for complete listing*