Entwicklungsteams und Plattformarchitekten, die private API- und SDK-Dokumentationen für Unternehmenspartner, Unternehmenskunden oder interne Integrationen bereitstellen, stehen vor einem sicherheitstechnischen Spagat: Einerseits verlangen Integratoren ein interaktives, modernes Entwicklerportal mit funktionsfähigen API-Playgrounds zum direkten Testen; andererseits müssen geschäftskritische Abrechnungsschnittstellen, interne Administrationsendpunkte und proprietäre SDKs strikt vor unberechtigten Zugriffen und öffentlichen Web-Scrapern geschützt werden.
Mintlify löst dieses Problem durch die Verknüpfung seiner MDX- und OpenAPI-gestützten Engine mit vier klar definierten Zugriffskontrollmechanismen: interner Organisationszugriff, globaler Passwortschutz, Enterprise Single Sign-On (SSO / OAuth 2.0) und signierte JSON Web Token (JWT)-Authentifizierung. Dieser Leitfaden beschreibt die architektonischen Voraussetzungen, Konfigurationsschritte, gruppenbasierte Berechtigungsstrukturen (RBAC) auf Seitenebene und das sichere automatische Vorbefüllen von Zugangsdaten im API-Playground für Produktionsumgebungen.
Architektonische Voraussetzungen und Domain-Einschränkungen
Bevor Authentifizierungsmethoden eingerichtet werden, müssen technische Teams die Hosting-Vorgaben von Mintlify berücksichtigen:
- Pflicht zur dedizierten Domain: Sowohl die vollständige als auch die partielle Authentifizierung setzt voraus, dass die Dokumentation auf einer dedizierten benutzerdefinierten Domain (z. B.
docs.api.example.com) oder einer Mintlify-Subdomain (example.mintlify.site) gehostet wird. Zugriffsbeschränkungen über Subpfade (z. B.example.com/docs) werden nicht unterstützt. In Subpfad-Setups stehen lediglich Personalisierungsfunktionen ohne strikte Zugriffssperre zur Verfügung. - Umfang der Zugriffskontrolle (Vollständig vs. Partiell): Teams können zwischen einer vollständigen Authentifizierung (Full) (alle Seiten und OpenAPI-Spezifikationen erfordern einen Login) und einer partiellen Authentifizierung (Partial) (öffentliche Schnellstart-Anleitungen bleiben frei zugänglich, vertrauliche Endpunkte werden gesperrt) wählen.
- Sicherheit bei Preview-Deployments: Bei Git-basierten Workflows können Pull-Request-Vorschau-Deployments sensible Schnittstellen versehentlich exponieren. Nach Aktivierung der Authentifizierung im Mintlify-Dashboard werden sämtliche Vorschauzweige automatisch durch denselben Schutzmechanismus gesichert.
Vergleich der Authentifizierungsmethoden
| Methode | Bester Einsatzzweck | Erforderlicher Tarif | Gruppenbasiertes RBAC | Playground-Vorbefüllung | Reichweite des Benutzerwiderrufs |
|---|---|---|---|---|---|
| Organisations-Auth (Private) | Interne Entwicklerteams und unternehmensinterne Wikis | Alle Tarife | Nein | Nein | Entfernen von Mitgliedern in der Mintlify-Organisation |
| Passwortschutz (Password) | Frühe geschlossene Betaphasen, NDA-Prüfungen | Pro oder Enterprise | Nein | Nein | Portalweite Passwortänderung erforderlich |
| Enterprise SSO (OAuth 2.0 / SSO) | Unternehmensweite Identitätsföderation (Okta, Entra ID, Google) | Enterprise | Ja | Ja | Sofortige Deaktivierung im unternehmenseigenen IdP |
| JWT-Authentifizierung | Nahtlos in bestehende SaaS-Webanwendungen eingebettete Portale | Enterprise | Ja | Ja | Kurzlebige Token-Abläufe und Kontrolle im eigenen Backend |
Methode 1: Passwortschutz (Schnelle, leichtgewichtige Barriere)
Wenn Schnittstellendokumentationen im Rahmen geschlossener Vorabtests oder vertraulicher Evaluierungen schnell gesichert werden müssen, bietet der Passwortschutz eine unkomplizierte Lösung ohne IdP-Anbindung.
Konfigurationsschritte
- Öffnen Sie das Mintlify Dashboard und wählen Sie den Reiter Access.
- Ändern Sie Visibility von Public auf Private.
- Wählen Sie als Method die Option Password.
- Geben Sie ein sicheres, kryptografisch starkes Passwort ein und klicken Sie auf Save changes.
Grenzen und architektonische Abwägungen
Das Setup dauert weniger als zwei Minuten, birgt jedoch erhebliche Nachteile für den Regelbetrieb: Alle Partner teilen sich denselben Schlüssel, Benutzeraktivitäten lassen sich nicht individuell protokollieren, und verlässt ein Partner das Projekt, muss das Passwort für alle Parteien neu vergeben werden. Diese Methode sollte auf reine Übergangsphasen beschränkt bleiben.
Methode 2: Enterprise SSO und OAuth 2.0 (Identitätsföderation)
Für interne Entwicklerportale oder dedizierte Partnerzugänge für Großkunden stellt die Anbindung an SAML 2.0 oder OAuth 2.0 sicher, dass Governance-Vorgaben eingehalten werden und Zugriffsrechte beim Ausscheiden von Mitarbeitern automatisch erlöschen.
Einrichtung von Okta SAML 2.0
- Mintlify-Endpunkte abrufen: Navigieren Sie im Mintlify-Dashboard zu Security, klicken Sie auf Configure und wählen Sie Okta SAML. Kopieren Sie die angezeigte Single sign on URL (ACS-URL) und die Audience URI (SP Entity ID).
- SAML-Anwendung in Okta erstellen: Öffnen Sie die Okta Admin Console unter Applications > Create App Integration > SAML 2.0 und fügen Sie die kopierte URL und URI ein.
- Attribut-Statements zuweisen: Konfigurieren Sie die von Mintlify geforderten Attribute:
firstName->user.firstNamelastName->user.lastNameName->user.email(mit Name-ID-FormatEmailAddress).
- Metadaten verknüpfen: Kopieren Sie die Metadata URL aus Okta, tragen Sie diese im Mintlify-Dashboard ein und speichern Sie mit Save changes.
Nach der Aktivierung werden Anfragen an die Dokumentationsdomain automatisch an den Unternehmens-IdP weitergeleitet, bevor geschützte Schnittstellendetails geladen werden.
Methode 3: JWT-basierte Authentifizierung (Nahtlose Anbindung an die eigene App)
In modernen SaaS- und Entwicklerplattformen sind Partner bereits in Ihrem zentralen Kunden-Dashboard eingeloggt. Um einen redundanten zweiten Login zu vermeiden, ermöglicht Mintlify eine nahtlose Sitzungsübergabe mittels asymmetrisch signierter JSON Web Tokens (JWT).
Architekturablauf
Benutzer (Browser) Eigenes Anwendungs-Backend Mintlify Dokumentation
| | |
| 1. Klick auf "API-Referenz" | |
|---------------------------------->| |
| | 2. Erstellt Payload mit Rechten |
| | und signiert JWT mit ES256 |
| 3. Leitet zu Dokumentations-URL | |
| https://docs.example.com/#JWT | |
|<----------------------------------| |
| |
| 4. Ruft Dokumentationsseite mit JWT im URL-Fragment (Hash) auf |
|------------------------------------------------------------------------>|
| | 5. Prüft ES256-Signatur, |
| | setzt Gruppen, bereinigt Hash |
| 6. Rendert private Endpunkte und vorbefüllten Playground |
|<------------------------------------------------------------------------|
Implementierungsschritte
- Wählen Sie im Mintlify-Dashboard unter Access (oder Personalization) die Methode JWT und hinterlegen Sie die Login-URL Ihrer Hauptanwendung.
- Generieren Sie ein Schlüsselpaar im Dashboard und speichern Sie den privaten Schlüssel sicher in Ihrem Secret-Manager oder KMS.
- Erstellen Sie im Backend-Dienst ein JWT mit dem Algorithmus
ES256, das Benutzeransprüche, Sitzungsdauer und Gruppenberechtigungen enthält:
import jwt from "jsonwebtoken";
// Beispiel in Node.js zur Signierung von Mintlify-Tokens
export function generateMintlifyDocToken(user, partnerAccount) {
const payload = {
// Standard-JWT-Claims
sub: user.id,
exp: Math.floor(Date.now() / 1000) + 10, // Kurze Gültigkeit: 10 Sekunden oder weniger
// Gültigkeitsdauer der lokalen Mintlify-Sitzung
expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8), // 8 Stunden Sitzungsdauer
// Benutzerdaten für bedingtes Rendering in MDX
content: {
userId: user.id,
email: user.email,
organization: partnerAccount.name,
plan: partnerAccount.tier // z. B. "enterprise" oder "fintech-partner"
},
// Berechtigungsgruppen für Navigationsfilter und Zugriffssperren
groups: [partnerAccount.tier, "partner-tier-1"],
// Anmeldedaten für den interaktiven API-Playground
apiPlaygroundInputs: {
header: {
Authorization: `Bearer ${partnerAccount.ephemeralSandboxKey}`
}
}
};
return jwt.sign(payload, process.env.MINTLIFY_PRIVATE_SIGNING_KEY, {
algorithm: "ES256"
});
}
- Leiten Sie den Browser des Partners mit dem signierten JWT als URL-Fragment (Hash) weiter:
Der Mintlify-Webclient extrahiert das Token clientseitig, verifiziert die Signatur gegen den hinterlegten öffentlichen Schlüssel, etabliert die Nutzersitzung und entfernt den Hash umgehend aus der Adresszeile, um ein Abfangen über den Browserverlauf oder Referrer-Header auszuschließen.https://docs.api.example.com/api/v2/private-settlement#eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
Rollenbasierte Zugriffskontrolle (RBAC) und Absicherung einzelner Seiten
Sobald die Identität verifiziert ist, können Entwicklungsteams die Sichtbarkeit von Inhalten exakt nach Partnerverträgen und Berechtigungsstufen steuern.
1. Absicherung im MDX-Frontmatter
Definieren Sie berechtigte Gruppen im YAML-Header der jeweiligen .mdx-Dateien:
---
title: "Clearing- und Abrechnungs-Webhooks"
description: "Hochvolumige Zahlungs-Webhooks für strategische Finanzpartner"
groups: ["enterprise", "fintech-partners"]
---
Fehlt der entsprechende Gruppeneintrag im Token des Benutzers, blendet Mintlify die Seite vollständig aus der Navigation aus und blockiert direkte Zugriffe mit einem Zugriffsfehler (404 oder Sperrhinweis).
2. Dynamisches Rendering in MDX mit userContext
Um auf allgemeinen Informationsseiten selektiv Zusatzinformationen anzuzeigen, lässt sich userContext direkt im MDX-Code einbinden:
# Durchsatz- und Ratenbegrenzungsrichtlinien
{userContext?.content?.plan === "enterprise" ? (
<Card title="Exklusive Partner-Bandbreite" icon="shield-check">
Ihr Tarif beinhaltet dedizierte 10.000 Anfragen pro Sekunde mit 24/7-SLA-Garantie.
</Card>
) : (
<Card title="Standard-Ratenbegrenzung" icon="gauge">
Das Standard-Limit beträgt 200 Anfragen pro Minute. Wenden Sie sich an den Vertrieb für ein Upgrade.
</Card>
)}
3. Trennung von Inhalten für Menschen und KI-Agenten
Mintlify optimiert Dokumente standardmäßig als Markdown für KI-Agenten und LLMs. Um vertrauliche Implementierungsdetails vor Web-Scrapern zu verbergen, nutzen Sie die <Visibility>-Komponente:
<Visibility for="humans">
<Note>Produktionsschlüssel müssen alle 90 Tage über das Partnerportal erneuert werden.</Note>
</Visibility>
<Visibility for="agents">
API-Anfragen erfordern ein Bearer-Token im Authorization-Header.
</Visibility>
Sicherheitsarchitektur für den interaktiven API-Playground
Der interaktive API-Playground gehört zu den herausragenden Stärken von Mintlify, birgt bei unachtsamer Konfiguration jedoch erhebliche Risiken, wie das versehentliche Offenlegen von Produktivschlüsseln.
1. Dynamische Schlüsselübergabe mit apiPlaygroundInputs
Statt Entwickler aufzufordern, sensible Tokens manuell in das Browserfenster zu kopieren, übergeben Sie über die Authentifizierungssitzung kurzlebige Sandbox-Schlüssel:
{
"apiPlaygroundInputs": {
"server": {
"environment": "sandbox"
},
"header": {
"Authorization": "Bearer sbx_partner_9981aef0"
},
"query": {
"version": "2026-10"
}
}
}
Beim Laden der Seite bindet Mintlify diese Parameter automatisch an die entsprechenden Header- und Abfragefelder.
2. Grundlegende Sicherheitsrichtlinien
- Standardmäßig auf Sandbox-Server verweisen: Definieren Sie Server-URLs in der
docs.jsonso, dass Testaufrufe standardmäßig isolierte Mock- oder Testinstanzen ansprechen und nicht auf Produktivdatenbanken zugreifen. - Keine dauerhaften Hauptschlüssel übergeben: Anmeldedaten im Parameter
apiPlaygroundInputsmüssen zeitlich eng befristet und auf unkritische Testrechte beschränkt sein. - OpenAPI
x-defaultfür Platzhalter nutzen: In Seiten ohne dynamisches JWT sollten Platzhalter über das OpenAPI-Feldx-default(z. B.x-default: "IHR_SANDBOX_SCHLUESSEL") definiert werden, um echten Schlüsselcode im Repository zu vermeiden.
Checkliste vor dem Produktivgang
- Domain-Setup geprüft: Dokumentation läuft auf einer separaten Subdomain (
docs.partner.example.com) statt auf einem nicht geschützten Subpfad (/docs). - Gating-Umfang festgelegt: Im Dashboard unter Access wurde klar zwischen vollständiger (Full) oder partieller (Partial) Authentifizierung gewählt.
- Schlüsselsicherheit garantiert: Der private ES256-Signaturschlüssel liegt gesichert im KMS und wurde nicht ins Git-Repository eingecheckt.
- Kurze Token-Laufzeiten: Der JWT-Claim
expist auf höchstens 10 Sekunden limitiert, um Replay-Angriffe zu verhindern. - Gruppen im Frontmatter hinterlegt: Alle privaten Endpunkte sind in ihren MDX-Dateien mit zutreffenden
groups-Tags versehen. - Playground abgesichert: Die Standardaufrufe des interaktiven Testers zielen auf geschützte Sandbox-Umgebungen ab.
- Preview-Deployments überprüft: PR-Vorschau-Links unterliegen denselben Authentifizierungsbarrieren wie die Hauptdokumentation.
Mit dieser Architektur bieten technische Plattformteams ihren Partnern ein hervorragendes interaktives Dokumentationserlebnis und wahren gleichzeitig lückenlose Zero-Trust-Sicherheitsstandards für ihre privaten Programmierschnittstellen.