API de Sesiones

La API de Sesiones proporciona visibilidad y control sobre las sesiones de usuario en todo el tenant. Los administradores pueden listar sesiones activas, inspeccionar detalles de sesión, revocar sesiones individuales o todas las sesiones de un usuario, y configurar políticas de duración de sesión.

Una sesión se crea cuando un usuario se autentica correctamente (mediante contraseña, magic link, inicio de sesión social o SSO). Cada sesión registra el dispositivo, la dirección IP, la hora de última actividad y el método de autenticación utilizado. Las sesiones permanecen activas hasta que expiran, son revocadas por un administrador o el usuario cierra sesión.

Gestión de Sesiones

Listar Sesiones

GET/api/sessionsRequires: manage:sessions

Lista las sesiones en todo el tenant. Admite filtrado por ID de usuario y estado activo/inactivo. Devuelve metadatos de sesión incluyendo información del dispositivo, dirección IP y método de autenticación. Las sesiones se ordenan por hora de última actividad en orden descendente.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página (predeterminado: 1)
`limit`	integer	Elementos por página (predeterminado: 20, máx: 100)
`userId`	string	Filtra las sesiones de un usuario específico
`active`	boolean	`true` para sesiones activas únicamente, `false` para expiradas/revocadas únicamente

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "sess_abc123",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "userName": "Alice Smith",
        "ipAddress": "203.0.113.50",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
        "device": "Chrome on macOS",
        "authMethod": "password",
        "isActive": true,
        "createdAt": "2025-02-18T08:00:00Z",
        "lastActivityAt": "2025-02-18T09:45:00Z",
        "expiresAt": "2025-02-19T08:00:00Z"
      },
      {
        "id": "sess_def456",
        "userId": "usr_abc123",
        "userEmail": "[email protected]",
        "userName": "Bob Jones",
        "ipAddress": "198.51.100.42",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_3 like Mac OS X) AppleWebKit/605.1.15",
        "device": "Safari on iOS",
        "authMethod": "magic_link",
        "isActive": true,
        "createdAt": "2025-02-18T07:30:00Z",
        "lastActivityAt": "2025-02-18T09:30:00Z",
        "expiresAt": "2025-02-19T07:30:00Z"
      },
      {
        "id": "sess_ghi789",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "userName": "Alice Smith",
        "ipAddress": "203.0.113.51",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "device": "Edge on Windows",
        "authMethod": "sso",
        "isActive": false,
        "revokedAt": "2025-02-17T16:00:00Z",
        "revokedBy": "usr_admin001",
        "createdAt": "2025-02-17T08:00:00Z",
        "lastActivityAt": "2025-02-17T15:55:00Z",
        "expiresAt": "2025-02-18T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

Métodos de autenticación: password, magic_link, social, sso, device_code, m2m.

Obtener Sesión

GET/api/sessions/[id]Requires: manage:sessions

Recupera información detallada sobre una sesión específica, incluyendo la cadena completa del agente de usuario, el contexto de autenticación y los detalles de revocación si la sesión ha sido revocada.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "sess_abc123",
    "userId": "usr_xyz789",
    "userEmail": "[email protected]",
    "userName": "Alice Smith",
    "ipAddress": "203.0.113.50",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
    "device": "Chrome on macOS",
    "authMethod": "password",
    "isActive": true,
    "mfaVerified": true,
    "mfaMethod": "totp",
    "acr": "urn:auris:mfa",
    "amr": ["pwd", "otp"],
    "createdAt": "2025-02-18T08:00:00Z",
    "lastActivityAt": "2025-02-18T09:45:00Z",
    "expiresAt": "2025-02-19T08:00:00Z"
  }
}

Campo	Descripción
`mfaVerified`	Indica si se completó la verificación en 2 pasos para esta sesión
`mfaMethod`	El método de 2FA utilizado (`totp`, `sms`, `webauthn` o `null`)
`acr`	Authentication Context Class Reference (claim de OIDC)
`amr`	Array de Authentication Methods Reference (claim de OIDC)

Códigos de error

Código	HTTP	Descripción
`NOT_FOUND`	404	La sesión no existe o pertenece a un tenant diferente

Revocar Sesión

DELETE/api/sessions/[id]Requires: manage:sessions

Revoca una sesión específica. El refresh token asociado se invalida inmediatamente. El access token continúa siendo válido hasta que expire de forma natural (los JWT son stateless). Para un bloqueo inmediato, combina la revocación de sesión con tiempos de vida cortos del access token.

