ExLLM.Gemini.Auth (ex_llm v0.5.0)

View Source

OAuth2 authentication helper for Google Gemini APIs that require user authentication.

This module provides utilities for obtaining and managing OAuth2 tokens for APIs like the Permissions API that don't support API key authentication.

Usage

# Option 1: Service Account (recommended for servers)
{:ok, token} = ExLLM.Gemini.Auth.get_service_account_token()

# Option 2: User OAuth2 flow
{:ok, auth_url} = ExLLM.Gemini.Auth.get_authorization_url()
# ... user authorizes ...
{:ok, tokens} = ExLLM.Gemini.Auth.exchange_code(auth_code)

# Use with Permissions API
ExLLM.Gemini.Permissions.list_permissions("tunedModels/my-model",
  oauth_token: token
)

Summary

Functions

Simple CLI flow for obtaining OAuth2 tokens.

Exchanges an authorization code for access and refresh tokens.

Gets the authorization URL for the OAuth2 flow.

Gets a service account token using Application Default Credentials.

Refreshes an access token using a refresh token.

Revokes a token (access token or refresh token).

Validates if a token is still valid by checking with Google's tokeninfo endpoint.

Types

oauth_config()

@type oauth_config() :: %{
  client_id: String.t(),
  client_secret: String.t(),
  redirect_uri: String.t()
}

token_response()

@type token_response() :: %{
  access_token: String.t(),
  token_type: String.t(),
  expires_in: integer(),
  refresh_token: String.t() | nil,
  scope: String.t()
}

Functions

cli_flow(opts \\ [])

@spec cli_flow(Keyword.t()) :: {:ok, token_response()} | {:error, term()}

Simple CLI flow for obtaining OAuth2 tokens.

This starts a local web server to receive the OAuth2 callback. Useful for CLI tools and development.

Options

  • :port - Local server port (default: 8080)
  • :client_id - Google OAuth2 client ID
  • :client_secret - Google OAuth2 client secret
  • :scopes - List of OAuth2 scopes

Examples

{:ok, tokens} = ExLLM.Gemini.Auth.cli_flow(
  client_id: "your-client-id",
  client_secret: "your-client-secret"
)

exchange_code(code, opts \\ [])

@spec exchange_code(String.t(), Keyword.t()) ::
  {:ok, token_response()} | {:error, term()}

Exchanges an authorization code for access and refresh tokens.

Parameters

  • code - The authorization code from the OAuth2 callback
  • opts - Options including client credentials and redirect URI

Examples

{:ok, tokens} = ExLLM.Gemini.Auth.exchange_code(auth_code,
  client_id: "your-client-id",
  client_secret: "your-client-secret",
  redirect_uri: "http://localhost:8080/callback"
)

get_authorization_url(opts \\ [])

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

Gets the authorization URL for the OAuth2 flow.

Options

  • :client_id - Google OAuth2 client ID (required)
  • :redirect_uri - Callback URL (default: "http://localhost:8080/callback")
  • :scopes - List of OAuth2 scopes (default: generative language scope)
  • :access_type - "online" or "offline" (default: "offline" for refresh tokens)
  • :prompt - "none", "consent", or "select_account" (default: "consent")
  • :state - Optional state parameter for CSRF protection

Examples

{:ok, url} = ExLLM.Gemini.Auth.get_authorization_url(
  client_id: "your-client-id",
  scopes: [:generative_language, :tuning]
)

get_service_account_token(opts \\ [])

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

Gets a service account token using Application Default Credentials.

This requires either:

  1. GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to a service account JSON file
  2. Running on Google Cloud with appropriate service account attached
  3. Using gcloud auth application-default login

Options

  • :scopes - List of OAuth2 scopes (default: generative language scope)

Examples

# Requires Goth library to be added to your project
{:ok, token} = ExLLM.Gemini.Auth.get_service_account_token()

refresh_token(refresh_token, opts \\ [])

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

Refreshes an access token using a refresh token.

Parameters

  • refresh_token - The refresh token
  • opts - Options including client credentials

Examples

{:ok, new_token} = ExLLM.Gemini.Auth.refresh_token(stored_refresh_token)

revoke_token(token, opts \\ [])

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

Revokes a token (access token or refresh token).

Parameters

  • token - The token to revoke
  • opts - Options (currently unused)

Examples

:ok = ExLLM.Gemini.Auth.revoke_token(access_token)

validate_token(access_token)

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

Validates if a token is still valid by checking with Google's tokeninfo endpoint.

Parameters

  • access_token - The access token to validate

Returns

  • {:ok, token_info} - Token is valid, returns info including expiry
  • {:error, reason} - Token is invalid or expired