Identity - Auth

Documentation detaillee des endpoints d'authentification du module Identity : login, register, logout, refresh token, mot de passe oublie, confirmation email, login social, 2FA, sessions.

Identity - Auth

Tous les endpoints d'authentification utilisent le prefixe /api/v1/identity/auth.

Login

POST /api/v1/identity/auth/login

Authentifie un utilisateur avec email et mot de passe.

Tag : Authentication

Auth requise : Non

Rate limiting : Auth policy (10 req/min)

Request body

{
  "email": "user@example.com",
  "password": "MyP@ssword123",
  "deviceId": "device-abc-123"
}
ChampTypeRequisDescription
emailstringOuiAdresse email de l'utilisateur
passwordstringOuiMot de passe
deviceIdstringNonIdentifiant stable du device (max 256 chars)

Reponses

200 OK -- Authentification reussie :

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "dGhpcyBpcyB...",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "phoneNumber": null,
    "imageUrl": null,
    "roles": ["user"]
  }
}

200 OK -- 2FA requis (si active) :

{
  "requiresTwoFactor": true,
  "challengeToken": "abc123..."
}

401 Unauthorized -- Email ou mot de passe invalide.

423 Locked -- Compte temporairement verrouille apres echecs repetes. Inclut lockoutEnd.

Register

POST /api/v1/identity/auth/register

Cree un nouveau compte utilisateur et emet automatiquement des tokens d'authentification.

Tag : Authentication

Auth requise : Non

Rate limiting : Registration policy (5 req/min)

Request body

{
  "email": "newuser@example.com",
  "password": "MyP@ssword123",
  "confirmPassword": "MyP@ssword123",
  "deviceId": "device-abc-123"
}
ChampTypeRequisDescription
emailstringOuiAdresse email
passwordstringOuiMot de passe (min 8 caracteres)
confirmPasswordstringOuiConfirmation du mot de passe
deviceIdstringNonIdentifiant du device

Headers optionnels

  • Idempotency-Key : Cle d'idempotence pour eviter les doublons en cas de retry.

Reponses

201 Created -- Compte cree. Retourne AuthTokensResponse. Header Location pointe vers la ressource utilisateur.

400 Bad Request -- Erreur de validation ou politique de mot de passe non respectee.

409 Conflict -- Un compte avec cet email existe deja (message generique pour eviter l'enumeration).

Refresh Token

POST /api/v1/identity/auth/refresh

Echange un refresh token contre une nouvelle paire access/refresh token.

Tag : Authentication

Auth requise : Non

Rate limiting : Auth policy

Request body

{
  "refreshToken": "dGhpcyBpcyB...",
  "deviceId": "device-abc-123"
}

Reponses

200 OK -- Retourne AuthTokensResponse avec les nouveaux tokens.

401 Unauthorized -- Token invalide, expire, revoque ou replay detecte.

Securite

  • Token rotation : Chaque appel emet un nouveau refresh token. L'ancien est invalide immediatement.
  • Detection de replay : Si un token deja utilise est soumis, toutes les sessions de l'utilisateur sont revoquees.
  • Session binding : Si le binding IP est active et que l'IP differe, la session est revoquee.

Logout

POST /api/v1/identity/auth/logout

Revoque la session courante et invalide le refresh token.

Tag : Authentication

Auth requise : Oui (Authorization: Bearer <accessToken>)

Request body

{
  "refreshToken": "dGhpcyBpcyB..."
}

Reponses

204 No Content -- Session revoquee.

Le access token reste valide jusqu'a son expiration naturelle (15-60 minutes). Le client doit le supprimer immediatement.

Confirm Email

POST /api/v1/identity/auth/confirm-email

Confirme l'adresse email de l'utilisateur via un code OTP.

Tag : Authentication

Auth requise : Non

Rate limiting : Auth policy

Request body

{
  "email": "user@example.com",
  "code": "123456"
}

Reponses

200 OK -- Email confirme (ou deja confirme). Retourne toujours 200 pour eviter l'enumeration.

401 Unauthorized -- Code OTP invalide ou expire.

400 Bad Request -- Erreur de validation.

Resend Confirmation

POST /api/v1/identity/auth/resend-confirmation

Renvoie le code de confirmation email.

Tag : Authentication

Auth requise : Non

Rate limiting : Auth policy

Request body

{
  "email": "user@example.com"
}

Reponses

200 OK -- Toujours retourne 200 (anti-enumeration).

{
  "method": "email",
  "maskedContact": "u***@example.com",
  "expiresIn": 300
}

Social Login

POST /api/v1/identity/auth/social

Authentifie ou enregistre un utilisateur via un provider OAuth social.

Tag : Authentication

Auth requise : Non

Rate limiting : Auth policy

Request body

{
  "provider": "google",
  "token": "eyJhbGciOi...",
  "deviceId": "device-abc-123"
}
ChampTypeRequisDescription
providerstringOuiProvider : google, apple, facebook
tokenstringOuiID token du provider (pas un access token)
deviceIdstringNonIdentifiant du device

Headers optionnels

  • Idempotency-Key : Cle d'idempotence.

Reponses

200 OK -- Utilisateur existant connecte. Retourne SocialLoginResponse.

201 Created -- Nouveau compte cree via login social. Retourne SocialLoginResponse.

{
  "tokens": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresIn": 3600,
    "tokenType": "Bearer",
    "user": { ... }
  },
  "isNewAccount": true
}

