# Documentation de l'API d'Authentification

Ce document décrit les points d'accès (endpoints) de l'API REST que le frontend utilisera pour communiquer avec le backend PHP.

**URL de base de l'API :** `https://votresite.com/api/auth`

## 1. Inscription

- **Endpoint :** `POST /register`
- **Description :** Crée un nouveau compte utilisateur.
- **Corps de la requête (Request Body) :**
    ```
    {
      "username": "nouvel_utilisateur",
      "email": "utilisateur@email.com",
      "password": "un_mot_de_passe_solide"
    }
    ```
- **Réponses (Responses) :**
    - `201 Created` : L'utilisateur a été créé avec succès. Un email de confirmation a été envoyé.
        ```
        {
          "message": "Compte créé. Veuillez vérifier votre email pour l'activer."
        }
        ```
    - `400 Bad Request` : Données invalides (ex: email au mauvais format).
    - `409 Conflict` : Le nom d'utilisateur ou l'email existe déjà.

## 2. Activation du compte

- **Endpoint :** `GET /verify-email?token={token}`
- **Description :** Active le compte de l'utilisateur après qu'il a cliqué sur le lien dans l'email.
- **Paramètres (Query Parameters) :**
    - `token` : Le token de vérification reçu par email.
- **Réponses :**
    - `200 OK` : Compte activé. L'utilisateur est redirigé vers la page de connexion.
    - `400 Bad Request` : Token invalide ou expiré.

## 3. Connexion

- **Endpoint :** `POST /login`
- **Description :** Connecte l'utilisateur.
- **Corps de la requête :**
    ```
    {
      "username": "mon_utilisateur",
      "password": "mon_mot_de_passe"
    }
    ```
- **Réponses :**
    - `200 OK` : Connexion réussie (si 2FA est désactivé). La session est créée.
    - `202 Accepted` : Identifiants corrects, mais une vérification 2FA est nécessaire.
        ```
        {
          "message": "Vérification 2FA requise."
        }
        ```
    - `401 Unauthorized` : Identifiants incorrects ou compte inactif.

## 4. Vérification 2FA

- **Endpoint :** `POST /login/2fa`
- **Description :** Valide le code 2FA après une première étape de connexion réussie. Doit être appelé dans la même session.
- **Corps de la requête :**
    ```
    {
      "code": "123456"
    }
    ```
- **Réponses :**
    - `200 OK` : Code valide. Connexion complète. La session est élevée à un statut "pleinement authentifié".
    - `401 Unauthorized` : Code invalide.

## 5. Déconnexion

- **Endpoint :** `POST /logout`
- **Description :** Met fin à la session de l'utilisateur.
- **Réponses :**
    - `200 OK` : Déconnexion réussie.

## 6. Mot de passe oublié

- **Endpoint :** `POST /password/forgot`
- **Description :** Déclenche l'envoi d'un email de réinitialisation de mot de passe.
- **Corps de la requête :**
    ```
    {
      "email": "utilisateur@email.com"
    }
    ```
- **Réponses :**
    - `200 OK` : Si un compte existe pour cet email, un lien a été envoyé. (La réponse est toujours la même pour ne pas révéler si un email existe).

## 7. Réinitialisation du mot de passe

- **Endpoint :** `POST /password/reset`
- **Description :** Met à jour le mot de passe à l'aide d'un token.
- **Corps de la requête :**
    ```
    {
      "token": "le_token_recu_par_email",
      "new_password": "un_nouveau_mot_de_passe_solide"
    }
    ```
- **Réponses :**
    - `200 OK` : Mot de passe mis à jour avec succès.
    - `400 Bad Request` : Token invalide ou expiré.