Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Token effimeri e sicurezza

Lezione 13 di 14 Aggiornata il 3 novembre 2026 Intermedio
In questa pagina
  1. Il problema della chiave API sul client
  2. Come funziona
  3. L’architettura end-to-end
  4. Regole da non infrangere mai
  5. Punti chiave

Aggiornato il 3 novembre 2026, sulla base del riferimento API Voice di xAI. Fonti: Token effimeri · Riferimento API Voice · Ripresa della sessione.

Il problema della chiave API sul client

Un’app vocale eseguita in un browser o su un telefono non può includere la tua chiave API. Qualsiasi visitatore può aprire gli strumenti per sviluppatori, leggere la chiave dal bundle JavaScript o da un’intestazione di richiesta e utilizzarla sul tuo account fino all’esaurimento della quota. Nessuna quantità di offuscamento protegge un valore che il client deve possedere per chiamare l’API.

La risposta di xAI sono i token effimeri, chiamati anche segreti client: un token a breve durata, generato dal tuo server, che autorizza una sessione vocale e nient’altro.

600s
durata predefinita
3600s
durata massima
POST
/v1/realtime/client_secrets
valore
il token, con expires_at

Come funziona

Il flusso si riduce a cinque passaggi:

  1. Il tuo backend (un server sicuro) chiama POST /v1/realtime/client_secrets con la tua chiave API
  2. L’API restituisce un token temporaneo con una durata limitata
  3. Il tuo backend invia quel token al client (browser o app mobile)
  4. Il client utilizza il token per connettersi al WebSocket dell’Agente Voice
  5. Il token scade dopo la durata che hai scelto (expires_after.seconds)

Ciò che può trapelare lato client ora vale molto meno: un token che scade in pochi minuti e può aprire solo una sessione vocale, non la tua chiave API. Sul server, generarne uno richiede poche righe di codice. Nota che il gestore inizia verificando l’utente: senza quel controllo, il tuo backend sarebbe semplicemente un distributore pubblico di token.

// Backend Node.js (Express)
app.post("/api/voice-token", async (req, res) => {
  // Verifica che l'utente sia autenticato
  if (!req.user) return res.status(401).json({ error: "Unauthorized" });

  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({
        expires_after: { seconds: 600 }  // 10 minuti, il valore predefinito
      })
    }
  );

  const data = await response.json();  // { value, expires_at }
  res.json({ token: data.value, expiresAt: data.expires_at });
});

Il client conosce solo il tuo route: richiede un token, quindi apre il WebSocket con esso.

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

  // Il WebSocket del browser non accetta intestazioni:
  // il token va in un sottoprotocollo, prefissato con "xai-client-secret."
  const ws = new WebSocket(
    "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
    [`xai-client-secret.${token}`]
  );

  // ... configurazione della sessione
}

L’architettura end-to-end

Mettendo insieme i pezzi, il flusso inizia con l’utente che accede alla tua app. Il suo client richiede quindi un token vocale al tuo backend, e il backend verifica autenticazione e permessi prima di generare il token effimero tramite l’API xAI. Il token torna al client, che lo usa per aprire la sessione dell’Agente Voice, e scade automaticamente alla fine della sua durata.

Quel controllo tra la richiesta e la generazione trasforma un semplice relay in un punto di controllo, ed è lì che risiedono le tue regole di business. Puoi limitare il numero di sessioni vocali per utente al giorno, così un singolo account non può bruciare il tuo budget mensile durante la notte. Puoi riservare i token agli abbonamenti attivi, facendo rispettare il tuo modello di business altrove rispetto all’interfaccia. Puoi applicare limiti di frequenza alle richieste, così un client difettoso o malintenzionato non può chiedere mille token al minuto. E puoi registrare ogni token che generi: è la tua unica base affidabile per il monitoraggio, la fatturazione interna e l’analisi degli incidenti.

Regole da non infrangere mai

La chiave API non va mai al client, in nessuna forma. Tienila fuori dal JavaScript front-end e da qualsiasi variabile d’ambiente esposta alla build del browser (le variabili prefissate per essere iniettate nel bundle finiscono per essere pubbliche). Tienila fuori anche da URL, log e messaggi di errore mostrati agli utenti.

Inoltre, mantieni la durata più breve possibile. Secondo il riferimento API, expires_after.seconds ha un valore predefinito di 600 secondi e un massimo di 3.600; la documentazione usa 300 nei suoi esempi. Soprattutto, il token deve essere valido quando il client apre la connessione. Una durata breve riduce la finestra temporale durante la quale un token intercettato può essere utilizzato.

La documentazione non specifica se un token in scadenza interrompa una connessione già aperta. Se il tuo client deve riconnettersi, dopo un’interruzione di rete o durante una sessione molto lunga, richiedi un nuovo token e usa la ripresa della sessione: abilita resumption.enabled in session.update, conserva l’ID ricevuto in conversation.created, quindi riapri il WebSocket con ?conversation_id=<id>. I turni precedenti vengono riprodotti e il modello riprende da dove aveva interrotto.

async function reconnect(conversationId) {
  const { token } = await (await fetch("/api/voice-token", { method: "POST" })).json();
  const url = `wss://api.x.ai/v1/realtime?model=grok-voice-latest&conversation_id=${conversationId}`;
  const ws = new WebSocket(url, [`xai-client-secret.${token}`]);
  ws.onopen = () => ws.send(JSON.stringify({
    type: "session.update",
    session: { resumption: { enabled: true } },  // invia di nuovo a ogni connessione
  }));
  return ws;
}

Per il TTS in modalità HTTP, esiste un’alternativa ancora più semplice ai token: un proxy. Il client invia il suo testo al tuo backend, e il tuo backend chiama il TTS e restituisce l’audio. La chiave non lascia mai il tuo server e ottieni un luogo naturale per filtrare i contenuti e misurare l’utilizzo lungo il percorso.

Punti chiave

  • I token effimeri proteggono l’accesso all’Agente Voice dalle app lato client
  • POST /v1/realtime/client_secrets restituisce value ed expires_at; expires_after.seconds ha un valore predefinito di 600 e un massimo di 3.600
  • Nel browser, il token va nel sottoprotocollo xai-client-secret.<token>
  • Il tuo backend deve verificare autenticazione e permessi prima di generare un token
  • Non esporre mai la tua chiave API sul client, negli URL o nei log
  • Per il TTS HTTP, il proxying tramite il tuo backend è un’alternativa valida ai token effimeri