Tokens Ephemeres et Securite

Le probleme de la cle API cote client

Quand votre application vocale s’execute dans le navigateur ou sur un appareil mobile, vous ne pouvez pas embarquer votre cle API dans le code. N’importe quel utilisateur pourrait l’extraire des outils de developpement et l’utiliser a vos frais. C’est un risque de securite majeur.

La solution de xAI : les tokens ephemeres (client secrets).

Comment fonctionnent les tokens ephemeres

Le principe est simple :

1. Votre backend (serveur securise) appelle POST /v1/realtime/client_secrets avec votre cle API
2. L’API retourne un token temporaire avec une duree de vie limitee
3. Votre backend envoie ce token au client (navigateur/mobile)
4. Le client utilise ce token pour se connecter au WebSocket Voice Agent
5. Le token expire apres utilisation ou apres sa duree de vie

Generer un token depuis votre backend

// Backend Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
  // Verifier l'authentification de l'utilisateur
  if (!req.user) return res.status(401).json({ error: "Non autorise" });

  const response = await fetch(
    "https://api.x.ai/v1/realtime/client_secrets",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer " + process.env.XAI_API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        ttl: 600  // 10 minutes
      })
    }
  );

  const data = await response.json();
  res.json({ token: data.client_secret });
});

Utiliser le token cote client

// Frontend (navigateur)
async function startVoiceSession() {
  // Demander un token au backend
  const tokenRes = await fetch("/api/voice-token", { method: "POST" });
  const { token } = await tokenRes.json();

  // Se connecter au Voice Agent avec le token ephemere
  const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
    headers: { "Authorization": "Bearer " + token }
  });

  // ... configuration de la session
}

Architecture de securite recommandee

Le flux complet est le suivant :

1. L’utilisateur s’authentifie sur votre application
2. Le client demande un token vocal a votre backend
3. Votre backend verifie l’authentification et les droits
4. Votre backend genere un token ephemere via l’API xAI
5. Le token est envoye au client
6. Le client se connecte au Voice Agent avec ce token
7. Le token expire automatiquement apres usage ou apres le TTL

Controle d’acces

Votre backend peut ajouter des verifications avant de generer un token :

• Quotas utilisateur : limiter le nombre de sessions vocales par utilisateur et par jour
• Verification d’abonnement : n’accorder de tokens qu’aux utilisateurs avec un plan actif
• Rate limiting : empecher un utilisateur de demander trop de tokens en peu de temps
• Logging : enregistrer chaque generation de token pour le monitoring et la facturation

Bonnes pratiques de securite

Ne jamais exposer la cle API

• Jamais dans le code JavaScript front-end
• Jamais dans les variables d’environnement accessibles cote client
• Jamais dans les URLs, logs ou messages d’erreur visibles

Duree de vie minimale

Configurez le TTL le plus court possible. Pour une session vocale typique de 5 minutes, un TTL de 600 secondes (10 minutes) est suffisant. N’utilisez le maximum de 3600 secondes que si votre cas d’usage le justifie.

Renouvellement

Si une session dure plus longtemps que prevu, votre client doit pouvoir demander un nouveau token avant l’expiration de l’ancien. Implementez un mecanisme de renouvellement :

function scheduleTokenRenewal(ttl) {
  // Renouveler le token 60 secondes avant expiration
  setTimeout(async () => {
    const newToken = await requestNewToken();
    reconnectWithToken(newToken);
  }, (ttl - 60) * 1000);
}

Proxying du backend

Pour le TTS en mode HTTP, une alternative aux tokens ephemeres est de proxier les requetes via votre backend. Le client envoie le texte a votre backend, votre backend appelle le TTS, et retourne l’audio au client. L’avantage : la cle API ne quitte jamais votre serveur.

Points cles a retenir

• Les tokens ephemeres securisent l’acces au Voice Agent depuis les applications cote client
• Le endpoint POST /v1/realtime/client_secrets genere un token avec un TTL configurable (max 3600s)
• Votre backend doit verifier l’authentification et les droits avant de generer un token
• N’exposez jamais votre cle API cote client, dans les URLs ou dans les logs
• Pour le TTS HTTP, le proxying via votre backend est une alternative valide aux tokens ephemeres