Los access tokens son JWT y no pueden revocarse individualmente sin una lista de bloqueo. Auris se basa en tiempos de vida cortos del access token (15 minutos por defecto) para mayor seguridad. Cuando se revoca una sesión, el refresh token se invalida, por lo que el usuario no puede obtener un nuevo access token una vez que el actual expire.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "revoked": true,
    "sessionId": "sess_abc123"
  }
}

Códigos de error

Código	HTTP	Descripción
`NOT_FOUND`	404	La sesión no existe
`ALREADY_REVOKED`	400	La sesión ya ha sido revocada

Revocar Todas las Sesiones del Usuario

POST/api/sessions/revoke-allRequires: manage:sessions

Revoca todas las sesiones activas de un usuario específico. Esto es útil cuando una cuenta puede estar comprometida o cuando un administrador necesita forzar al usuario a volver a autenticarse en todos los dispositivos. Todos los refresh tokens asociados se invalidan inmediatamente.

Cuerpo de la solicitud


{
  "userId": "usr_xyz789"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "revoked": true,
    "sessionsRevoked": 3,
    "userId": "usr_xyz789"
  }
}

El campo sessionsRevoked indica cuántas sesiones activas fueron terminadas.

Códigos de error

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Falta el campo `userId`
`NOT_FOUND`	404	El usuario no existe en este tenant
`NO_ACTIVE_SESSIONS`	400	El usuario no tiene sesiones activas para revocar

Revocar todas las sesiones cierra la sesión del usuario en todos sus dispositivos y navegadores. Deberá volver a autenticarse en cada uno de ellos. Considera notificar al usuario por correo electrónico al realizar esta acción.

Estadísticas de Sesión

GET/api/sessions/statsRequires: manage:sessions

Obtiene estadísticas agregadas de sesiones para el tenant. Útil para monitorear usuarios activos e identificar tendencias.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "activeSessions": 156,
    "uniqueUsers": 89,
    "last24Hours": {
      "newSessions": 42,
      "expiredSessions": 31,
      "revokedSessions": 3
    },
    "byAuthMethod": {
      "password": 98,
      "magic_link": 23,
      "social": 25,
      "sso": 10
    },
    "byDevice": {
      "desktop": 87,
      "mobile": 52,
      "tablet": 12,
      "unknown": 5
    }
  }
}

Políticas de Sesión

Las políticas de sesión controlan la duración de sesiones y tokens en todo el tenant. Estas configuraciones se aplican a todos los usuarios salvo que sean reemplazadas por configuración específica de la aplicación.

Obtener Configuración de Seguridad

GET/api/settings/securityRequires: manage:security_settings

Recupera la configuración actual de políticas de sesión y seguridad del tenant.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "sessionMaxLifetime": 86400,
    "sessionIdleTimeout": 3600,
    "refreshTokenExpiry": 604800,
    "accessTokenExpiry": 900,
    "maxConcurrentSessions": 5,
    "requireMfaForAdmin": true,
    "passwordMinLength": 8,
    "passwordRequireUppercase": true,
    "passwordRequireLowercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecial": false,
    "passwordHistoryCount": 5,
    "lockoutThreshold": 5,
    "lockoutDuration": 900,
    "updatedAt": "2025-02-10T14:00:00Z"
  }
}

Configuración de sesión y tokens

Campo	Tipo	Predeterminado	Descripción
`sessionMaxLifetime`	integer	`86400` (24h)	Duración máxima de la sesión en segundos, independientemente de la actividad
`sessionIdleTimeout`	integer	`3600` (1h)	La sesión expira después de este número de segundos de inactividad
`refreshTokenExpiry`	integer	`604800` (7d)	Tiempo de vida del refresh token en segundos
`accessTokenExpiry`	integer	`900` (15m)	Tiempo de vida del access token en segundos
`maxConcurrentSessions`	integer	`5`	Número máximo de sesiones activas por usuario (0 = ilimitado)

Configuración de MFA

Campo	Tipo	Predeterminado	Descripción
`requireMfaForAdmin`	boolean	`true`	Requiere 2FA para usuarios con roles de administrador

Configuración de política de contraseñas

Campo	Tipo	Predeterminado	Descripción
`passwordMinLength`	integer	`8`	Longitud mínima de la contraseña
`passwordRequireUppercase`	boolean	`true`	Requiere al menos una letra mayúscula
`passwordRequireLowercase`	boolean	`true`	Requiere al menos una letra minúscula
`passwordRequireNumbers`	boolean	`true`	Requiere al menos un dígito
`passwordRequireSpecial`	boolean	`false`	Requiere al menos un carácter especial
`passwordHistoryCount`	integer	`5`	Número de contraseñas anteriores a comprobar (0 = desactivado)

Configuración de bloqueo

