Contenu personnalisé

Personnalisez le contenu pour les visiteurs identifiés tout en gardant votre documentation publique. La personnalisation permet, par exemple, de préremplir des clés d’API, d’afficher du contenu propre au plan ou au rôle d’un utilisateur et de filtrer le contenu de la référence d’API selon l’appartenance à un groupe. La personnalisation utilise une session partagée, un JWT ou OAuth pour identifier les visiteurs sans restreindre l’accès à vos pages.

Méthode	Idéal pour	Identification du visiteur
Session partagée	Une documentation et une application existante pouvant partager une session de navigateur	Mintlify demande les données utilisateur à votre Info API à l’aide des cookies de session du visiteur.
JWT	Un flux de connexion existant capable de signer les données utilisateur Mintlify	Votre flux de connexion redirige le visiteur avec un JWT signé.
OAuth	Un fournisseur OAuth 2.0 existant	Mintlify réalise un flux OAuth et demande les données utilisateur à votre Info API.

Configurer la personnalisation

Activez la personnalisation depuis la page Add-ons de votre Dashboard. La personnalisation est mutuellement exclusive avec l’authentification complète. Les authentifications JWT et OAuth incluent déjà les fonctionnalités de personnalisation.

Accédez à la page Add-ons de votre Dashboard.
Dans la section Personalization, sélectionnez session partagée, JWT ou OAuth.
Configurez la méthode de personnalisation choisie.
Cliquez sur Save changes.

Session partagée

La session partagée réutilise la session applicative existante du visiteur, il n’a donc pas besoin de se reconnecter sur votre site Mintlify.

Sélectionnez Shared session dans les paramètres de Personalization.
Saisissez une Info API URL qui renvoie les données utilisateur du visiteur actuel.
Saisissez facultativement une Login URL. Mintlify affiche un lien de connexion lorsque l’Info API ne renvoie pas de données utilisateur.
Cliquez sur Save changes.

Mintlify envoie une requête GET à l’Info API depuis le navigateur du visiteur, avec les identifiants inclus. Renvoyez une réponse JSON réussie pour un visiteur identifié :

User data response

