Ir al contenido principal
Español— Elegir un idioma
Menú

Tokens efímeros para conexiones WebSocket

Lección 5 de 12 Actualizado el 28 de julio de 2026 Avanzado
En esta página
  1. El problema: autenticar un cliente sin exponer tu clave
  2. Cómo funcionan los tokens efímeros
  3. Elección de la duración adecuada
  4. Implementación en el backend
  5. Puntos clave

El problema: autenticar un cliente sin exponer tu clave

Al desarrollar una aplicación de voz o en tiempo real con la API de Grok, necesitas establecer una conexión WebSocket directamente desde el navegador o el cliente móvil. Enrutar el tráfico a través de tu servidor añade latencia, lo que rompe la fluidez de la conversación por voz. Sin embargo, las conexiones directas plantean un problema de autenticación: nunca debes incluir tu clave de API en el código del lado del cliente.

La razón es sencilla: cualquier clave incrustada en JavaScript del frontend, en una aplicación móvil descompilable o en un binario distribuido queda comprometida en el momento de su publicación. Cualquier usuario puede abrir las herramientas de desarrollo de su navegador y leerla. Para resolver esto, xAI ofrece tokens efímeros: tokens temporales que los clientes pueden utilizar sin llegar a ver nunca la clave maestra.

600s
Duración predeterminada
3600s
Duración máxima
POST
/v1/realtime/client_secrets
Bearer
Token temporal

Cómo funcionan los tokens efímeros

La arquitectura sigue un principio: la clave de API nunca abandona tu servidor y el cliente recibe únicamente un token de corta duración. El flujo es breve. El cliente solicita un token a tu backend, el cual llama a POST /v1/realtime/client_secrets con tu clave de API. Esta llamada es el único lugar donde aparece la clave y ocurre íntegramente en el servidor. xAI devuelve un token efímero con su fecha de caducidad, que tu backend transmite al cliente. A continuación, el cliente abre la conexión WebSocket a wss://api.x.ai/v1/realtime presentando este token. En ningún momento el navegador ve la clave maestra; solo gestiona un token que caduca por sí solo.

La llamada de creación desde tu backend tiene este aspecto:

curl -X POST https://api.x.ai/v1/realtime/client_secrets \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_after": {"seconds": 600}}'

Y la respuesta:

{
  "value": "Bearer eyJhbGciOiJSUzI1NiIs...",
  "expires_at": 1712001200
}

En cuanto a la duración, existen tres puntos de referencia: no hay un límite inferior documentado (son posibles unos pocos segundos), el valor predeterminado es de 600 segundos (10 minutos) y el máximo es de 3600 segundos (1 hora).

Elección de la duración adecuada

La duración del token debe ajustarse a tu caso de uso; esta elección constituye una decisión de seguridad real. Para interacciones de voz esporádicas (preguntas y respuestas, comandos de voz, dictado), una ventana de 300 a 600 segundos es más que suficiente: la sesión finalizará mucho antes de la caducidad. Para conversaciones de voz sostenidas, como atención al cliente, una entrevista o una reunión asistida, apunta a entre 600 y 1800 segundos para evitar cortes a mitad de la conversación. Las sesiones de trabajo prolongadas (transcripción en tiempo real, monitorización continua de voz) pueden justificar entre 1800 y 3600 segundos, pero utiliza la duración máxima con cautela: amplía la ventana de explotación si el token es robado.

La regla de oro se resume así: elige siempre la duración más corta compatible con tu caso de uso. Si interceptan un token, una caducidad de diez minutos convierte un incidente potencialmente grave en una molestia menor.

Implementación en el backend

Aquí tienes un ejemplo de un proxy seguro en Node.js:

// Ruta del backend - NO exponer en el lado del cliente
app.post("/api/realtime-token", authenticateUser, async (req, res) => {
  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 }
      })
    }
  );

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

Tres detalles de este ejemplo sustentan toda la seguridad de la configuración. La clave de API reside en una variable de entorno del servidor, nunca en el código. El middleware authenticateUser verifica la identidad del usuario antes de emitir un token; sin él, cualquiera podría obtener tokens y consumir tu cuota a tu costa. Y solo se devuelve al cliente el token efímero, nunca la clave.

Suelen aparecer algunos errores frecuentes en las revisiones de código. La clave de API colada en el frontend «solo para el prototipo» acaba invariablemente en producción. El token creado sistemáticamente con la duración máxima por comodidad, cuando el caso de uso requiere una cuarta parte de ese tiempo. El endpoint de generación dejado sin verificación de autenticación, abierto a todo el mundo. Y la falta de gestión de la renovación en el lado del cliente, lo que produce errores de caducidad a mitad de la sesión en lugar de una reconexión transparente: dado que la respuesta te proporciona expires_at, tu cliente tiene todo lo necesario para solicitar un nuevo token antes del plazo límite, no después.

Puntos clave

  • Los tokens efímeros permiten la autenticación WebSocket sin exponer tu clave de API
  • Endpoint: POST /v1/realtime/client_secrets (llamada exclusiva del servidor)
  • Duración configurable desde unos pocos segundos hasta un máximo de 3600 segundos (predeterminado: 600 s)
  • Tu backend actúa como un proxy de autenticación entre el cliente y xAI
  • Elige siempre la duración más corta compatible con tu uso