> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# API d'authentification

> Authentification utilisateur, inscription et gestion des sessions

## Aperçu

L'API d'authentification gère l'inscription, la connexion, la gestion des sessions, la vérification des e-mails et la réinitialisation des mots de passe. Toutes les authentifications utilisent des cookies HTTP-only sécurisés pour la gestion de session avec des tokens JWT.

## Flux d'authentification

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client
    participant API
    participant Email

    User->>Client: Enter credentials
    Client->>API: POST /auth/register
    API->>Email: Send verification email
    API-->>Client: Success (unverified account)
    User->>Email: Click verification link
    Email->>API: POST /auth/verify-email
    API-->>Client: Email verified
    User->>Client: Login
    Client->>API: POST /auth/login
    API-->>Client: Set HTTP-only cookie
    Client->>API: Authenticated requests
```

## Endpoints

### Inscrire un nouvel utilisateur

<ParamField path="POST" type="endpoint">
  /auth/register
</ParamField>

Crée un nouveau compte utilisateur. Un lien de vérification d'e-mail sera envoyé à l'adresse fournie.

**Corps de la requête :**

```json theme={null}
{
  "email": "user@example.com",
  "name": "John Doe",
  "password": "SecurePassword123!"
}
```

<ParamField body="email" type="string" required>
  Adresse e-mail valide
</ParamField>

<ParamField body="name" type="string" required>
  Nom complet (minimum 2 caractères)
</ParamField>

<ParamField body="password" type="string" required>
  Mot de passe fort (minimum 8 caractères)
</ParamField>

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "Registration successful. Please check your email to verify your account.",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "emailVerified": false,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}
```

<Warning>
  Les utilisateurs doivent vérifier leur e-mail avant de pouvoir accéder pleinement à la plateforme.
</Warning>

***

### Connexion

<ParamField path="POST" type="endpoint">
  /auth/login
</ParamField>

Authentifie un utilisateur et établit une session.

**Corps de la requête :**

```json theme={null}
{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}
```

<ParamField body="email" type="string" required>
  Adresse e-mail de l'utilisateur
</ParamField>

<ParamField body="password" type="string" required>
  Mot de passe de l'utilisateur
</ParamField>

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true
  }
}
```

**Cookies définis :**

* `accessToken` - HTTP-only, Secure, SameSite=Strict (15 minutes)
* `refreshToken` - HTTP-only, Secure, SameSite=Strict (7 jours)

***

### Récupérer l'utilisateur courant

<ParamField path="GET" type="endpoint">
  /auth/me
</ParamField>

Récupère les informations de l'utilisateur actuellement authentifié.

**En-têtes :**

```
Cookie: accessToken=...
```

**Réponse :**

```json theme={null}
{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}
```

***

### Rafraîchir le token d'accès

<ParamField path="POST" type="endpoint">
  /auth/refresh
</ParamField>

Obtient un nouveau token d'accès à l'aide du refresh token.

**En-têtes :**

```
Cookie: refreshToken=...
```

**Réponse :**

```json theme={null}
{
  "ok": true,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER"
  }
}
```

**Cookies mis à jour :**

* Nouveau `accessToken` émis
* `refreshToken` renouvelé pour la sécurité

***

### Déconnexion

<ParamField path="POST" type="endpoint">
  /auth/logout
</ParamField>

Met fin à la session de l'utilisateur et invalide les tokens.

**En-têtes :**

```
Cookie: accessToken=...
```

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "Logged out successfully"
}
```

**Cookies supprimés :**

* `accessToken` supprimé
* `refreshToken` supprimé

***

### Vérifier l'adresse e-mail

<ParamField path="POST" type="endpoint">
  /auth/verify-email
</ParamField>

Vérifie l'adresse e-mail d'un utilisateur à l'aide du token envoyé par e-mail.

**Corps de la requête :**

```json theme={null}
{
  "token": "verification_token_from_email"
}
```

<ParamField body="token" type="string" required>
  Token de vérification d'e-mail
</ParamField>

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "Email verified successfully. You can now log in."
}
```

***

### Renvoyer l'e-mail de vérification

<ParamField path="POST" type="endpoint">
  /auth/send-email-verification
</ParamField>

Demande un nouvel e-mail de vérification si le précédent a expiré ou a été perdu.

**Corps de la requête :**

```json theme={null}
{
  "email": "user@example.com"
}
```

<ParamField body="email" type="string" required>
  Adresse e-mail de l'utilisateur
</ParamField>

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "Verification email sent. Please check your inbox."
}
```

**Limitation de débit :**

Cet endpoint est limité pour éviter les abus :

* **5 requêtes par heure** par adresse e-mail

***

### Mot de passe oublié

<ParamField path="POST" type="endpoint">
  /auth/forgot-password
</ParamField>

Demande un lien de réinitialisation du mot de passe par e-mail.

**Corps de la requête :**

```json theme={null}
{
  "email": "user@example.com"
}
```

<ParamField body="email" type="string" required>
  Adresse e-mail de l'utilisateur
