Gemini.Live.EphemeralToken (GeminiEx v0.11.0)

Creates ephemeral tokens for client-side Live API access.

Ephemeral tokens allow secure client-side WebSocket connections by providing short-lived, restricted credentials. They are designed for client-to-server implementations where the token is used in a browser or mobile app.

Security Benefits

Short-lived tokens reduce risk if extracted from client-side code
Tokens can be locked to specific configurations
Usage limits prevent token reuse

Usage

# Server-side: Create token
{:ok, token} = EphemeralToken.create(
  uses: 1,
  expire_minutes: 30,
  live_connect_constraints: %{
    model: "gemini-2.5-flash-native-audio-preview-12-2025",
    config: %{response_modalities: ["AUDIO"]}
  }
)

# Return token.name to client
# Client uses token.name as API key for WebSocket connection

Token Lifetimes

expire_time - How long the token is valid for messages (default: 30 minutes)
new_session_expire_time - Deadline to start a new session (default: 1 minute)

Constraints

Tokens can be locked to specific configurations:

Model name
Generation config (response modalities, temperature, etc.)
Session resumption settings

This prevents clients from using the token with different configurations than intended by the server.

Note

Ephemeral tokens are only compatible with the Live API at this time.

Summary

Types

create_opts()

Functions

create(opts \\ [])

Creates an ephemeral token for Live API access.

Types

create_opts()

@type create_opts() :: [
  uses: pos_integer(),
  expire_minutes: pos_integer(),
  new_session_expire_minutes: pos_integer(),
  live_connect_constraints: map()
]

Functions

create(opts \\ [])

@spec create(create_opts()) :: {:ok, map()} | {:error, term()}

Creates an ephemeral token for Live API access.

Options

:uses - Number of times token can be used (default: 1)
:expire_minutes - Token expiration in minutes (default: 30)
:new_session_expire_minutes - New session deadline in minutes (default: 1)
:live_connect_constraints - Lock token to specific config

Constraints Format

The :live_connect_constraints option accepts a map with:

:model - Model name to lock to
:config - Configuration map with:
- :response_modalities - List of modalities (:audio, :text, or strings)
- :temperature - Temperature setting
- :session_resumption - Session resumption config

Returns

{:ok, %{name: token_string, ...}} - Token created successfully
{:error, reason} - Token creation failed

Examples

# Simple token
{:ok, token} = EphemeralToken.create()

# Token with constraints
{:ok, token} = EphemeralToken.create(
  uses: 1,
  expire_minutes: 15,
  live_connect_constraints: %{
    model: "gemini-2.5-flash-native-audio-preview-12-2025",
    config: %{
      response_modalities: [:audio],
      temperature: 0.7
    }
  }
)

# Use the token name as API key
token.name  # => "authTokens/abc123..."