Documentation API — Module Auth¶

Préfixe : /api/auth | 35 routes | Mixte (public + protégé)

Table des matières¶

Authentification de base
2FA — Double authentification
Mots de passe
Sessions
Tokens
Profil & Paramètres
Sécurité & Administration

Authentification de base¶

POST /api/auth/connexion¶

Description : Connexion d'un utilisateur avec email et mot de passe
Permission : PUBLIC
Authentification : Publique
Rate limit : preset auth

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`email`	string	Oui	body	Email de l'utilisateur
`motDePasse`	string	Oui	body	Mot de passe

Réponse succès (HTTP 200)

{
  "succes": true,
  "message": "Connexion réussie",
  "donnees": {
    "accessToken": "jwt_access_token",
    "refreshToken": "jwt_refresh_token",
    "utilisateur": {
      "id": "cuid",
      "email": "user@example.com",
      "nom": "Nom",
      "prenom": "Prénom",
      "role": { "code": "AGENT", "niveau": 3 }
    }
  }
}

Codes d'erreur

Code	HTTP	Signification
`DONNEES_INVALIDES`	400	Email ou mot de passe manquant/invalide
`IDENTIFIANTS_INVALIDES`	401	Email ou mot de passe incorrect
`COMPTE_BLOQUE`	423	Compte verrouillé (trop de tentatives)
`EMAIL_NON_VERIFIE`	403	Email non vérifié
`ERREUR_SERVEUR`	500	Erreur technique

Use Case associé : ConnexionUseCase.ts
Cas d'usage métier : Un agent ou administrateur ESM se connecte à l'application.

POST /api/auth/register¶

Description : Inscription d'un nouvel utilisateur
Permission : PUBLIC
Authentification : Publique
Rate limit : preset register

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`email`	string	Oui	body	Email unique
`motDePasse`	string	Oui	body	Mot de passe (min 8 car.)
`nom`	string	Oui	body	Nom de famille
`prenom`	string	Oui	body	Prénom
`profilId`	string	Oui	body	CUID du profil utilisateur
`communeCode`	string	Non	body	Code commune d'affectation

Réponse succès (HTTP 201)

{
  "succes": true,
  "message": "Compte créé. Vérifiez votre email.",
  "donnees": { "idUtilisateur": "cuid" }
}

Codes d'erreur

Code	HTTP	Signification
`DONNEES_INVALIDES`	400	Champs manquants ou invalides
`EMAIL_DEJA_UTILISE`	409	Email déjà enregistré
`ERREUR_SERVEUR`	500	Erreur technique

Use Case associé : InscrireUtilisateurUseCase.ts
Cas d'usage métier : Création d'un nouveau compte agent ou administrateur.

POST /api/auth/refresh¶

Description : Rafraîchir le token d'accès avec un refresh token
Permission : PUBLIC
Authentification : Publique

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`refreshToken`	string	Oui	body	JWT refresh token valide

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "accessToken": "nouveau_jwt_access_token",
    "refreshToken": "nouveau_refresh_token"
  }
}

Codes d'erreur

Code	HTTP	Signification
`TOKEN_INVALIDE`	401	Refresh token invalide ou expiré
`TOKEN_REVOQUE`	401	Refresh token révoqué
`ERREUR_SERVEUR`	500	Erreur technique

Use Case associé : RefreshTokenUseCase.ts

POST /api/auth/verify-email¶

Description : Vérifier l'email avec un code reçu par email
Permission : PUBLIC
Authentification : Publique

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`code`	string	Oui	body	Code de vérification (6 chiffres)
`email`	string	Oui	body	Email à vérifier

Réponse succès (HTTP 200)

{ "succes": true, "message": "Email vérifié avec succès" }

Use Case associé : VerifierEmailUseCase.ts

POST /api/auth/logout¶

Description : Déconnexion de l'utilisateur (révocation de la session courante)
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`sessionId`	string	Non	body	ID de session spécifique (optionnel)

Réponse succès (HTTP 200)

{ "succes": true, "message": "Déconnexion réussie" }

Use Case associé : DeconnexionUseCase.ts

POST /api/auth/verify-email-change¶

Description : Valider le changement d'email avec le code envoyé au nouvel email
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`code`	string	Oui	body	Code de vérification reçu
`nouvelEmail`	string	Oui	body	Nouvel email à confirmer

Use Case associé : VerifierNouvelEmailUseCase.ts

POST /api/auth/change-email¶

Description : Demander un changement d'email (envoie un code au nouvel email)
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`nouvelEmail`	string	Oui	body	Nouvel email souhaité
`motDePasse`	string	Oui	body	Confirmation par mot de passe actuel

Use Case associé : ChangerEmailUseCase.ts

2FA — Double authentification¶

POST /api/auth/2fa/generate-secret¶

Description : Générer un secret TOTP et un QR code pour configurer l'app 2FA
Permission : AUTH requise
Authentification : Requise

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "secret": "BASE32SECRET",
    "qrCode": "data:image/png;base64,...",
    "otpAuthUrl": "otpauth://totp/ESM:user@email.com?secret=..."
  }
}

