# `Gemini.Live.EphemeralToken`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.15.0/lib/gemini/live/ephemeral_token.ex#L1)

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.

# `create_opts`

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

# `create`

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

---

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