API Sessions

L’API Sessions permet de visualiser et gérer les sessions actives des utilisateurs, de consulter des statistiques agrégées et de configurer les politiques de sécurité liées aux sessions, aux tokens, aux mots de passe et au verrouillage de compte.

Tous les endpoints nécessitent le header x-tenant.

Gestion des Sessions

GET/api/sessionsRequires: manage:sessions

Liste les sessions, avec filtres optionnels. Retourne les sessions paginées avec les métadonnées de l’appareil et d’authentification.

Paramètres de query

Paramètre	Type	Description
`userId`	string	Filtre par identifiant utilisateur
`active`	boolean	`true` pour les sessions actives uniquement, `false` pour toutes
`page`	integer	Numéro de page (défaut : 1)
`limit`	integer	Éléments par page (défaut : 20)

Réponse de succès


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "ses_abc123",
        "userId": "usr_abc123",
        "userEmail": "[email protected]",
        "userName": "Alice Martin",
        "ipAddress": "192.168.1.1",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
        "device": "Desktop - Chrome 121",
        "authMethod": "password",
        "isActive": true,
        "createdAt": "2025-03-01T08:00:00Z",
        "lastActivityAt": "2025-03-01T14:30:00Z",
        "expiresAt": "2025-03-02T08:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 42 }
  }
}

Méthodes d’authentification

Valeur	Description
`password`	Email + mot de passe
`magic_link`	Magic link par email
`social`	OAuth2 social (Google, GitHub, etc.)
`sso`	SSO d’entreprise (SAML/OIDC)
`device_code`	Flow Device Code (appareils limités)
`m2m`	Machine-to-Machine (Client Credentials)

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

Obtient les détails complets d’une session spécifique, y compris les informations MFA, l’ACR et l’AMR.

Réponse de succès


{
  "ok": true,
  "data": {
    "id": "ses_abc123",
    "userId": "usr_abc123",
    "userEmail": "[email protected]",
    "ipAddress": "192.168.1.1",
    "device": "Desktop - Chrome 121",
    "authMethod": "password",
    "isActive": true,
    "mfaVerified": true,
    "mfaMethod": "totp",
    "acr": "urn:auris:loa:2",
    "amr": ["pwd", "otp"],
    "createdAt": "2025-03-01T08:00:00Z",
    "lastActivityAt": "2025-03-01T14:30:00Z",
    "expiresAt": "2025-03-02T08:00:00Z"
  }
}

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

Révoque une session spécifique. L’utilisateur sera déconnecté lors de sa prochaine tentative d’utilisation du refresh token. Les access tokens existants restent valides jusqu’à leur expiration naturelle.

La révocation de session invalide le refresh token de la session. Cependant, les access tokens émis avant la révocation restent valides jusqu’à leur expiration (par défaut 15 minutes). Pour une invalidation immédiate des access tokens, combinez la révocation de session avec la liste de révocation de tokens.

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

Révoque toutes les sessions actives d’un utilisateur. Utile pour forcer une déconnexion complète en cas de compromission de compte.

Corps de la requête


{
  "userId": "usr_abc123"
}

Réponse de succès


{
  "ok": true,
  "data": {
    "revokedCount": 3
  }
}

Statistiques des Sessions

GET/api/sessions/statsRequires: manage:sessions

Retourne des statistiques agrégées sur les sessions actives du tenant.

Réponse de succès


{
  "ok": true,
  "data": {
    "activeSessions": 1247,
    "uniqueUsers": 834,
    "last24Hours": 312,
    "byAuthMethod": {
      "password": 645,
      "magic_link": 189,
      "social": 287,
      "sso": 98,
      "device_code": 15,
      "m2m": 13
    },
    "byDevice": {
      "Desktop": 756,
      "Mobile": 412,
      "Tablet": 79
    }
  }
}

Paramètres de Sécurité

Les paramètres de sécurité contrôlent les durées de vie des sessions et tokens, les politiques de mots de passe et le comportement de verrouillage des comptes.

GET/api/settings/securityRequires: manage:security_settings

Récupère les paramètres de sécurité actuels du tenant.

Réponse de succès


{
  "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
  }
}

PUT/api/settings/securityRequires: manage:security_settings

Met à jour les paramètres de sécurité. Les modifications sont appliquées immédiatement aux nouvelles sessions.

Corps de la requête


{
  "sessionMaxLifetime": 43200,
  "sessionIdleTimeout": 1800,
  "refreshTokenExpiry": 604800,
  "accessTokenExpiry": 900,
  "maxConcurrentSessions": 3,
  "requireMfaForAdmin": true,
  "passwordMinLength": 12,
  "passwordRequireUppercase": true,
  "passwordRequireLowercase": true,
  "passwordRequireNumbers": true,
  "passwordRequireSpecial": true,
  "passwordHistoryCount": 10,
  "lockoutThreshold": 5,
  "lockoutDuration": 1800
}

Référence des Paramètres

Paramètre	Type	Défaut	Contraintes
`sessionMaxLifetime`	integer (secondes)	86400 (24h)	3600–2592000
`sessionIdleTimeout`	integer (secondes)	3600 (1h)	300–86400
`refreshTokenExpiry`	integer (secondes)	604800 (7j)	3600–2592000
`accessTokenExpiry`	integer (secondes)	900 (15min)	60–86400
`maxConcurrentSessions`	integer	5	0–100 (0 = illimité)
`requireMfaForAdmin`	boolean	true	—
`passwordMinLength`	integer	8	6–128
`passwordRequireUppercase`	boolean	true	—
`passwordRequireLowercase`	boolean	true	—
`passwordRequireNumbers`	boolean	true	—
`passwordRequireSpecial`	boolean	false	—
`passwordHistoryCount`	integer	5	0–24
`lockoutThreshold`	integer	5	1–20
`lockoutDuration`	integer (secondes)	900 (15min)	60–86400

Codes d’erreur

Code	HTTP	Description
`VALIDATION_ERROR`	400	Valeur hors limites ou type invalide

Cycle de Vie d’une Session


Création de session
       │
       ▼
   [ACTIVE] ◄──────────────────────┐
       │                            │
       │  Activité utilisateur      │ Refresh token valide
       │  (mise à jour lastActivity)│ (renouvellement access token)
       ▼                            │
   [IDLE?]  ──── sessionIdleTimeout ──► [EXPIRÉE]
       │
       │  sessionMaxLifetime dépassée
       ▼
   [EXPIRÉE]
       │
       │  Révocation manuelle (API ou Console)
       ▼
   [RÉVOQUÉE]

Pages Associées

Sessions (Concept) — Comment fonctionnent les sessions dans Auris
Guide Gestion des Sessions — Bonnes pratiques et configuration
Sessions (Console) — Visualiser et révoquer depuis la Console
API Authentification — Login, logout, refresh token