# `HfHub.Auth`
[🔗](https://github.com/North-Shore-AI/hf_hub_ex/blob/v0.3.1/lib/hf_hub/auth.ex#L1)

Authentication and authorization for HuggingFace Hub.

Handles token management, login/logout flows, and user information retrieval.

## Examples

    # Get current token
    {:ok, token} = HfHub.Auth.get_token()

    # Set token
    :ok = HfHub.Auth.set_token("hf_...")

    # Get current user info
    {:ok, user} = HfHub.Auth.whoami()

    # Logout
    :ok = HfHub.Auth.logout()

# `user_info`

```elixir
@type user_info() :: %{
  username: String.t(),
  email: String.t(),
  fullname: String.t() | nil,
  organizations: [String.t()]
}
```

# `auth_headers`

```elixir
@spec auth_headers(keyword()) :: {:ok, [{String.t(), String.t()}]} | {:error, term()}
```

Builds HTTP authorization headers from the current or provided token.

## Options

  * `:token` - Token to use. If not provided, uses get_token/0.

## Examples

    {:ok, headers} = HfHub.Auth.auth_headers()
    # => {:ok, [{"authorization", "Bearer hf_..."}]}

    {:ok, headers} = HfHub.Auth.auth_headers(token: "hf_custom")

# `get_token`

```elixir
@spec get_token() :: {:ok, String.t()} | {:error, :no_token}
```

Retrieves the current HuggingFace token from application configuration.

Per Elixir runtime-configuration best practices, this library no longer
reads `HF_TOKEN` from the OS environment directly. Hosts wire env vars
into `Application.put_env(:hf_hub, :token, ...)` from their
`config/runtime.exs` (or via `HfHub.Auth.set_token/1` at runtime). See
the `HfHub` moduledoc for the recommended snippet.

## Examples

    {:ok, token} = HfHub.Auth.get_token()

# `login`

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

Interactive login flow.

Prompts for a token and stores it for future use.

## Options

  * `:token` - Token to use (skips prompt)
  * `:add_to_git_credentials` - Add token to git credentials. Defaults to `false`.

## Examples

    :ok = HfHub.Auth.login(token: "hf_...")
    :ok = HfHub.Auth.login()  # Interactive prompt

# `logout`

```elixir
@spec logout() :: :ok
```

Logs out and removes stored credentials.

## Examples

    :ok = HfHub.Auth.logout()

# `set_token`

```elixir
@spec set_token(String.t()) :: :ok
```

Sets the HuggingFace authentication token.

The token is stored in application configuration for the current session.

## Arguments

  * `token` - HuggingFace API token (starts with "hf_")

## Examples

    :ok = HfHub.Auth.set_token("hf_...")

# `validate_token`

```elixir
@spec validate_token(String.t()) :: :ok | {:error, term()}
```

Validates a token.

Checks if the token is properly formatted and valid with the Hub API.

## Arguments

  * `token` - Token to validate

## Examples

    :ok = HfHub.Auth.validate_token("hf_...")
    {:error, :invalid_token} = HfHub.Auth.validate_token("bad_token")

# `whoami`

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

Gets information about the current authenticated user.

Requires a valid authentication token.

## Examples

    {:ok, user} = HfHub.Auth.whoami()
    IO.inspect(user.username)
    IO.inspect(user.organizations)

---

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