Campo	Tipo	Predeterminado	Descripción
`lockoutThreshold`	integer	`5`	Número de intentos fallidos de inicio de sesión antes del bloqueo
`lockoutDuration`	integer	`900` (15m)	Duración del bloqueo en segundos

Actualizar Configuración de Seguridad

PUT/api/settings/securityRequires: manage:security_settings

Actualiza la configuración de políticas de sesión y seguridad. Todos los campos son opcionales — solo se actualizan los campos proporcionados. Los cambios tienen efecto inmediato para las nuevas sesiones. Las sesiones existentes no se ven afectadas retroactivamente (continúan con sus tiempos de expiración originales).

Cuerpo de la solicitud


{
  "sessionMaxLifetime": 43200,
  "accessTokenExpiry": 600,
  "maxConcurrentSessions": 3,
  "requireMfaForAdmin": true,
  "passwordMinLength": 12,
  "lockoutThreshold": 3,
  "lockoutDuration": 1800
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "sessionMaxLifetime": 43200,
    "sessionIdleTimeout": 3600,
    "refreshTokenExpiry": 604800,
    "accessTokenExpiry": 600,
    "maxConcurrentSessions": 3,
    "requireMfaForAdmin": true,
    "passwordMinLength": 12,
    "passwordRequireUppercase": true,
    "passwordRequireLowercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecial": false,
    "passwordHistoryCount": 5,
    "lockoutThreshold": 3,
    "lockoutDuration": 1800,
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Valor inválido (p. ej., número negativo, `accessTokenExpiry` > `sessionMaxLifetime`)

Reglas de validación

accessTokenExpiry debe estar entre 60 (1 minuto) y 86400 (24 horas)
refreshTokenExpiry debe estar entre 3600 (1 hora) y 2592000 (30 días)
sessionMaxLifetime debe ser >= accessTokenExpiry
sessionIdleTimeout debe ser <= sessionMaxLifetime
maxConcurrentSessions debe estar entre 0 y 100
passwordMinLength debe estar entre 6 y 128
lockoutThreshold debe estar entre 1 y 100
lockoutDuration debe estar entre 60 (1 minuto) y 86400 (24 horas)

Establecer tiempos de vida muy cortos para el access token (menos de 5 minutos) aumenta la frecuencia de solicitudes de renovación del token. Establecer tiempos de vida muy largos reduce la seguridad. El rango recomendado es de 5 a 30 minutos.

Gestión de Sesiones Concurrentes

Cuando maxConcurrentSessions se establece en un valor distinto de cero, Auris aplica un límite en el número de sesiones activas por usuario. Cuando se crea una nueva sesión y el usuario ya tiene el número máximo de sesiones:

La sesión más antigua (por createdAt) se revoca automáticamente.
La nueva sesión se crea con normalidad.
El usuario recibe una notificación de que se ha terminado una sesión anterior (si las notificaciones en la aplicación están activadas).

Este comportamiento garantiza que los usuarios nunca sean bloqueados al iniciar sesión por culpa de sesiones inactivas, mientras se mantiene un límite razonable de acceso concurrente.

Ciclo de Vida de la Sesión


El usuario se autentica
       |
       v
  Sesión creada (isActive: true)
       |
       +--- El usuario realiza solicitudes a la API ---> lastActivityAt se actualiza
       |
       +--- El access token expira ---> El usuario renueva el token
       |         (el refreshToken sigue siendo válido)
       |
       +--- Se alcanza el timeout de inactividad ---> Sesión expirada
       |
       +--- Se alcanza la duración máxima ---> Sesión expirada
       |
       +--- El administrador revoca la sesión ---> Sesión revocada
       |
       +--- El usuario cierra sesión ---> Sesión revocada
       |
       v
  Sesión inactiva (isActive: false)

Referencia de Permisos

Permiso	Descripción
`manage:sessions`	Listar, inspeccionar y revocar sesiones en todo el tenant
`manage:security_settings`	Ver y actualizar políticas de sesión y configuración de seguridad

Los usuarios individuales pueden ver y revocar sus propias sesiones a través de los endpoints de perfil de usuario (GET /api/user/sessions, DELETE /api/user/sessions/[id]) sin necesidad de permisos de administrador. Los endpoints documentados en esta página son para la administración a nivel de tenant.

Relacionado

Sesiones y Rotación de Tokens — Cómo funcionan juntos las sesiones, los tokens y la rotación
Guía de Gestión de Sesiones — Configura políticas de sesión y su aplicación
Gestión de Sesiones — Monitorea y revoca sesiones desde la Consola
API de Autenticación — Endpoints de inicio de sesión y tokens que crean sesiones