> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-add-hello-world-quickstart-48843.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration de la personnalisation

> Permettez aux utilisateurs de se connecter pour une expérience de documentation personnalisée

La personnalisation adapte votre documentation à chaque utilisateur lorsqu’il est connecté. Par exemple, vous pouvez préremplir ses clés API, afficher du contenu spécifique à son offre ou à son rôle, ou masquer les sections auxquelles il n’a pas besoin d’accéder.

<div id="personalization-features">
  ## Fonctionnalités de personnalisation
</div>

Personnalisez le contenu grâce à ces fonctionnalités de personnalisation.

<div id="api-key-prefilling">
  ### Préremplissage de la clé API
</div>

Renseignez automatiquement les champs du terrain de jeu API avec des valeurs propres à l’utilisateur en renvoyant des noms de champs identiques dans vos données utilisateur. Les noms de champs dans vos données utilisateur doivent correspondre exactement à ceux du terrain de jeu API pour que le préremplissage automatique fonctionne.

<div id="dynamic-mdx-content">
  ### Contenu MDX dynamique
</div>

Affichez du contenu dynamique en fonction d’informations utilisateur comme le nom, l’offre ou l’organisation à l’aide de la variable `user`.

```jsx
Bon retour, {user.firstName} ! Votre offre {user.org?.plan} inclut...
```

