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

​
Fonctionnalités de personnalisation

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

​
Préremplissage de la clé API

Renseignez automatiquement les champs du bac à sable d’API avec des valeurs propres à chaque utilisateur en renvoyant, dans vos données utilisateur, des noms de champs identiques. Pour que le préremplissage automatique fonctionne, les noms de champs de vos données utilisateur doivent correspondre exactement à ceux du bac à sable d’API.

​
Contenu MDX dynamique

Affichez du contenu dynamique en fonction d’informations sur l’utilisateur, comme son nom, son abonnement ou son organisation, à l’aide de la variable user. 
Bon retour, {user.firstName} ! Votre forfait {user.org?.plan} inclut...
Voir la section Format des données utilisateur ci-dessous pour des exemples détaillés et des recommandations de mise en œuvre.

​
Visibilité des pages

Limitez les pages visibles par vos utilisateurs en ajoutant des champs groups au frontmatter de vos pages. Par défaut, chaque page est visible pour tous les utilisateurs. Les utilisateurs ne verront que les pages associées aux groups auxquels ils appartiennent. 
---
title: "Gestion de vos utilisateurs"
description: "Ajouter et supprimer des utilisateurs de votre organisation"
groups: ["admin"]
---

​
Format des données utilisateur

Lors de l’implémentation de la personnalisation, votre système renvoie les données utilisateur dans un format spécifique qui permet de personnaliser le contenu. Ces données peuvent être envoyées soit sous forme d’objet JSON brut, soit encapsulées dans un JWT signé, selon votre méthode de négociation. La structure des données est identique dans les deux cas. 
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>;
  };
};
​
expiresAt
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.
Pour les handshakes JWT : Cela diffère de la claim exp du JWT, qui détermine le moment où un JWT est considéré comme invalide. Par mesure de sécurité, définissez la claim exp du JWT sur une courte durée (10 secondes ou moins). Utilisez expiresAt pour la durée réelle de la session (de quelques heures à plusieurs semaines).
​
groups
string[]
Liste des groupes auxquels l’utilisateur appartient. Les pages dont le champ groups dans leur frontmatter correspond sont visibles par cet utilisateur.Exemple : Un utilisateur avec groups: ["admin", "engineering"] peut accéder aux pages étiquetées avec le groupe admin ou engineering.
​
content
object
Données personnalisées accessibles dans votre contenu MDX via la variable user. Utilisez ces données pour une personnalisation dynamique dans toute votre documentation.Exemple simple :
{ "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" }
Utilisation dans MDX :
Welcome back, {user.firstName}! Your {user.plan} plan includes...
Avec les données d’exemple de user, le rendu serait : Welcome back, Ronan! Your Enterprise plan includes…Rendu conditionnel avancé :
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.</>
}
Les informations 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’optional chaining sur vos champs user. Par exemple, {user.org?.plan}.
​
apiPlaygroundInputs
object
Valeurs propres à l’utilisateur qui préremplissent les champs du bac à sable d’API. Cela fait gagner du temps aux utilisateurs en remplissant automatiquement leurs données lors des tests d’API.Exemple :
{
  "header": { "X-API-Key": "user_api_key_123" },
  "server": { "subdomain": "foo" },
  "query": { "org_id": "12345" }
}
Si un utilisateur effectue des requêtes sur un sous-domaine spécifique, vous pouvez envoyer { server: { subdomain: 'foo' } } en tant que champ apiPlaygroundInputs. Cette valeur sera préremplie sur toute page d’API utilisant le champ subdomain.
Les champs header, query et cookie ne seront préremplis que s’ils font partie de votre schéma de sécurité OpenAPI. 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é.

​
Exemple de données d’utilisateur

{
  "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"
    }
  }
}

​
Configurer la personnalisation

Sélectionnez la méthode de handshake que vous souhaitez configurer.
  • JWT (JSON Web Token)
  • OAuth 2.0
  • Session partagée

​
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

​
Implémentation

1

Generate a private key.

  1. Dans votre Dashboard, accédez à Authentication.
  2. Sélectionnez Personalization.
  3. Sélectionnez JWT.
  4. Saisissez l’URL de votre flux de connexion existant et sélectionnez Enregistrer les modifications.
  5. Sélectionnez Generate new key.
  6. Stockez votre key en toute sécurité à un emplacement accessible par votre backend.
2

Integrate Mintlify personalization into your login flow.

Modifiez votre flux 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 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 hash.

​
Exemple

Votre documentation est hébergée sur docs.foo.com. Vous souhaitez que votre documentation soit distincte de votre Dashboard (ou vous n’avez pas de Dashboard) et activer la personnalisation.Générez un secret JWT. Puis créez un endpoint de connexion à https://foo.com/docs-login qui lance un flux 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 de Mintlify.
  • Signez le JWT et redirigez vers https://docs.foo.com#{SIGNED_JWT}.
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