401 Unauthorized -- Token social invalide ou expire.

403 Forbidden -- Email existant avec une autre methode d'auth, ou compte inactif.

Change Password

POST /api/v1/identity/auth/change-password

Change le mot de passe de l'utilisateur authentifie.

Tag : Account

Auth requise : Oui

Request body

{
  "currentPassword": "OldP@ssword123",
  "newPassword": "NewP@ssword456"
}

Reponses

204 No Content -- Mot de passe change.

401 Unauthorized -- Mot de passe actuel incorrect.

422 Unprocessable Entity -- Nouveau mot de passe non conforme ou dans l'historique recent.

Effets de bord

Toutes les sessions actives sauf la courante sont immediatement revoquees.

Forgot Password

POST /api/v1/identity/auth/forgot-password

Demande un code OTP par email pour reinitialiser le mot de passe.

Tag : Password Recovery

Auth requise : Non

Request body

{
  "email": "user@example.com"
}

Reponses

200 OK -- Toujours (anti-enumeration).

{
  "method": "email",
  "maskedContact": "u***@example.com",
  "expiresIn": 300
}

Verify OTP

POST /api/v1/identity/auth/otp/verify

Valide le code OTP et retourne un token de reinitialisation.

Tag : Password Recovery

Auth requise : Non

Request body

{
  "email": "user@example.com",
  "code": "123456"
}

Reponses

200 OK :

{
  "resetToken": "abc123...",
  "expiresIn": 600
}

Le resetToken est valide 10 minutes.

401 Unauthorized -- Code invalide ou expire.

Resend OTP

POST /api/v1/identity/auth/otp/resend

Genere un nouveau code OTP et invalide le precedent.

Tag : Password Recovery

Auth requise : Non

Request body

{
  "email": "user@example.com"
}

Reponses

200 OK -- Toujours (anti-enumeration).

{
  "method": "email",
  "maskedContact": "u***@example.com",
  "expiresIn": 300
}

Reset Password

POST /api/v1/identity/auth/reset-password

Reinitialise le mot de passe avec le token obtenu via Verify OTP.

Tag : Password Recovery

Auth requise : Non

Request body

{
  "resetToken": "abc123...",
  "newPassword": "NewP@ssword456",
  "deviceId": "device-abc-123"
}

Headers optionnels

  • Idempotency-Key : Cle d'idempotence.

Reponses

200 OK -- Mot de passe reinitialise. Retourne AuthTokensResponse (connexion automatique).

401 Unauthorized -- Token invalide, deja utilise ou expire.

422 Unprocessable Entity -- Mot de passe non conforme ou dans l'historique.

Effets de bord

Toutes les sessions existantes sont immediatement revoquees.

Login 2FA

POST /api/v1/identity/auth/login/2fa

Complete l'authentification avec un code 2FA (TOTP ou recovery code).

Tag : Two-Factor Authentication

Auth requise : Non

Request body

{
  "challengeToken": "abc123...",
  "code": "123456",
  "deviceId": "device-abc-123"
}

Reponses

200 OK -- Retourne AuthTokensResponse.

401 Unauthorized -- Code 2FA invalide, challenge expire (5 min), ou compte inactif.

TOTP Setup

POST /api/v1/identity/auth/2fa/totp/setup

Initie la configuration TOTP pour l'utilisateur authentifie.

Tag : Two-Factor Authentication

Auth requise : Oui

Reponses

200 OK :

{
  "sharedKey": "JBSWY3DPEHPK3PXP",
  "authenticatorUri": "otpauth://totp/Place%20API:user@example.com?secret=..."
}

409 Conflict -- 2FA deja active.

TOTP Verify

POST /api/v1/identity/auth/2fa/totp/verify

Complete la configuration TOTP en verifiant un code de l'application authenticator.

Tag : Two-Factor Authentication

Auth requise : Oui

Request body

{
  "code": "123456"
}

Reponses

200 OK :

{
  "recoveryCodes": [
    "ABCD-1234-EFGH",
    "IJKL-5678-MNOP",
    ...
  ]
}

Les recovery codes ne sont affiches qu'une seule fois.

400 Bad Request -- Code de verification invalide.

409 Conflict -- 2FA deja active.

