Autenticar a tus usuarios

Cuando alguien usa el chat en tu aplicación, Syncanix necesita saber quién es, para que el asistente actúe como esa persona y nadie más. Tú mantienes el control de la identidad: Syncanix verifica un token que emite tu propio sistema, en lugar de pedir a tus usuarios que creen una cuenta de Syncanix aparte.

Los cuatro modos de autenticación

Elige uno según cómo gestiona ya la autenticación tu aplicación. Van desde unas pocas líneas de código en el backend hasta una configuración totalmente con proxy en la que el widget nunca ve un token.

Token de sesión firmado (predeterminado)

Tu backend genera un token firmado de corta duración para el usuario conectado con un secreto compartido y se lo entrega al widget. Es el camino más rápido —unas pocas líneas de código en el servidor— y encaja en la mayoría de las apps que ya tienen su propio inicio de sesión. Genera el secreto compartido en la página Federación de identidades del panel: se muestra una sola vez y puedes rotarlo cuando quieras.

Adaptador de proveedor de identidad (recomendado)

Si ya usas Auth0, Clerk, Amazon Cognito o WorkOS, el widget lee el token que el SDK de tu proveedor ya emite en el navegador, y Syncanix lo verifica en el servidor con las claves públicas de tu proveedor. No hay que gestionar ningún secreto nuevo y la reverificación adicional funciona desde el primer momento.

Intercambio de tokens OAuth

Para entornos empresariales, Syncanix admite el flujo estándar de intercambio de tokens (RFC 8693): tu servidor de autorización cambia un token existente por uno de alcance reducido ligado a la sesión de chat. Ideal cuando tu equipo de seguridad quiere que cada token derivado se emita y se audite de forma explícita.

Backend para frontend (BFF)

La opción más blindada: un pequeño proxy que ejecutas se sitúa entre el widget y Syncanix, de modo que los tokens nunca llegan al navegador. Elígela cuando la política prohíba cualquier token en el código del lado del cliente.

Token de sesión firmado, de principio a fin

La integración más rápida es un pequeño endpoint de tokens en tu backend más dos líneas en tu página. Esta es la configuración completa.

1. 1
   Genera el secreto compartidoEn el panel, abre Configuración → Federación de identidad y genera el secreto del token de sesión. Se muestra exactamente una vez: guárdalo en tu gestor de secretos, por ejemplo como SYNCANIX_SESSION_SECRET.
2. 2
   Añade un endpoint de tokens a tu backendDetrás de tu login existente, firma un token de corta duración para el usuario actual con el secreto compartido.
3. 3
   Entrega el token al widgetRegistra un proveedor de tokens que consulte tu endpoint: el widget lo llama antes de cada turno.

Un ejemplo en Node con la librería jose (cualquier librería JWT en cualquier lenguaje funciona igual):

import { SignJWT } from 'jose';

const secret = new TextEncoder().encode(process.env.SYNCANIX_SESSION_SECRET);

app.get('/api/chat-token', requireLogin, async (req, res) => {
  const token = await new SignJWT({ tenant: process.env.SYNCANIX_WORKSPACE_ID })
    .setProtectedHeader({ alg: 'HS256' })
    .setSubject(req.user.id)
    .setAudience('syncanix-tools')
    .setIssuedAt()
    .setExpirationTime('10m')
    .sign(secret);
  res.json({ token });
});

Uses la librería que uses, el token debe llevar exactamente estos claims:

• aud — la cadena fija syncanix-tools.
• sub — el id estable de tu usuario; es como quien actúa el asistente.
• tenant — el ID de tu espacio de trabajo (puedes leerlo en tu URL de conexión MCP, en la página MCP del panel).
• exp e iat — caducidad como máximo 15 minutos tras la emisión; cuanto más corta, mejor.

Después conecta el widget con tu endpoint:

window.syncanix?.setTokenProvider(async () => {
  const res = await fetch('/api/chat-token');
  const { token } = await res.json();
  return token;
});

¿Cuál deberías elegir?

Quieres el inicio más rápido

Usa el token de sesión firmado: solo necesitas un pequeño endpoint en el backend.

Ya usas un proveedor de identidad alojado

Usa el adaptador de proveedor de identidad: reutiliza lo que ya tienes y habilita la verificación adicional.

Tienes requisitos de seguridad estrictos

Usa el intercambio de tokens OAuth o el BFF, según si los tokens pueden llegar al navegador o no.

Próximos pasos