Use Case associé : Generer2FASecretUseCase.ts

POST /api/auth/2fa/activate¶

Description : Activer le 2FA en vérifiant le premier code TOTP
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`code`	string	Oui	body	Code TOTP de l'app authenticator
`secret`	string	Oui	body	Secret généré à l'étape précédente

Use Case associé : Activer2FAUseCase.ts

POST /api/auth/2fa/verify¶

Description : Vérifier un code 2FA lors de la connexion
Permission : PUBLIC
Authentification : Publique
Rate limit : preset twoFactor

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`code`	string	Oui	body	Code TOTP 6 chiffres
`tempToken`	string	Oui	body	Token temporaire obtenu après connexion partielle

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "accessToken": "jwt_access_token",
    "refreshToken": "jwt_refresh_token"
  }
}

Use Case associé : Verifier2FAUseCase.ts
Cas d'usage métier : Deuxième étape du flow de connexion pour les comptes 2FA activé.

POST /api/auth/2fa/deactivate¶

Description : Désactiver le 2FA (confirmation par code TOTP)
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`code`	string	Oui	body	Code TOTP actuel pour confirmer

Use Case associé : Desactiver2FAUseCase.ts

POST /api/auth/2fa/backup-codes/generate¶

Description : Générer des codes de récupération (backup codes) pour le 2FA
Permission : AUTH requise
Authentification : Requise

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "codes": ["CODE1", "CODE2", "CODE3", "CODE4", "CODE5",
              "CODE6", "CODE7", "CODE8", "CODE9", "CODE10"]
  }
}

Use Case associé : GenererBackupCodesUseCase.ts
Note : À afficher UNE SEULE FOIS — les codes sont hashés en base.

POST /api/auth/2fa/backup-codes/verify¶

Description : Vérifier un code de récupération (alternative au TOTP)
Permission : PUBLIC
Authentification : Publique
Rate limit : preset twoFactor

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`code`	string	Oui	body	Code de récupération (format XXXX-XXXX)
`tempToken`	string	Oui	body	Token temporaire post-connexion

Use Case associé : VerifierBackupCodeUseCase.ts

POST /api/auth/2fa/backup-codes/revoke¶

Description : Révoquer tous les codes de récupération existants
Permission : AUTH requise
Authentification : Requise

Use Case associé : RevoquerCodesRecuperationUseCase.ts

Mots de passe¶

PUT /api/auth/change-password¶

Description : Changer le mot de passe (utilisateur connecté)
Permission : AUTH requise
Authentification : Requise
Rate limit : preset auth

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`motDePasseActuel`	string	Oui	body	Mot de passe actuel
`nouveauMotDePasse`	string	Oui	body	Nouveau mot de passe
`confirmation`	string	Oui	body	Confirmation du nouveau mot de passe

Use Case associé : ChangerMotDePasseUseCase.ts

POST /api/auth/reset-password/request¶

Description : Demander une réinitialisation de mot de passe par email
Permission : PUBLIC
Authentification : Publique
Rate limit : preset passwordReset

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`email`	string	Oui	body	Email du compte

Réponse succès (HTTP 200)

{ "succes": true, "message": "Email de réinitialisation envoyé si le compte existe" }

Use Case associé : DemanderResetPasswordUseCase.ts

POST /api/auth/reset-password/verify¶

Description : Vérifier la validité d'un token de reset
Permission : PUBLIC
Authentification : Publique

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`token`	string	Oui	body	Token de réinitialisation reçu par email

Use Case associé : VerifierTokenResetUseCase.ts

POST /api/auth/reset-password/confirm¶

Description : Confirmer et effectuer la réinitialisation du mot de passe
Permission : PUBLIC
Authentification : Publique
Rate limit : preset passwordReset

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`token`	string	Oui	body	Token de réinitialisation
`nouveauMotDePasse`	string	Oui	body	Nouveau mot de passe
`confirmation`	string	Oui	body	Confirmation

Use Case associé : ResetPasswordUseCase.ts

Sessions¶

GET /api/auth/sessions¶

Description : Lister toutes les sessions actives de l'utilisateur connecté
Permission : AUTH requise
Authentification : Requise

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "sessions": [
      {
        "id": "cuid",
        "ipAddress": "192.168.1.1",
        "userAgent": "Mozilla/5.0...",
        "createdAt": "2026-06-17T00:00:00Z",
        "lastActivity": "2026-06-17T00:00:00Z",
        "isCurrent": true
      }
    ]
  }
}

Use Case associé : ListerSessionsActivesUseCase.ts

GET /api/auth/sessions/events¶

Description : Obtenir l'historique des événements de session
Permission : AUTH requise
Authentification : Requise

Paramètres query

Champ	Type	Obligatoire	Description
`page`	number	Non	Numéro de page
`limite`	number	Non	Nombre par page

Use Case associé : ObtenirHistoriqueUseCase.ts

DELETE /api/auth/sessions/:idSession¶

