Guía de Integración SSO JWT

Se prefiere SSO con JWT por su menor complejidad. La empresa firma un JWT de un solo uso con el secreto compartido, redirige al usuario al endpoint de Nume, y Nume crea o reactiva la cuenta e inicia sesión.

Integración preferida

Se prefiere SSO con JWT cuando el usuario ya está autenticado en el portal de la empresa. El flujo por tokens API aplica cuando no es posible redirigir el navegador con un JWT.

Flujo

  1. El usuario está autenticado en el portal de la empresa.
  2. La empresa firma un JWT con los datos del usuario, un jti único y el secreto compartido.
  3. Redirige el browser a Nume con ese JWT en la query.
  4. Nume valida el JWT, rechaza un jti ya utilizado, crea el usuario si no existe (o lo reactiva si estaba desactivado), inicia sesión y redirige a la app.

Requisitos previos

Antes de usar este flujo, Nume les entrega:

  • API host — base URL de la API de Nume (prod o testing)
  • Integration UUID — identifica la integración en la URL
  • JWT secret — clave compartida para firmar el JWT (algoritmo HS256)

Endpoint

Método GET. La empresa debe redirigir el browser del usuario a esta URL (no es una llamada server-to-server).

Producción:

GET https://api.nuevometodo.com/integrations/sso/{integrationUuid}?token={jwt}

Ruta:

GET /integrations/sso/{integrationUuid}?token={jwt}

Claims del JWT

Algoritmo HS256. El secret es el valor entregado por Nume.

Campos requeridos

CampoTipoDescripción
email o external_idstringAl menos uno de los dos. Si se envían juntos, se reutiliza la cuenta de esta integración que ya coincida con el email o con el external_id; si esa cuenta se había creado solo con external_id, se le asigna el email. Si no existe ninguna, se crea la cuenta con el email y se guarda el external_id. El acceso se rechaza si cada uno pertenece a un usuario distinto, si la cuenta del email ya tiene otro external_id, si el external_id ya está en una cuenta con otro email o si el email pertenece a otra empresa.
iatnumberUnix timestamp (segundos) de emisión. El token se rechaza si tiene más de 5 minutos de antigüedad.
jtistringIdentificador único del token. Cada JWT es de un solo uso; un jti ya utilizado se rechaza.

Campos opcionales

CampoTipoDescripción
full_namestringNombre completo del usuario
data.first_namestringNombre
data.last_namestringApellido
data.dnistringDocumento
data.date_of_birthstringFecha ISO 8601 UTC, ej. "1995-07-21T00:00:00.000Z"
data.countrystringPaís, ej. "Argentina"
data.genderstring"M" o "F"
data.dial_codestringCódigo de país, ej. "+54"
data.phone_numberstringTeléfono sin código de país
expnumberOpcional. Si se envía, Nume lo ignora.

Ejemplo de payload

Con email y datos de perfil:

{
  "email": "usuario@ejemplo.com",
  "full_name": "Juan Pérez",
  "jti": "3f1c0a8e-2b9d-4c7a-9e11-5a6b7c8d9e00",
  "iat": 1710000000,
  "data": {
    "first_name": "Juan",
    "last_name": "Pérez",
    "dni": "12345678",
    "date_of_birth": "1995-07-21T00:00:00.000Z",
    "country": "Argentina",
    "gender": "M",
    "dial_code": "+54",
    "phone_number": "1123456789"
  }
}

Mínimo con external_id:

{
  "external_id": "USR-12345-ABC",
  "jti": "7b2e91c4-0d55-4a18-8f3c-1d9a2b4c6e70",
  "iat": 1710000000
}

Ejemplo de código (Node.js)

Importante

Firmá el JWT siempre en tu backend. No expongas el secret en el frontend ni en la app.
const { randomUUID } = require('crypto');
const express = require('express');
const jwt = require('jsonwebtoken');

const app = express();

const secret = process.env.NUME_SSO_JWT_SECRET; // secreto entregado por Nume
const integrationUuid = process.env.NUME_INTEGRATION_UUID; // integration UUID entregado por Nume
const apiBaseUrl = process.env.NUME_API_BASE_URL; // host de la API de Nume

app.get('/entrar-a-nume', (req, res) => {
  const token = jwt.sign(
    {
      email: 'usuario@ejemplo.com',
      full_name: 'Juan Pérez',
      // iat lo agrega jsonwebtoken automáticamente
    },
    secret,
    { algorithm: 'HS256', jwtid: randomUUID() },
  );

  const url =
    `${apiBaseUrl}/integrations/sso/${integrationUuid}` +
    `?token=${encodeURIComponent(token)}`;

  res.redirect(url);
});

app.listen(3000);

Errores comunes

Si el acceso falla, Nume redirige al usuario a una pantalla de error genérica (código en la URL). Códigos posibles:

CódigoCausa típica
invalid_requestEl JWT no incluye email ni external_id, el UUID de la integración no es válido, o email y external_id no corresponden al mismo usuario
invalid_tokenJWT inválido, firma incorrecta, sin iat o con un jti ya utilizado
missing_jtiJWT sin el claim jti
token_expirediat con más de 5 minutos de antigüedad
forbiddenIntegración inactiva, empresa inactiva, empresa eliminada o email que pertenece a otra empresa
email_in_useEl email ya está en otra cuenta
admin_accountEl email ya está en una cuenta de administración
not_foundIntegration UUID inexistente
unexpectedError inesperado al procesar el acceso

Notas

  • Si el usuario no existe, Nume lo crea.
  • Si existía pero estaba desactivado, Nume lo reactiva al entrar por SSO.
  • Cada JWT es de un solo uso. El claim jti no puede repetirse.
  • Si el JWT trae solo external_id, Nume usa un email sintético interno basado en ese id. Si trae los dos, Nume entra a la cuenta que ya coincida con cualquiera de ellos y, si esa cuenta usaba el email sintético, le asigna el email real. El acceso se rechaza si los dos identificadores no corresponden al mismo usuario o si el email pertenece a otra empresa.
  • Cuando no es posible utilizar SSO, corresponde el flujo por API key: POST /integrations/token.

Implementación con iframe (flujo embebido / nativo)

Si preferís no sacar al usuario de tu portal (o lo mostrás dentro de una app nativa con WebView), podés apuntar un iframe / WebView al mismo endpoint de tu backend que firma el JWT y hace el redirect (por ejemplo /entrar-a-nume).

Importante

Firmá el JWT siempre en tu backend. No expongas el secret en el frontend ni en la app.

Sin el atributo allow correcto no funcionan las llamadas con los médicos (cámara, micrófono y captura de pantalla).

El iframe carga tu endpoint; ese endpoint redirige a Nume

<iframe
  title="Nume"
  src="/entrar-a-nume"
  style="width: 100%; height: 100%; border: 0;"
  allow="camera *; microphone *; autoplay *; display-capture *; clipboard-read *; clipboard-write *"
  allowfullscreen
></iframe>

Los permisos de cámara y micrófono para mostrar Nume dentro de una app están en Apps móviles.

Copyright © 2026, Nuevo Método