Sessions API

Gestion des sessions utilisateur a travers les appareils et les profils, avec monitoring de securite et controle des sessions.

Base URL : /api/v2/sessions

Endpoints

Methode	Endpoint	Description	Auth
GET	/sessions	Lister les sessions du compte	Oui
GET	/sessions/profile	Sessions du profil courant	Oui
GET	/sessions/current	Session courante	Oui
GET	/sessions/:id	Details d'une session	Oui
DELETE	/sessions/:id	Revoquer une session	Oui
DELETE	/sessions/profile/all	Revoquer toutes les sessions du profil	Oui
DELETE	/sessions	Revoquer toutes les sessions du compte	Oui
POST	/sessions/current/heartbeat	Mettre a jour l'activite	Oui
POST	/sessions/:id/challenge	Challenger une session (haute securite)	Oui

---

GET /sessions

Lister toutes les sessions actives du compte.

GET /api/v2/sessions?status=ACTIVE&limit=20
Authorization: Bearer <access_token>

Reponse 200 OK

{
  "data": [
    {
      "id": "session-uuid-1",
      "profileId": "profile-uuid",
      "profileName": "John",
      "deviceId": "device-uuid",
      "deviceName": "iPhone 15 Pro",
      "deviceType": "MOBILE_IOS",
      "ipAddress": "192.168.1.100",
      "location": {
        "city": "Paris",
        "country": "France"
      },
      "status": "ACTIVE",
      "createdAt": "2025-01-15T08:00:00Z",
      "lastActivityAt": "2025-01-15T10:30:00Z",
      "expiresAt": "2025-01-22T08:00:00Z",
      "isCurrent": true
    }
  ],
  "meta": {
    "total": 2,
    "maxConcurrent": 4,
    "activeSessions": 2
  }
}

---

GET /sessions/current

Details de la session courante.

GET /api/v2/sessions/current
Authorization: Bearer <access_token>

Reponse 200 OK

{
  "id": "current-session-uuid",
  "accountId": "account-uuid",
  "profileId": "profile-uuid",
  "deviceId": "device-uuid",
  "deviceName": "iPhone 15 Pro",
  "deviceType": "MOBILE_IOS",
  "ipAddress": "192.168.1.100",
  "userAgent": "MyTV/2.1.0 (iOS 17.2; iPhone15,2)",
  "location": {
    "city": "Paris",
    "region": "Ile-de-France",
    "country": "France",
    "countryCode": "FR"
  },
  "status": "ACTIVE",
  "createdAt": "2025-01-15T08:00:00Z",
  "lastActivityAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-22T08:00:00Z",
  "tokenRefreshCount": 3
}

---

DELETE /sessions/:id

Revoquer une session specifique.

DELETE /api/v2/sessions/:id
Authorization: Bearer <access_token>

Reponse 200 OK

{
  "message": "Session revoked successfully",
  "sessionId": "session-uuid"
}

attention

La session courante ne peut pas etre revoquee. Utilisez la deconnexion a la place.

---

DELETE /sessions

Revoquer toutes les sessions du compte (sauf la session courante).

DELETE /api/v2/sessions
Authorization: Bearer <access_token>

Reponse 200 OK

{
  "message": "All other account sessions revoked",
  "revokedCount": 5
}

---

POST /sessions/current/heartbeat

Mettre a jour le timestamp d'activite de la session.

POST /api/v2/sessions/current/heartbeat
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "currentContentId": "movie-uuid",
  "contentType": "MOVIE",
  "playbackPosition": 1845
}

Reponse 200 OK

{
  "lastActivityAt": "2025-01-15T10:35:00Z",
  "sessionValid": true
}

Statuts de session

Statut	Description
ACTIVE	Session valide et active
EXPIRED	Session expiree naturellement
REVOKED	Session revoquee manuellement
CHALLENGED	Re-authentification requise

Limites de sessions concurrentes

Les sessions sont limitees par compte selon l'abonnement :

Plan	Sessions concurrentes max
Free	1
Basic	2
Premium	4
Ultimate	6

Lorsque la limite est depassee, la session la plus ancienne est automatiquement revoquee.

Cycle de vie d'une session

[Login/Select Profile] --> ACTIVE
ACTIVE --> ACTIVE (Heartbeat / Token Refresh)
ACTIVE --> EXPIRED (TTL depasse)
ACTIVE --> REVOKED (Revocation manuelle)
ACTIVE --> CHALLENGED (Activite suspecte)
CHALLENGED --> ACTIVE (Re-authentification reussie)
CHALLENGED --> REVOKED (Timeout)

Detection de session suspecte

Lorsqu'une activite suspecte est detectee :

{
  "alert": "SUSPICIOUS_SESSION",
  "session": {
    "id": "session-uuid",
    "location": "Unknown City, Russia",
    "riskScore": 85
  },
  "recommendedAction": "REVOKE"
}

Donnees de localisation

La localisation de la session est derivee de l'adresse IP :

{
  "location": {
    "city": "Paris",
    "region": "Ile-de-France",
    "country": "France",
    "countryCode": "FR",
    "latitude": 48.8566,
    "longitude": 2.3522,
    "accuracy": "city"
  }
}

Vie privee

Les coordonnees precises ne sont stockees que si l'utilisateur a donne son consentement.

Exemple d'integration

React Native -- Moniteur de session

import { useEffect } from 'react';
import { api } from './api';

export function useSessionMonitor() {
  useEffect(() => {
    const interval = setInterval(
      async () => {
        try {
          await api.post('/sessions/current/heartbeat');
        } catch (error) {
          if (error.response?.status === 401) {
            // Session revoquee, deconnecter l'utilisateur
            logout();
          }
        }
      },
      5 * 60 * 1000,
    ); // toutes les 5 minutes

    return () => clearInterval(interval);
  }, []);
}

Codes d'erreur

Code	HTTP	Description
SESSION_001	404	Session introuvable
SESSION_002	403	Impossible de revoquer la session courante
SESSION_003	403	Session appartenant a un autre compte
SESSION_004	401	Session revoquee
SESSION_005	401	Session expiree
SESSION_006	403	Re-authentification requise