Ephemeral tokens

Les jetons éphémères sont des jetons d'authentification de courte durée permettant d'accéder à l'API Gemini via des WebSockets. Elles sont conçues pour renforcer la sécurité lorsque vous vous connectez directement à l'API depuis l'appareil d'un utilisateur (implémentation client-serveur). Comme les clés API standards, les jetons éphémères peuvent être extraits des applications côté client, telles que les navigateurs Web ou les applications mobiles. Cependant, comme les jetons éphémères expirent rapidement et peuvent être limités, ils réduisent considérablement les risques de sécurité dans un environnement de production.

Fonctionnement des jetons éphémères

Voici comment fonctionnent les jetons éphémères de manière générale:

1. Votre client (par exemple, une application Web) s'authentifie auprès de votre backend.
2. Votre backend demande un jeton éphémère au service de provisionnement de l'API Gemini.
3. L'API Gemini émet un jeton de courte durée.
4. Votre backend envoie le jeton au client pour les connexions WebSocket à l'API Live. Pour ce faire, remplacez votre clé API par un jeton éphémère.
5. Le client utilise ensuite le jeton comme s'il s'agissait d'une clé API.

Cela renforce la sécurité, car même s'il est extrait, le jeton est de courte durée, contrairement à une clé API de longue durée déployée côté client. Étant donné que le client envoie des données directement à Gemini, cela améliore également la latence et évite à vos backends d'utiliser un proxy pour les données en temps réel.

Créer un jeton éphémère

Voici un exemple simplifié illustrant comment obtenir un jeton éphémère à partir de Gemini. Par défaut, vous disposez d'une minute pour démarrer de nouvelles sessions d'API Live à l'aide du jeton de cette requête (newSessionExpireTime) et de 30 minutes pour envoyer des messages via cette connexion (expireTime).

import datetime

now = datetime.datetime.now(tz=datetime.timezone.utc)

client = genai.Client(
    http_options={'api_version': 'v1alpha',}
)

token = client.auth_tokens.create(
    config = {
    'uses': 1, # The ephemeral token can only be used to start a single session
    'expire_time': now + datetime.timedelta(minutes=30), # Default is 30 minutes in the future
    # 'expire_time': '2025-05-17T00:00:00Z',   # Accepts isoformat.
    'new_session_expire_time': now + datetime.timedelta(minutes=1), # Default 1 minute in the future
    'http_options': {'api_version': 'v1alpha'},
  }
)

# You'll need to pass the value under token.name back to your client to use it

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

  const token: AuthToken = await client.authTokens.create({
    config: {
      uses: 1, // The default
      expireTime: expireTime // Default is 30 mins
      newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future
      httpOptions: {apiVersion: 'v1alpha'},
    },
  });

Pour connaître les contraintes, les valeurs par défaut et les autres spécifications de champ expireTime, consultez la documentation de référence de l'API. Dans le délai expireTime, vous devez sessionResumption pour reconnecter l'appel toutes les 10 minutes (cela peut être fait avec le même jeton, même si uses: 1).

Vous pouvez également verrouiller un jeton éphémère à un ensemble de configurations. Cela peut être utile pour améliorer davantage la sécurité de votre application et conserver vos instructions système côté serveur.

client = genai.Client(
    http_options={'api_version': 'v1alpha',}
)

token = client.auth_tokens.create(
    config = {
    'uses': 1,
    'live_connect_constraints': {
        'model': 'gemini-2.0-flash-live-001',
        'config': {
            'session_resumption':{},
            'temperature':0.7,
            'response_modalities':['TEXT']
        }
    },
    'http_options': {'api_version': 'v1alpha'},
    }
)

# You'll need to pass the value under token.name back to your client to use it

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();

const token = await client.authTokens.create({
    config: {
        uses: 1, // The default
        expireTime: expireTime,
        liveConnectConstraints: {
            model: 'gemini-2.0-flash-live-001',
            config: {
                sessionResumption: {},
                temperature: 0.7,
                responseModalities: ['TEXT']
            }
        },
        httpOptions: {
            apiVersion: 'v1alpha'
        }
    }
});

// You'll need to pass the value under token.name back to your client to use it

Vous pouvez également verrouiller un sous-ensemble de champs. Pour en savoir plus, consultez la documentation du SDK.

Se connecter à l'API Live avec un jeton éphémère

Voici un exemple de connexion à l'API Live via un jeton éphémère. Notez que l'utilisation de jetons éphémères n'ajoute de la valeur que lors du déploiement d'applications qui suivent l'approche d'implémentation client-serveur.

import { GoogleGenAI, Modality } from '@google/genai';

// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({});
const model = 'gemini-2.0-flash-live-001';
const config = { responseModalities: [Modality.TEXT] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: { ... },
  });

  // Send content...

  session.close();
}

main();

Pour en savoir plus, consultez Premiers pas avec l'API Live.

Bonnes pratiques

• Définissez une durée d'expiration courte à l'aide du paramètre expire_time.
• Les jetons expirent et nécessitent de relancer le processus de provisionnement.
• Vérifiez l'authentification sécurisée pour votre propre backend. Les jetons éphémères ne seront sécurisés que si votre méthode d'authentification backend l'est.
• En règle générale, évitez d'utiliser des jetons éphémères pour les connexions backend-to-Gemini, car ce chemin est généralement considéré comme sécurisé.

Limites

Pour le moment, les jetons éphémères ne sont compatibles qu'avec l'API Live.

Étape suivante

• Pour en savoir plus, consultez la documentation de référence de l'API Live sur les jetons éphémères.