{
  "expiresAt": 1893456000,
  "content": {
    "firstName": "Jane",
    "plan": "Enterprise"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

Pour un visiteur sans session valide, renvoyez une réponse d’échec telle que 401. Mintlify laisse le visiteur non identifié et conserve l’accès au contenu public. Si l’Info API se trouve sur une origine différente de votre documentation, configurez-la pour autoriser les requêtes cross-origin avec identifiants depuis l’origine exacte de la documentation. N’utilisez pas d’origine générique avec des identifiants. Empêchez les navigateurs et les caches intermédiaires de stocker les données utilisateur en renvoyant Cache-Control: private, no-store.

Les valeurs de apiPlaygroundInputs sont accessibles au navigateur afin que le bac à sable d’API puisse les envoyer. Renvoyez des identifiants à courte durée de vie et correctement limités en portée, et évitez d’exposer un jeton de session applicative privilégié lorsqu’un jeton dédié à la documentation est disponible.

JWT et OAuth

Les personnalisations JWT et OAuth utilisent le même format de données utilisateur que la session partagée, mais ne restreignent pas l’accès à votre documentation. Configurez ces méthodes dans Add-ons, et non dans Authentication. Pour la personnalisation JWT :

Saisissez l’URL de votre flux de connexion existant.
Cliquez sur Save changes.
Cliquez sur Generate new key et stockez en toute sécurité la clé privée téléchargée.
Dans votre flux de connexion, créez un JWT contenant les données utilisateur du visiteur identifié et signez-le avec la clé privée générée à l’aide de l’algorithme ES256.
Redirigez le visiteur vers une page de votre site de documentation avec le JWT signé comme fragment d’URL. Par exemple, https://docs.example.com/get-started#{SIGNED_JWT}. Pour un sous-chemin personnalisé, incluez ce sous-chemin dans l’URL.

Définissez la claim exp du JWT sur une durée courte de 10 secondes ou moins. Utilisez le champ expiresAt des données utilisateur pour contrôler la durée pendant laquelle Mintlify conserve les données de personnalisation. Pour la personnalisation OAuth :

Saisissez votre URL d’autorisation, votre client ID, vos scopes, votre URL de jeton, votre Info API URL et tous les paramètres facultatifs, puis cliquez sur Save changes. La personnalisation OAuth utilise le flux Authorization Code avec Proof Key for Code Exchange (PKCE) et ne nécessite pas de client secret.
Copiez la Redirect URL depuis le Dashboard et ajoutez-la comme URL de redirection autorisée chez votre fournisseur OAuth.
Configurez l’Info API pour accepter une requête GET avec le jeton d’accès OAuth dans l’en-tête Authorization: Bearer <access_token> et renvoyer les données utilisateur.

Le chemin de redirection OAuth est /mintlify-oauth-callback. Sur un sous-chemin personnalisé, le Dashboard inclut ce sous-chemin dans l’URL de redirection. Mintlify échange le code d’autorisation et demande les données utilisateur depuis le navigateur du visiteur. Si le jeton ou l’endpoint Info API se trouve sur une origine différente de votre documentation, configurez-le pour autoriser les requêtes cross-origin depuis l’origine exacte de la documentation. L’Info API doit autoriser l’en-tête de requête Authorization.

Préremplissage de la clé d’API

Renseignez automatiquement les champs du bac à sable d’API avec des valeurs propres à chaque utilisateur en renvoyant des noms de champs correspondants dans vos données utilisateur. Incluez ces valeurs dans le champ apiPlaygroundInputs de vos données utilisateur.

{
  "apiPlaygroundInputs": {
    "header": { "X-API-Key": "user_api_key_123" },
    "server": { "subdomain": "acme" }
  }
}

Les noms de champ doivent correspondre aux noms définis dans votre spécification OpenAPI. Mintlify n’applique que les valeurs correspondant au schéma de sécurité du point de terminaison en cours.

Contenu MDX dynamique

Affichez du contenu en fonction des informations utilisateur comme le nom, l’abonnement ou l’organisation grâce à la variable user dans vos pages MDX. Incluez des données personnalisées dans le champ content de vos données utilisateur.

{
  "content": {
    "firstName": "Jane",
    "company": "Acme Corp",
    "plan": "Enterprise"
  }
}

Utilisez ces valeurs dans votre MDX.

Bienvenue, {user.firstName} ! Votre forfait {user.plan} comprend 100 places pour les membres de votre organisation {user.company}.

Pour effectuer un rendu conditionnel en fonction des données utilisateur, utilisez la variable user dans les composants JSX.

{
  user.plan === 'enterprise'
    ? <>Contactez votre administrateur pour activer cette fonctionnalité.</>
    : <>Consultez <a href="https://yoursite.com/pricing">nos tarifs</a> pour plus d'informations sur la mise à niveau.</>
}

La variable user est un objet vide pour les utilisateurs déconnectés. Utilisez l’opérateur d’enchaînement optionnel sur tous les champs de user pour éviter les erreurs. Par exemple, {user.org?.plan} au lieu de {user.org.plan}.

Pour lire le même objet utilisateur depuis un fichier JavaScript personnalisé, utilisez window.mintlify.user et écoutez l’événement mintlify:user.

Visibilité des pages

Contrôlez les pages qui apparaissent dans la navigation selon les groupes d’utilisateurs en ajoutant groups au frontmatter de la page.

Avec la personnalisation, groups contrôle la visibilité mais ne restreint pas l’accès à une page. Un visiteur peut toujours ouvrir une page filtrée par groupe en accédant directement à son URL. Utilisez l’authentification pour restreindre l’accès aux contenus sensibles.

---
title: "Paramètres d'administration"
groups: ["admin"]
---

Filtrage du contenu OpenAPI

Filtrez le contenu de la référence d’API en fonction des groupes d’utilisateurs à l’aide de l’extension x-mint dans votre spécification OpenAPI. Vous pouvez filtrer des points de terminaison entiers, des propriétés de schéma individuelles, des variantes oneOf et des valeurs d’énumération.

Filtrer les endpoints

Ajoutez x-mint.groups à une opération ou à un chemin pour n’afficher l’endpoint dans la navigation qu’à certains groupes d’utilisateurs. Avec la personnalisation autonome, les utilisateurs qui ne font pas partie des groupes indiqués peuvent tout de même ouvrir la page de l’endpoint via son URL directe.

{
  "paths": {
    "/billing": {
      "get": {
        "summary": "Récupérer les détails de facturation",
        "x-mint": {
          "groups": ["admin", "billing"]
        },
        "responses": {
          "200": {
            "description": "Détails de facturation"
          }
        }
      }
    }
  }
}

{
  "paths": {
    "x-mint": {
      "groups": ["admin", "billing"]
    },
    "/billing": {
      "get": {
        "summary": "Récupérer les détails de facturation",
      }
    },
    "/users": {
      "get": {
        "summary": "Récupérer les détails de l'utilisateur",
      }
    }
  }
}

Filtrer les propriétés du schéma

Ajoutez x-mint.groups aux propriétés individuelles des corps de requête, des paramètres ou des réponses. Les propriétés sans x-mint.groups restent visibles pour tous les utilisateurs.

Restricted property

{
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "internal_id": {
            "type": "string",
            "x-mint": {
              "groups": ["admin"]
            }
          }
        }
      }
    }
  }
}