TOTP Disable

POST /api/v1/identity/auth/2fa/totp/disable

Desactive la 2FA. Requiert la confirmation du mot de passe.

Tag : Two-Factor Authentication

Auth requise : Oui

Request body

{
  "password": "MyP@ssword123"
}

Reponses

204 No Content -- 2FA desactivee.

401 Unauthorized -- Mot de passe incorrect.

409 Conflict -- 2FA pas active.

Effets de bord

Toutes les sessions sont revoquees apres desactivation.

Regenerate Recovery Codes

POST /api/v1/identity/auth/2fa/recovery-codes/regenerate

Genere un nouveau jeu de codes de recuperation, invalidant les precedents.

Tag : Two-Factor Authentication

Auth requise : Oui

Request body

{
  "password": "MyP@ssword123"
}

Reponses

200 OK -- Retourne RecoveryCodesResponse.

409 Conflict -- 2FA pas active.

Sessions

Get My Sessions

GET /api/v1/identity/auth/sessions

Retourne toutes les sessions actives de l'utilisateur authentifie.

Tag : Sessions

Auth requise : Oui

Reponses

200 OK :

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deviceType": "Desktop",
    "browser": "Chrome",
    "operatingSystem": "macOS",
    "ipAddress": "192.168.*.1",
    "createdAt": "2026-01-15T10:30:00Z",
    "lastActivityAt": "2026-01-15T14:00:00Z",
    "isCurrent": true
  }
]

Les adresses IP sont partiellement masquees pour la confidentialite.

Revoke Session

DELETE /api/v1/identity/auth/sessions/{sessionId}

Revoque une session specifique de l'utilisateur.

Tag : Sessions

Auth requise : Oui

Reponse : 204 No Content

Revoke All Other Sessions

DELETE /api/v1/identity/auth/sessions

Revoque toutes les sessions sauf la courante.

Tag : Sessions

Auth requise : Oui

Reponse : 204 No Content

Push Tokens

Register Push Token

POST /api/v1/identity/users/me/push-tokens

Enregistre ou met a jour un token de notification push.

Tag : Push Tokens

Auth requise : Oui

Request body

{
  "token": "fcm-token-abc123...",
  "platform": "android",
  "deviceId": "device-abc-123"
}

Reponse : 204 No Content

Unregister Push Token

DELETE /api/v1/identity/users/me/push-tokens

Supprime un token push.

Tag : Push Tokens

Auth requise : Oui

Request body

{
  "token": "fcm-token-abc123..."
}

Reponse : 204 No Content (meme si le token n'existait pas).

Linked Accounts

Get Linked Accounts

GET /api/v1/identity/users/me/linked-accounts

Retourne le statut de liaison pour tous les providers sociaux.

Tag : Linked Accounts

Auth requise : Oui

Reponse

200 OK :

[
  {
    "provider": "google",
    "linked": true,
    "email": "user@gmail.com",
    "linkedAt": "2026-01-10T08:00:00Z"
  },
  {
    "provider": "apple",
    "linked": false,
    "email": null,
    "linkedAt": null
  },
  {
    "provider": "facebook",
    "linked": false,
    "email": null,
    "linkedAt": null
  }
]

POST /api/v1/identity/users/me/linked-accounts

Lie un provider social au compte de l'utilisateur.

Tag : Linked Accounts

Auth requise : Oui

Request body

{
  "provider": "google",
  "token": "eyJhbGciOi..."
}

201 Created -- Provider lie.

409 Conflict -- Provider deja lie, ou compte social deja lie a un autre utilisateur.

DELETE /api/v1/identity/users/me/linked-accounts/{provider}

Supprime la liaison avec un provider social.

Tag : Linked Accounts

Auth requise : Oui

204 No Content -- Provider delie.

404 Not Found -- Provider non lie.

409 Conflict -- Impossible de supprimer la derniere methode d'authentification.

Security Settings

Get Security Settings

GET /api/v1/identity/users/me/security

Retourne les parametres de securite de l'utilisateur.

Tag : Security Settings

Auth requise : Oui

Reponse

{
  "twoFactorEnabled": false,
  "loginNotificationsEnabled": true,
  "sessionAlertEnabled": false
}

Update Security Settings

PATCH /api/v1/identity/users/me/security

Met a jour les parametres de securite (semantique PATCH : seuls les champs fournis sont modifies).

Tag : Security Settings

Auth requise : Oui

Request body

{
  "loginNotificationsEnabled": true,
  "sessionAlertEnabled": true
}

Reponse : 204 No Content

JWKS

Get JSON Web Key Set

GET /.well-known/jwks.json

Retourne les cles publiques utilisees pour verifier les JWT emis par le serveur (format RFC 7517).

Tag : Authentication

Auth requise : Non

Cache : Reponse cacheable (1 heure).

© 2026 Place API