SSO e iframes

El flujo SSO permite que un usuario ya identificado en tu sistema entre en FichaChat sin volver a iniciar sesión, ya sea siguiendo un enlace o dentro de un iframe.

1. Crear un token SSO

Requiere X-API-Key. Identifica al usuario por email o por user_id.

POST /api/v1/integrations/companies/{slug}/sso/token/
X-API-Key: fc_xxxxx
Content-Type: application/json

{ "email": "empleada@minegocio.com" }

Respuesta 201 Created:

{
  "token": "xxxxx",
  "login_url": "https://app.fichachat.com/auth/sso-login?token=xxxxx",
  "expires_at": "2026-01-01T00:05:00Z",
  "user": {
    "id": "uuid",
    "email": "empleada@minegocio.com",
    "role": "employee",
    "full_name": "Laura Pérez"
  }
}

• El token caduca a los 5 minutos y es de un solo uso. Genera uno nuevo por cada acceso.
• login_url es un enlace listo para usar (ver más abajo).

Para quién puede emitirse (si no, 403 con "code": "sso_role_not_allowed"):

Rol	Token SSO
Empleado	Siempre
Responsable	Solo si el subscription_plan de la empresa está entre los planes permitidos de tu clave (la misma clave que crea la empresa y su responsable)
Inspector	Nunca

Una clave sin planes permitidos solo puede emitir tokens de empleado.

2a. Enlace de acceso directo

Envía login_url al usuario (correo, notificación en tu app, botón «Abrir FichaChat»). Al abrirlo, FichaChat lo autentica y lo lleva a su pantalla según el rol: el responsable a /boss/employees y el empleado a /employee/dashboard.

import httpx

API_KEY = "fc_xxxxx"

def direct_login_url(company_slug: str, user_email: str) -> str:
    r = httpx.post(
        f"https://api.fichachat.com/api/v1/integrations/companies/{company_slug}/sso/token/",
        headers={"X-API-Key": API_KEY},
        json={"email": user_email},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()["login_url"]

2b. Iframe

Incrusta FichaChat pasándole el token en la URL. Hay dos vistas:

Vista	URL
Portal del empleado	https://app.fichachat.com/iframe/employee?sso_token=<token>
Panel del responsable	https://app.fichachat.com/iframe/boss?sso_token=<token>

<iframe
  src="https://app.fichachat.com/iframe/employee?sso_token=xxxxx"
  style="width: 100%; height: 600px; border: none;"
></iframe>

Flujo completo:

1. Tu backend pide el token SSO a FichaChat (con la clave de API).
2. Tu frontend carga el iframe con ?sso_token=<token>.
3. FichaChat intercambia el token por un JWT y muestra la vista ya autenticada.

Orígenes permitidos: configura allowed_origins en tu clave de API con los dominios desde los que incrustarás FichaChat; los demás orígenes se rechazan.

3. Intercambio del token por JWT

Lo usa el frontend de FichaChat, pero es público (sin clave de API) por si tu propio cliente necesita los tokens:

POST /api/v1/integrations/sso/exchange/
Content-Type: application/json

{ "token": "xxxxx" }

Respuesta 200 OK:

{
  "access": "jwt_access_token",
  "refresh": "jwt_refresh_token",
  "user": {
    "id": "uuid",
    "email": "empleada@minegocio.com",
    "role": "employee",
    "company": "uuid",
    "company_name": "Mi Negocio SL"
  }
}

Página de acceso con el email precargado

Si prefieres que el usuario introduzca su contraseña, puedes enviarlo a la pantalla de acceso con el email ya rellenado:

Usuario	URL
Responsable	https://app.fichachat.com/auth/login?email=admin@minegocio.com
Empleado (subdominio)	https://<slug>.web.fichachat.com/auth/login?email=empleada@minegocio.com
Empleado (ruta interna)	https://app.fichachat.com/web/<slug>/auth/login?email=empleada@minegocio.com