HfHub.Auth (HfHub v0.3.1)

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()

Summary

Functions

auth_headers(opts \\ [])

Builds HTTP authorization headers from the current or provided token.

get_token()

Retrieves the current HuggingFace token from application configuration.

Interactive login flow.

logout()

Logs out and removes stored credentials.

set_token(token)

Sets the HuggingFace authentication token.

validate_token(token)

Validates a token.

whoami()

Gets information about the current authenticated user.

Types

user_info()

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

Functions

auth_headers(opts \\ [])

@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()

@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(opts \\ [])

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

Interactive login flow.

Prompts for a token and stores it for future use.

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

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

logout()

@spec logout() :: :ok

Logs out and removes stored credentials.

Examples

:ok = HfHub.Auth.logout()

set_token(token)

@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(token)

@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()

@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)