Description : Révoquer une session spécifique
Permission : AUTH requise
Authentification : Requise

Paramètres URL

Champ	Type	Obligatoire	Description
`idSession`	string (CUID)	Oui	ID de la session à révoquer

Use Case associé : RevoquerSessionUseCase.ts

POST /api/auth/sessions/revoke-all¶

Description : Révoquer toutes les sessions (déconnexion tous appareils)
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Description
`garderSessionActuelle`	boolean	Non	Garder la session courante (défaut: false)

Use Case associé : RevoquerToutesSessionsUseCase.ts

Tokens¶

POST /api/auth/tokens/validate¶

Description : Valider un access token (utile pour les services internes)
Permission : PUBLIC
Authentification : Publique

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`token`	string	Oui	body	JWT access token à valider

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "valide": true,
    "payload": { "idUtilisateur": "cuid", "email": "...", "role": {...} }
  }
}

Use Case associé : ValiderAccessTokenUseCase.ts

POST /api/auth/tokens/revoke¶

Description : Révoquer un token spécifique
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`token`	string	Oui	body	Token à révoquer

Use Case associé : RevoquerTokenUseCase.ts

POST /api/auth/tokens/revoke-all¶

Description : Révoquer tous les tokens de l'utilisateur connecté
Permission : AUTH requise
Authentification : Requise

Use Case associé : RevoquerTousTokensUseCase.ts

Profil & Paramètres¶

GET /api/auth/profile¶

Description : Obtenir le profil complet de l'utilisateur connecté
Permission : AUTH requise
Authentification : Requise

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "id": "cuid",
    "email": "user@example.com",
    "nom": "Nom",
    "prenom": "Prénom",
    "emailVerifie": true,
    "deuxFacteursActive": false,
    "profil": { "code": "AGENT", "libelle": "Agent de terrain" },
    "commune": { "code": "COT", "nom": "Cotonou" },
    "createdAt": "2026-01-01T00:00:00Z"
  }
}

Use Case associé : ObtenirProfilUseCase.ts

PUT /api/auth/profile¶

Description : Modifier le profil de l'utilisateur connecté
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`nom`	string	Non	body	Nouveau nom
`prenom`	string	Non	body	Nouveau prénom
`emailNotifications`	boolean	Non	body	Activer les notifications email

Use Case associé : ModifierProfilUseCase.ts

GET /api/auth/parametres/:idUtilisateur¶

Description : Obtenir les paramètres de sécurité d'un utilisateur
Permission : AUTH requise
Authentification : Requise

Paramètres URL

Champ	Type	Obligatoire	Description
`idUtilisateur`	string (CUID)	Oui	ID de l'utilisateur

Use Case associé : ObtenirParametresUseCase.ts

DELETE /api/auth/delete-account¶

Description : Supprimer définitivement le compte utilisateur
Permission : AUTH requise
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`motDePasse`	string	Oui	body	Confirmation par mot de passe
`confirmation`	string	Oui	body	Texte "SUPPRIMER" pour confirmer

Use Case associé : SupprimerCompteUseCase.ts

GET /api/auth/history¶

Description : Obtenir l'historique d'activité de l'utilisateur
Permission : AUTH requise
Authentification : Requise

Paramètres query

Champ	Type	Description
`page`	number	Numéro de page
`limite`	number	Nombre par page

Use Case associé : ObtenirHistoriqueUseCase.ts

Sécurité & Administration¶

Ces routes nécessitent un niveau de rôle ≤ 2 (administrateurs).

POST /api/auth/security/block-ip¶

Description : Bloquer une adresse IP (blacklist Redis)
Permission : AUTH requise + niveau rôle ≤ 2
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`ipAddress`	string	Oui	body	Adresse IP à bloquer (IPv4 ou IPv6)
`raison`	string	Non	body	Raison du blocage
`dureeMinutes`	number	Non	body	Durée du blocage (0 = permanent)

Use Case associé : BloquerIPUseCase.ts

POST /api/auth/security/unblock-ip¶

Description : Débloquer une adresse IP
Permission : AUTH requise + niveau rôle ≤ 2
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Source	Description
`ipAddress`	string	Oui	body	Adresse IP à débloquer

Use Case associé : DebloquerIPUseCase.ts

GET /api/auth/security/logs¶

Description : Obtenir les logs de sécurité (connexions, blocages, tentatives)
Permission : AUTH requise + niveau rôle ≤ 2
Authentification : Requise

Paramètres query

Champ	Type	Description
`page`	number	Numéro de page
`limite`	number	Nombre par page
`ipAddress`	string	Filtrer par IP
`dateDebut`	string (ISO)	Date de début
`dateFin`	string (ISO)	Date de fin

Use Case associé : ObtenirLogsSecuriteUseCase.ts

GET /api/auth/security/suspicious-connections¶

Description : Détecter les connexions suspectes (IPs multiples, horaires inhabituels)
Permission : AUTH requise + niveau rôle ≤ 2
Authentification : Requise

Use Case associé : DetecterConnexionsSuspectesUseCase.ts