Dans cet exemple, tous les utilisateurs peuvent voir la propriété name. Seuls les utilisateurs du groupe admin peuvent voir la propriété internal_id.

Filtrer les variantes oneOf

Ajoutez x-mint.groups à chaque option oneOf pour restreindre les variantes de schéma qu’un utilisateur peut voir.

Restricted oneOf variant

{
  "schema": {
    "oneOf": [
      {
        "title": "Enterprise config",
        "type": "object",
        "x-mint": {
          "groups": ["enterprise"]
        },
        "properties": {
          "sso_enabled": { "type": "boolean" }
        }
      },
      {
        "title": "Standard config",
        "type": "object",
        "properties": {
          "notifications": { "type": "boolean" }
        }
      }
    ]
  }
}

Filtrer les valeurs d’énumération

Utilisez l’extension x-mint-enum pour restreindre certaines valeurs d’énumération par groupe. Indiquez chaque valeur restreinte comme key, avec ses groups autorisés comme value. Les valeurs d’énumération qui ne sont pas répertoriées dans x-mint-enum sont visibles par tous les utilisateurs.

Restricted enum values

{
  "type": "string",
  "enum": ["free", "pro", "enterprise"],
  "x-mint-enum": {
    "pro": ["pro", "enterprise"],
    "enterprise": ["enterprise"]
  }
}

Dans cet exemple, tous les utilisateurs voient free. Les utilisateurs appartenant aux groupes pro ou enterprise voient pro. Seuls les utilisateurs du groupe enterprise voient enterprise.

x-mint-enum est une extension distincte au niveau supérieur de l’objet de schéma, et non imbriquée sous x-mint.

Format des données utilisateur

Votre système d’identification ou d’authentification renvoie des données utilisateur qui contrôlent la personnalisation. Les champs groups, content et apiPlaygroundInputs décrits sur cette page font tous partie de l’objet de données utilisateur. Pour le format complet des données utilisateur et la référence des champs, consultez la page Format des données utilisateur.

Comportement de déconnexion

La déconnexion s’effectue côté client. Lorsque les utilisateurs cliquent sur le bouton de déconnexion, Mintlify efface les données de session stockées dans le navigateur. Pour limiter la durée de conservation des données de personnalisation, définissez le champ expiresAt dans vos données utilisateur.

Prise en main

Créer du contenu

Gérer votre site

Agent

Assistant

Contenu adapté aux agents

Recherche et SEO

Documenter des API

Intégrations

Référence

Contenu personnalisé

Configurer la personnalisation

Session partagée

JWT et OAuth

Préremplissage de la clé d’API

Contenu MDX dynamique

Visibilité des pages

Filtrage du contenu OpenAPI

Filtrer les endpoints

Filtrer les propriétés du schéma

Filtrer les variantes oneOf

Filtrer les valeurs d’énumération

Format des données utilisateur

Comportement de déconnexion

​Configurer la personnalisation

​Session partagée

​JWT et OAuth

​Préremplissage de la clé d’API

​Contenu MDX dynamique

​Visibilité des pages

​Filtrage du contenu OpenAPI

​Filtrer les endpoints

​Filtrer les propriétés du schéma

​Filtrer les variantes oneOf

​Filtrer les valeurs d’énumération

​Format des données utilisateur

​Comportement de déconnexion

Configurer la personnalisation

Session partagée

JWT et OAuth

Préremplissage de la clé d’API

Contenu MDX dynamique

Visibilité des pages

Filtrage du contenu OpenAPI

Filtrer les endpoints

Filtrer les propriétés du schéma

Filtrer les variantes oneOf

Filtrer les valeurs d’énumération

Format des données utilisateur

Comportement de déconnexion