Les équipes d'ingénierie et les architectes de plateformes de développement gérant des documentations d'API privées pour des clients grand compte, des partenaires stratégiques ou des services internes font face à un compromis récurrent : offrir une expérience moderne avec des consoles de test interactives (API Playground), tout en isolant rigoureusement les points de terminaison de facturation, les interfaces d'administration et les SDK propriétaires contre les accès non autorisés et les robots d'indexation.
Mintlify répond à cette exigence en combinant son moteur basé sur MDX et OpenAPI avec quatre modes de contrôle d'accès : protection interne à l'organisation, verrouillage global par mot de passe, authentification unique d'entreprise (SSO / OAuth 2.0) et validation de jetons signés JSON Web Tokens (JWT). Ce guide détaille les prérequis d'architecture, les processus de configuration, la gestion des permissions par groupe (RBAC) au niveau des pages et l'injection sécurisée d'identifiants dans le Playground interactif pour des déploiements en production.
Prérequis d'architecture et contraintes de domaine
Avant de configurer l'authentification, les équipes techniques doivent prendre en compte les contraintes d'hébergement de Mintlify :
- Obligation de domaine dédié : L'authentification (totale ou partielle) exige que la documentation soit hébergée sur un domaine personnalisé dédié (tel que
docs.api.example.com) ou un sous-domaine Mintlify (example.mintlify.site). Le verrouillage d'accès n'est pas pris en charge sur les sous-chemins (commeexample.com/docs). Sur un sous-chemin, seules des fonctionnalités de personnalisation sans blocage strict sont possibles. - Périmètre du contrôle (Total vs. Partiel) : Vous pouvez opter pour une authentification totale (Full) (verrouillant l'intégralité du site et les spécifications OpenAPI derrière un formulaire de connexion) ou une authentification partielle (Partial) (laissant les guides d'initiation publics et restreignant uniquement les points d'entrée sensibles).
- Sécurité des déploiements de prévisualisation (Preview Deployments) : Lors des flux Git automatisés par Pull Request, les URL de prévisualisation non protégées peuvent exposer des API confidentielles. L'activation de l'authentification sur Mintlify applique automatiquement ces règles d'accès à l'ensemble des branches de prévisualisation.
Matrice comparative des méthodes d'authentification
| Méthode | Cas d'usage recommandé | Formule requise | RBAC par groupe | Pré-remplissage du Playground | Périmètre de révocation des accès |
|---|---|---|---|---|---|
| Authentification interne (Private) | Équipes d'ingénierie internes, wikis d'entreprise | Toutes les formules | Non | Non | Retrait du membre dans l'organisation Mintlify |
| Protection par mot de passe (Password) | Bêta fermée, revue sous accord de confidentialité (NDA) | Pro ou Enterprise | Non | Non | Renouvellement du mot de passe partagé pour tout le portail |
| SSO d'entreprise (OAuth 2.0 / SSO) | Fédération d'identité d'entreprise (Okta, Entra ID, Google) | Enterprise | Oui | Oui | Désactivation immédiate dans l'IdP de l'entreprise |
| Authentification JWT | Portails intégrés aux consoles SaaS de production existantes | Enterprise | Oui | Oui | Expiration courte du jeton et contrôle dans le backend |
Méthode 1 : Protection par mot de passe (Verrouillage rapide)
Pour partager rapidement une documentation d'API avec un nombre restreint de partenaires lors d'une phase de test initiale, la protection par mot de passe offre une barrière immédiate sans nécessiter d'intégration avec un fournisseur d'identité.
Étapes de configuration
- Connectez-vous au tableau de bord Mintlify et ouvrez l'onglet Access.
- Passez le paramètre Visibility de Public à Private.
- Sélectionnez Password dans le menu déroulant Method.
- Définissez un mot de passe robuste et enregistrez avec Save changes.
Compromis techniques
Ce mode s'active en moins de deux minutes, mais tous les utilisateurs partagent le même identifiant. Il ne permet pas d'auditer les actions individuelles, ni de segmenter les droits par rôle. Si un partenariat prend fin, le mot de passe doit être modifié pour l'ensemble des utilisateurs. Ce mécanisme doit donc être réservé aux phases préliminaires de démonstration.
Méthode 2 : SSO d'entreprise et OAuth 2.0 (Fédération d'identité)
Pour les portails internes ou les espaces documentaires destinés à de grands comptes d'entreprise, fédérer l'accès via SAML 2.0 ou OAuth 2.0 garantit la conformité avec les politiques de sécurité et permet une révocation centralisée des accès.
Configuration avec Okta SAML 2.0
- Récupérer les coordonnées Mintlify : Dans le tableau de bord Mintlify, accédez à la page Security, cliquez sur Configure et sélectionnez Okta SAML. Copiez la Single sign on URL (URL ACS) et l'Audience URI (SP Entity ID).
- Créer l'application SAML dans Okta : Dans la console d'administration Okta, allez dans Applications > Create App Integration > SAML 2.0 et collez l'URL et l'URI fournies par Mintlify.
- Configurer les déclarations d'attributs : Renseignez les attributs requis par Mintlify :
firstName->user.firstNamelastName->user.lastNameName->user.email(avec le format Name ID configuré surEmailAddress).
- Lier les métadonnées : Copiez la Metadata URL générée par Okta, collez-la dans le champ correspondant sur Mintlify et validez avec Save changes.
Dès l'activation, toute personne tentant d'accéder au domaine de documentation sera redirigée vers la passerelle d'authentification de l'entreprise avant de pouvoir consulter les schémas d'API.
Méthode 3 : Authentification personnalisée par JWT (Connexion transparente)
Sur les plateformes SaaS commerciales, les développeurs partenaires sont déjà connectés à votre console principale. Pour leur éviter une double authentification lorsqu'ils accèdent à la documentation privée, Mintlify propose une passerelle par jetons JWT signés asymétriquement.
Schéma d'interaction
Navigateur utilisateur Backend de votre application Documentation Mintlify
| | |
| 1. Clic sur "Documentation API" | |
|---------------------------------->| |
| | 2. Génère le payload et signe |
| | le JWT avec clé privée ES256 |
| 3. Redirige vers la documentation | |
| https://docs.example.com/#JWT | |
|<----------------------------------| |
| |
| 4. Requête la page avec le JWT dans le fragment d'URL (Hash) |
|------------------------------------------------------------------------>|
| | 5. Valide la signature ES256, |
| | applique les groupes et efface |
| | le Hash de l'historique |
| 6. Affiche les endpoints privés et pré-remplit le Playground |
|<------------------------------------------------------------------------|
Mise en œuvre
- Dans le tableau de bord Mintlify, allez dans les paramètres Access (ou Personalization), sélectionnez JWT et renseignez l'URL de connexion de votre application.
- Générez une paire de clés cryptographiques dans le tableau de bord et stockez la clé privée dans votre gestionnaire de secrets (KMS, AWS Secrets Manager).
- Dans votre backend, générez un jeton JWT signé avec l'algorithme
ES256, incluant les droits, la durée de session et les groupes de l'utilisateur :
import jwt from "jsonwebtoken";
// Exemple Node.js de génération du jeton d'accès Mintlify
export function generateMintlifyDocToken(user, partnerAccount) {
const payload = {
// Revendications standards JWT
sub: user.id,
exp: Math.floor(Date.now() / 1000) + 10, // Expiration courte : 10 secondes ou moins
// Durée de validité de la session Mintlify
expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8), // Session locale de 8 heures
// Contexte utilisateur pour le rendu conditionnel MDX
content: {
userId: user.id,
email: user.email,
organization: partnerAccount.name,
plan: partnerAccount.tier // Ex. : "enterprise" ou "growth"
},
// Groupes pour le filtrage de la navigation et des pages
groups: [partnerAccount.tier, "partner-tier-1"],
// Données pour pré-remplir l'API Playground
apiPlaygroundInputs: {
header: {
Authorization: `Bearer ${partnerAccount.ephemeralSandboxKey}`
}
}
};
return jwt.sign(payload, process.env.MINTLIFY_PRIVATE_SIGNING_KEY, {
algorithm: "ES256"
});
}
- Lors de la redirection du client, attachez le jeton JWT en tant que fragment d'URL (Hash) :
Le client web Mintlify intercepte le fragment, valide la signature à l'aide de la clé publique enregistrée, ouvre la session locale et efface immédiatement le fragment de l'URL du navigateur, évitant ainsi toute fuite dans l'historique ou les en-têtes Referer.https://docs.api.example.com/api/v2/private-settlement#eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
Contrôle d'accès basé sur les rôles (RBAC) et verrouillage par page
Une fois l'identité vérifiée, l'équipe d'ingénierie peut cloisonner la documentation selon les niveaux de contrat ou les profils d'utilisateurs.
1. Verrouillage dans le Frontmatter MDX
Définissez les groupes autorisés dans l'en-tête YAML de chaque fichier .mdx sensible :
---
title: "Webhooks de règlement financier"
description: "Spécification des webhooks à haut débit pour partenaires bancaires"
groups: ["enterprise", "fintech-partners"]
---
Si le jeton ou la session de l'utilisateur ne contient pas le groupe spécifié, Mintlify masque automatiquement la page dans la barre de navigation latérale et bloque l'accès direct par URL (erreur 404 ou écran d'accès restreint).
2. Rendu conditionnel dynamique avec userContext
Pour les pages explicatives contenant des sections réservées aux clients de haut niveau, utilisez l'objet userContext :
# Politiques de débit et quotas d'appels
{userContext?.content?.plan === "enterprise" ? (
<Card title="Quota dédié grand compte" icon="shield-check">
Votre formule bénéficie de 10 000 requêtes par seconde avec garantie de SLA 24/7.
</Card>
) : (
<Card title="Quota standard" icon="gauge">
Le plafond standard est de 200 requêtes par minute. Contactez l'équipe commerciale pour une extension.
</Card>
)}
3. Cloisonnement du contenu entre humains et agents IA
Mintlify convertit automatiquement les pages en Markdown pour les outils d'IA. Pour éviter que des consignes internes sensibles ne soient analysées par des robots ou des agents externes, isolez-les avec le composant <Visibility> :
<Visibility for="humans">
<Note>Les clés de production doivent être renouvelées tous les 90 jours depuis votre console client.</Note>
</Visibility>
<Visibility for="agents">
Les requêtes API requièrent un jeton Bearer dans l'en-tête Authorization.
</Visibility>
Sécurisation de l'API Playground interactif
La console interactive de test est l'un des atouts majeurs de Mintlify, mais une configuration négligente peut entraîner la fuite de clés de production ou des altérations de données en direct.
1. Injection sécurisée d'identifiants via apiPlaygroundInputs
Plutôt que d'inviter les développeurs à copier manuellement leurs clés secrètes dans leur navigateur, transmettez des identifiants temporaires de bac à sable via la session :
{
"apiPlaygroundInputs": {
"server": {
"environment": "sandbox"
},
"header": {
"Authorization": "Bearer sbx_partner_9981aef0"
},
"query": {
"version": "2026-10"
}
}
}
Mintlify pré-remplit automatiquement ces valeurs dans les champs d'en-tête et de paramètres lors du chargement de l'interface.
2. Bonnes pratiques de sécurité indispensables
- Orienter par défaut vers des environnements Sandbox : Configurez les URL de serveurs dans
docs.jsonde sorte que le Playground pointe par défaut vers des serveurs mock ou des environnements de test isolés, jamais vers vos bases de données de production. - Ne jamais injecter de clés maîtresses permanentes : Les valeurs transmises dans
apiPlaygroundInputsdoivent être strictement limitées à des jetons de test temporaires. - Utiliser
x-defaultdans OpenAPI pour les modèles : Sur les pages publiques ou protégées par mot de passe sans JWT dynamique, spécifiez des marqueurs de substitution danssecuritySchemes(par exemple,x-default: "VOTRE_CLE_SANDBOX"), sans jamais stocker de vrais secrets dans votre dépôt de code.
Liste de contrôle avant mise en production
- Validation du domaine : La documentation est déployée sur un sous-domaine dédié (
docs.partner.example.com) et non sur un sous-chemin non sécurisable. - Définition du périmètre : Choix validé entre authentification totale (Full) ou partielle (Partial) dans l'onglet Access.
- Protection de la clé privée : La clé de signature ES256 est protégée dans un KMS ou coffre-fort de secrets, hors du code source.
- Durée de vie du jeton : La revendication
expdu JWT est fixée à 10 secondes ou moins pour bloquer les attaques par rejeu. - Attribution des groupes : Les pages et points d'accès réservés sont déclarés avec le champ
groupsdans leur Frontmatter MDX. - Sécurisation du Playground : Les appels de test sont confinés à des environnements sandbox sans impact sur la production.
- Vérification des prévisualisations : Les URL générées lors des Pull Requests sont soumises aux mêmes règles de contrôle d'accès.
En appliquant cette architecture, les équipes d'ingénierie offrent à leurs partenaires une expérience d'intégration interactive et moderne tout en préservant une sécurité sans faille pour leurs API privées.