</ParamField>

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "If an account exists with this email, a password reset link has been sent."
}
```

<Info>
  Pour des raisons de sécurité, l'API renvoie toujours un message de succès, qu'un e-mail existe ou non.
</Info>

***

### Réinitialiser le mot de passe

<ParamField path="POST" type="endpoint">
  /auth/reset-password
</ParamField>

Réinitialise le mot de passe à l'aide du token reçu par e-mail.

**Corps de la requête :**

```json theme={null}
{
  "token": "reset_token_from_email",
  "password": "NewSecurePassword123!"
}
```

<ParamField body="token" type="string" required>
  Token de réinitialisation du mot de passe reçu par e-mail
</ParamField>

<ParamField body="password" type="string" required>
  Nouveau mot de passe (minimum 8 caractères)
</ParamField>

**Réponse :**

```json theme={null}
{
  "success": true,
  "message": "Password reset successful. You can now log in with your new password."
}
```

***

## Fonctions de sécurité

### Cookies HTTP-only

Tous les tokens de session sont stockés dans des cookies HTTP-only pour éviter les attaques XSS. JavaScript ne peut pas accéder à ces cookies.

### Attribut Secure

Les cookies sont marqués `Secure`, garantissant qu'ils ne sont transmis qu'en HTTPS en production.

### Politique SameSite

Les cookies utilisent `SameSite=Strict` pour prévenir les attaques CSRF.

### Rotation des tokens

Les refresh tokens sont renouvelés à chaque utilisation pour réduire les risques si un token est compromis.

### Exigences de mot de passe

* Minimum 8 caractères
* Recommandé : mélange de majuscules, minuscules, chiffres et caractères spéciaux

### Expiration des tokens

* **Access Token :** 15 minutes
* **Refresh Token :** 7 jours
* **Verification Token :** 24 heures
* **Reset Token :** 1 heure

## Codes d'erreur

| Code                   | Statut | Description                                 |
| ---------------------- | ------ | ------------------------------------------- |
| `INVALID_CREDENTIALS`  | 401    | E-mail ou mot de passe incorrect            |
| `EMAIL_ALREADY_EXISTS` | 409    | L'e-mail est déjà enregistré                |
| `EMAIL_NOT_VERIFIED`   | 403    | Vérification d'e-mail requise               |
| `INVALID_TOKEN`        | 400    | Token invalide ou expiré                    |
| `TOKEN_EXPIRED`        | 401    | Token expiré                                |
| `WEAK_PASSWORD`        | 400    | Le mot de passe ne répond pas aux exigences |
| `RATE_LIMIT_EXCEEDED`  | 429    | Trop de requêtes                            |

## Cas d'usage

### Exemple 1 : Flux complet d'inscription

```bash theme={null}
# Étape 1 : Inscription
curl -X POST "https://api.steerai.autos/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dealer@example.com",
    "name": "Auto Dealer",
    "password": "SecurePass123!"
  }'

# Étape 2 : L'utilisateur reçoit l'e-mail et vérifie
curl -X POST "https://api.steerai.autos/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "verification_token_from_email"
  }'

# Étape 3 : Connexion
curl -X POST "https://api.steerai.autos/v1/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "dealer@example.com",
    "password": "SecurePass123!"
  }'
```

### Exemple 2 : Flux de réinitialisation du mot de passe

```bash theme={null}
# Étape 1 : Demande de réinitialisation
curl -X POST "https://api.steerai.autos/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dealer@example.com"
  }'

# Étape 2 : Réinitialisation avec le token de l'e-mail
curl -X POST "https://api.steerai.autos/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_token_from_email",
    "password": "NewSecurePass123!"
  }'
```

### Exemple 3 : Rafraîchissement du token

```bash theme={null}
# Rafraîchir le token d'accès avant expiration
curl -X POST "https://api.steerai.autos/v1/auth/refresh" \
  -b cookies.txt \
  -c cookies.txt
```

## Implémentation côté client

### JavaScript/Node.js

```javascript theme={null}
class AuthClient {
  constructor(baseURL) {
    this.baseURL = baseURL;
  }

  async register(email, name, password) {
    const response = await fetch(`${this.baseURL}/auth/register`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, name, password })
    });
    return response.json();
  }

  async login(email, password) {
    const response = await fetch(`${this.baseURL}/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include', // Important for cookies
      body: JSON.stringify({ email, password })
    });
    return response.json();
  }

  async getCurrentUser() {
    const response = await fetch(`${this.baseURL}/auth/me`, {
      credentials: 'include'
    });
    return response.json();
  }

  async logout() {
    const response = await fetch(`${this.baseURL}/auth/logout`, {
      method: 'POST',
      credentials: 'include'
    });
    return response.json();
  }
}
```

## Bonnes pratiques

<AccordionGroup>
  <Accordion title="Toujours utiliser HTTPS en production">
    Ne transmettez jamais les identifiants via des connexions HTTP non sécurisées.
  </Accordion>

  <Accordion title="Implémenter le rafraîchissement côté client">
    Rafraîchissez automatiquement les tokens avant leur expiration pour maintenir la continuité de session.
  </Accordion>

  <Accordion title="Stocker les refresh tokens en sécurité">
    Utilisez des cookies HTTP-only (gérés automatiquement par notre API) plutôt que localStorage.
  </Accordion>

  <Accordion title="Appliquer des politiques de mot de passe robustes">
    Exigez des mots de passe avec une complexité et une longueur suffisantes.
  </Accordion>

  <Accordion title="Mettre en place le rate limiting">
    Protégez les endpoints d'authentification contre les attaques par force brute.
  </Accordion>

  <Accordion title="Journaliser les événements d'authentification">
    Suivez les tentatives de connexion, les réinitialisations de mot de passe et les activités suspectes.
  </Accordion>
</AccordionGroup>

## Ressources associées

<CardGroup cols={2}>
  <Card title="Démarrage rapide" icon="rocket" href="/fr/getting-started/authentication">
    Guide de démarrage pour l'authentification
  </Card>

  <Card title="Guide de sécurité" icon="shield" href="/fr/guides/security">
    Bonnes pratiques de sécurité complètes
  </Card>

  <Card title="API Utilisateurs" icon="user" href="/fr/api-reference/users/management">
    Endpoints de gestion et profils utilisateurs
  </Card>

  <Card title="API Équipes" icon="users" href="/fr/api-reference/teams/overview">
    Collaboration d'équipe et permissions
  </Card>
</CardGroup>