Voir la section [Format des données utilisateur](#user-data-format) ci-dessous pour des exemples détaillés et des conseils de mise en œuvre.

<div id="page-visibility">
  ### Visibilité des pages
</div>

Limitez les pages visibles par vos utilisateurs en ajoutant des champs `groups` au front matter de vos pages. Par défaut, chaque page est visible par tous les utilisateurs.

Les utilisateurs ne verront que les pages des `groups` auxquels ils appartiennent.

```mdx
---
title: "Gestion des utilisateurs"
description: "Ajouter et supprimer des utilisateurs de votre organisation"
groups: ["admin"]
---
```

<div id="user-data-format">
  ## Format des données utilisateur
</div>

Lors de la mise en place de la personnalisation, votre système renvoie des données utilisateur dans un format spécifique qui permet d’adapter le contenu. Ces données peuvent être envoyées soit sous la forme d’un objet JSON brut, soit dans un JWT signé, selon votre méthode d’échange. La structure des données est identique dans les deux cas.

```tsx
type User = {
  expiresAt?: number;
  groups?: string[];
  content?: Record<string, any>;
  apiPlaygroundInputs?: {
    header?: Record<string, any>;
    query?: Record<string, any>;
    cookie?: Record<string, any>;
    server?: Record<string, string>;
  };
};
```

<ParamField path="expiresAt" type="number">
  Durée d’expiration de la session en **secondes depuis l’époque Unix**. Si l’utilisateur charge une page après ce délai, ses données stockées sont automatiquement supprimées et il doit se réauthentifier.
  <Warning><b>Pour les échanges JWT :</b> Cela diffère de l’attribut `exp` du JWT, qui détermine quand un JWT est considéré invalide. Par sécurité, définissez l’attribut `exp` du JWT sur une durée très courte (10 secondes ou moins). Utilisez `expiresAt` pour la durée réelle de la session (de quelques heures à plusieurs semaines).</Warning>
</ParamField>

<ParamField path="groups" type="string[]">
  Liste des groupes auxquels l’utilisateur appartient. Les pages dont le frontmatter contient des `groups` correspondants sont visibles pour cet utilisateur.

  **Exemple** : Un utilisateur avec `groups: ["admin", "engineering"]` peut accéder aux pages étiquetées avec les groupes `admin` ou `engineering`.
</ParamField>

<ParamField path="content" type="object">
  Données personnalisées accessibles dans votre contenu `MDX` via la variable `user`. Utilisez-les pour une personnalisation dynamique dans toute votre documentation.

  **Exemple simple** :

  ```json
  { "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }
  ```

  **Utilisation dans `MDX`** :

  ```mdx
  Welcome back, {user.firstName}! Your {user.plan} plan includes...
  ```

  Avec l’exemple de données `user`, le rendu serait : Welcome back, Ronan! Your Enterprise plan includes...

  **Rendu conditionnel avancé** :

  ```jsx
  Authentication is an enterprise feature. {
    user.org === undefined
      ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
      : user.org.plan !== 'enterprise'
        ? <>You are currently on the ${user.org.plan ?? 'free'} plan. See <a href="https://mintlify.com/pricing">our pricing page</a> for information about upgrading.</>
        : <>To request this feature for your enterprise org, contact your admin.</>
  }
  ```

  <Note>
    Les informations contenues dans `user` ne sont disponibles que pour les utilisateurs connectés. Pour les utilisateurs déconnectés, la valeur de `user` sera `{}`. Pour éviter que la page ne plante pour les utilisateurs déconnectés, utilisez toujours l’opérateur d’enchaînement optionnel sur vos champs `user`. Par exemple, `{user.org?.plan}`.
  </Note>
</ParamField>

<ParamField path="apiPlaygroundInputs" type="object">
  Valeurs propres à l’utilisateur qui préremplissent les champs du Terrain de jeu API. Cela fait gagner du temps en remplissant automatiquement leurs données lors des tests d’API.

  **Exemple** :

  ```json
  {
    "header": { "X-API-Key": "user_api_key_123" },
    "server": { "subdomain": "foo" },
    "query": { "org_id": "12345" }
  }
  ```

  Si un utilisateur envoie des requêtes sur un sous-domaine spécifique, vous pouvez transmettre `{ server: { subdomain: 'foo' } }` comme champ `apiPlaygroundInputs`. Cette valeur sera préremplie sur toute page d’API comportant le champ `subdomain`.

  <Note>Les champs `header`, `query` et `cookie` ne seront préremplis que s’ils font partie de votre [schéma de sécurité OpenAPI](https://swagger.io/docs/specification/authentication/). Si un champ se trouve dans les sections `Authorization` ou `Server`, il sera prérempli. Créer un paramètre d’en-tête standard nommé `Authorization` n’activera pas cette fonctionnalité.</Note>
</ParamField>

<div id="example-user-data">
  ### Exemple de données utilisateur
</div>

```json
{
  "expiresAt": 1735689600,
  "groups": ["admin", "beta-users"],
  "content": {
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "plan": "Enterprise",
    "region": "us-west"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer abc123",
      "X-Org-ID": "techcorp"
    },
    "server": {
      "environment": "production",
      "region": "us-west"
    }
  }
}
```

<div id="configuring-personalization">
  ## Configurer la personnalisation
</div>

Sélectionnez la méthode de handshake que vous souhaitez configurer.

<Tabs>
  <Tab title="JWT">
    ### Prérequis

    * Un système d’authentification capable de générer et de signer des JWT
    * Un service backend capable de créer des URL de redirection

    ### Mise en œuvre

    <Steps>
      <Step title="Generate a private key.">
        1. Dans votre tableau de bord, allez à [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
        2. Sélectionnez **Personnalisation**.
        3. Sélectionnez **JWT**.
        4. Saisissez l’URL de votre parcours de connexion existant et sélectionnez **Save changes**.
        5. Sélectionnez **Generate new key**.
        6. Stockez votre clé en lieu sûr afin qu’elle soit accessible par votre backend.
      </Step>

      <Step title="Integrate Mintlify personalization into your login flow.">
        Modifiez votre parcours de connexion existant pour inclure ces étapes après la connexion de l’utilisateur :

        * Créez un JWT contenant les informations de l’utilisateur connecté au format `User`. Consultez la section [User data format](#user-data-format) ci-dessus pour plus d’informations.
        * Signez le JWT avec la clé secrète, en utilisant l’algorithme ES256.
        * Créez une URL de redirection vers votre documentation, en incluant le JWT comme fragment.
      </Step>
    </Steps>

    ### Exemple

    Votre documentation est hébergée sur `docs.foo.com`. Vous souhaitez que votre documentation soit séparée de votre tableau de bord (ou vous n’avez pas de tableau de bord) et activer la personnalisation.

    Générez un secret JWT. Ensuite, créez un endpoint de connexion à `https://foo.com/docs-login` qui lance un parcours de connexion vers votre documentation.

    Après vérification des identifiants de l’utilisateur :

    * Générez un JWT avec les données utilisateur au format Mintlify.
    * Signez le JWT et redirigez vers `https://docs.foo.com#{SIGNED_JWT}`.

    ```ts
    import * as jose from 'jose';
    import { Request, Response } from 'express';

    const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;

    const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256');

    export async function handleRequest(req: Request, res: Response) {
      const user = {
        expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000),
        groups: res.locals.user.groups,
        content: {
          firstName: res.locals.user.firstName,
          lastName: res.locals.user.lastName,
        },
      };

      const jwt = await new jose.SignJWT(user)
        .setProtectedHeader({ alg: 'ES256' })
        .setExpirationTime('10 s')
        .sign(signingKey);

      return res.redirect(`https://docs.foo.com#${jwt}`);
    }
    ```

    ### Préserver les ancres de page

    Pour rediriger les utilisateurs vers des sections spécifiques après connexion, utilisez ce format d’URL : `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.

    **Exemple** :

    * URL d’origine : `https://docs.foo.com/quickstart#step-one`
    * URL de redirection : `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`
  </Tab>

  <Tab title="OAuth 2.0">
    ### Prérequis

    * Un serveur OAuth prenant en charge le flux Auth Code avec PKCE
    * La capacité de créer un endpoint d’API accessible via des jetons d’accès OAuth

    ### Implémentation

    <Steps>
      <Step title="Create user info API endpoint.">
        Créez un endpoint d’API qui :

        * Accepte les jetons d’accès OAuth pour l’authentification.
        * Renvoie les données utilisateur au format `User`. Voir la section [User data format](#user-data-format) ci-dessus pour plus d’informations.
        * Définit les scopes d’accès.
      </Step>

      <Step title="Configure your OAuth personalization settings.">
        1. Dans votre tableau de bord, accédez à [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
        2. Sélectionnez **Personalization**.
        3. Sélectionnez **OAuth** et configurez les champs suivants :

        * **Authorization URL** : votre endpoint d’autorisation OAuth.
        * **Client ID** : votre identifiant client OAuth 2.0.
        * **Scopes** : permissions à demander. Copiez la chaîne de scope **entière** (par exemple, pour un scope comme `provider.users.docs`, copiez l’intégralité de `provider.users.docs`). Doit correspondre aux scopes de l’endpoint configuré à l’étape 1.
        * **Token URL** : votre endpoint d’échange de jetons OAuth.
        * **Info API URL** : endpoint pour récupérer les données utilisateur pour la personnalisation. Créé à l’étape 1.

        4. Sélectionnez **Save changes**
      </Step>

      <Step title="Configure your OAuth server.">
        1. Copiez l’**URL de redirection** depuis vos [paramètres d’authentification](https://dashboard.mintlify.com/settings/deployment/authentication).
        2. Ajoutez cette URL comme URL de redirection autorisée dans la configuration de votre serveur OAuth.
      </Step>
    </Steps>

    ### Exemple

    Votre documentation est hébergée sur `foo.com/docs` et vous disposez d’un serveur OAuth existant prenant en charge le flux PKCE. Vous souhaitez personnaliser votre documentation en fonction des données utilisateur.

    **Créez un endpoint d’informations utilisateur** à `api.foo.com/docs/user-info`, qui requiert un jeton d’accès OAuth avec le scope `provider.users.docs` et renvoie les données personnalisées de l’utilisateur :

    ```json
    {
      "content": {
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "groups": ["engineering", "admin"]
    }
    ```

    **Configurez les paramètres de votre serveur OAuth** dans votre tableau de bord :

    * **URL d’autorisation** : `https://auth.foo.com/authorization`
    * **ID client** : `ydybo4SD8PR73vzWWd6S0ObH`
    * **Scopes** : `['docs-user-info']`
    * **URL de jeton** : `https://auth.foo.com/exchange`
    * **URL de l’API d’informations** : `https://api.foo.com/docs/user-info`

    **Configurez votre serveur OAuth** pour autoriser les redirections vers votre URL de rappel (callback).
  </Tab>

  <Tab title="Session partagée">
    ### Prérequis

    * Un tableau de bord ou un portail utilisateur avec une authentification de session basée sur des cookies.
    * Possibilité de créer un point de terminaison API sur la même origine ou le même sous-domaine que votre tableau de bord.
      * Si votre tableau de bord est à `foo.com`, l’**URL de l’API** doit commencer par `foo.com` ou `*.foo.com`.
      * Si votre tableau de bord est à `dash.foo.com`, l’**URL de l’API** doit commencer par `dash.foo.com` ou `*.dash.foo.com`.
    * Vos docs sont hébergées sur le même domaine ou sous-domaine que votre tableau de bord.
      * Si votre tableau de bord est à `foo.com`, vos **docs** doivent être hébergées à `foo.com` ou `*.foo.com`.
      * Si votre tableau de bord est à `*.foo.com`, vos **docs** doivent être hébergées à `foo.com` ou `*.foo.com`.

    ### Implémentation

    <Steps>
      <Step title="Create user info API endpoint.">
        Créez un point de terminaison API qui :

        * Utilise votre authentification de session existante pour identifier les utilisateurs
        * Renvoie les données utilisateur au format `User` (voir la section [Format des données utilisateur](#user-data-format) ci-dessus)
        * Si le domaine de l’API et celui des docs **ne correspondent pas exactement** :

          * Ajoutez le domaine des docs à l’en-tête `Access-Control-Allow-Origin` de votre API (ne doit pas être `*`).
          * Définissez l’en-tête `Access-Control-Allow-Credentials` de votre API sur `true`.

                  <Warning>
                    Activez les en-têtes CORS uniquement sur ce point de terminaison spécifique, pas sur l’ensemble de l’API de votre tableau de bord.
                  </Warning>
      </Step>

      <Step title="Configure your personalization settings">
        1. Dans votre tableau de bord, allez à [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
        2. Sélectionnez **Personalization**.
        3. Sélectionnez **Shared Session**.
        4. Saisissez votre **Info API URL**, c’est-à-dire le point de terminaison de la première étape.
        5. Saisissez votre **Login URL**, où les utilisateurs se connectent à votre tableau de bord.
        6. Sélectionnez **Save changes**.
      </Step>
    </Steps>

    ### Exemples

    #### Tableau de bord sur sous-domaine, docs sur sous-domaine

    Vous avez un tableau de bord à `dash.foo.com`, qui utilise une authentification de session basée sur des cookies. Les routes de votre API de tableau de bord sont hébergées à `dash.foo.com/api`. Vous souhaitez configurer la personnalisation pour vos docs hébergées à `docs.foo.com`.

    **Processus de configuration** :

    1. **Créez le point de terminaison** `dash.foo.com/api/docs/user-info` qui identifie les utilisateurs via l’authentification de session et renvoie leurs données utilisateur.
    2. **Ajoutez les en-têtes CORS** pour cette route uniquement :
       * `Access-Control-Allow-Origin` : `https://docs.foo.com`
       * `Access-Control-Allow-Credentials` : `true`
    3. **Configurez l’URL de l’API** dans les paramètres d’authentification : `https://dash.foo.com/api/docs/user-info`.

    #### Tableau de bord sur sous-domaine, docs à la racine

    Vous avez un tableau de bord à `dash.foo.com`, qui utilise une authentification de session basée sur des cookies. Les routes de votre API de tableau de bord sont hébergées à `dash.foo.com/api`. Vous souhaitez configurer la personnalisation pour vos docs hébergées à `foo.com/docs`.

    **Processus de configuration** :

    1. **Créez le point de terminaison** `dash.foo.com/api/docs/user-info` qui identifie les utilisateurs via l’authentification de session et renvoie leurs données utilisateur.
    2. **Ajoutez les en-têtes CORS** pour cette route uniquement :
       * `Access-Control-Allow-Origin` : `https://foo.com`
       * `Access-Control-Allow-Credentials` : `true`
    3. **Configurez l’URL de l’API** dans les paramètres d’authentification : `https://dash.foo.com/api/docs/user-info`.

    #### Tableau de bord à la racine, docs à la racine

    Vous avez un tableau de bord à `foo.com/dashboard`, qui utilise une authentification de session basée sur des cookies. Les routes de votre API de tableau de bord sont hébergées à `foo.com/api`. Vous souhaitez configurer la personnalisation pour vos docs hébergées à `foo.com/docs`.

    **Processus de configuration** :

    1. **Créez le point de terminaison** `foo.com/api/docs/user-info` qui identifie les utilisateurs via l’authentification de session et renvoie leurs données utilisateur.
    2. **Configurez l’URL de l’API** dans les paramètres d’authentification : `https://foo.com/api/docs/user-info`

    <Note>
      Aucune configuration CORS n’est nécessaire puisque le tableau de bord et les docs partagent le même domaine.
    </Note>
  </Tab>
</Tabs>