How to Configure Gated Access and User Authentication in Mintlify for Private API Documentation

Engineering teams and developer platform architects building private API documentation face a delicate security balancing act: enterprise clients and integration partners expect an interactive, modern developer portal with functional API playgrounds, but core endpoints, proprietary SDKs, and billing interfaces must remain strictly isolated from public scrapers and unauthorized users.

Mintlify resolves this friction by pairing its MDX- and OpenAPI-driven developer engine with four access control mechanisms: organization-internal protection, shared password gating, Enterprise Single Sign-On (SSO / OAuth 2.0), and signed JSON Web Token (JWT) authentication. This guide walks through the architectural requirements, configuration workflows, page-level group permissions, and secure API playground pre-filling necessary to implement production-grade private documentation.

Architectural Prerequisites and Hosting Constraints

Before configuring authentication methods, engineering teams must align on how Mintlify serves gated content:

1. Domain Isolation Requirements: Full and partial user authentication requires documentation to be hosted on a dedicated custom domain (such as docs.api.example.com) or a Mintlify subdomain (example.mintlify.site). Gated authentication is not supported on custom subpaths (such as example.com/docs). Teams requiring subpath deployments must rely on client-side personalization rather than strict access gating.
2. Access Scope (Full vs. Partial): Teams can enforce Full Authentication (locking down every page and OpenAPI schema behind a mandatory login barrier) or Partial Authentication (keeping getting-started guides and public SDKs open while restricting enterprise endpoints and internal modules).
3. Preview Deployment Security: In Git-driven documentation workflows, pull request preview branches can unintentionally expose private endpoints if left unsecured. Enabling portal-wide authentication automatically applies protection to deployment previews.

Authentication Methods: Comparison Matrix

Method 1: Password Protection (Lightweight Gating)

Password protection provides an immediate barrier for early-stage customer pilots or confidential staging reviews without requiring identity provider synchronization.

Setup Workflow

1. Navigate to your project dashboard at Mintlify Dashboard and select the Access tab.
2. Change Visibility from Public to Private.
3. Set Method to Password.
4. Enter a cryptographically strong shared secret and click Save changes.

Trade-offs and Best Practices

While setup takes less than two minutes, password protection shares a single credential across all recipients. You cannot audit individual user activity, apply role-based access to specific API endpoints, or revoke access for a single departing contractor without changing the password for all partners. Use password protection strictly for pre-release milestones, not production-tier customer portals.

Method 2: Enterprise SSO and OAuth 2.0 (Identity Federation)

For internal engineering docs or dedicated B2B enterprise partner portals, federating authentication via SAML 2.0 or OAuth 2.0 ensures compliance, automated user onboarding, and immediate deprovisioning.

Step-by-Step Okta SAML Integration

1. Retrieve Mintlify Endpoints: In the Mintlify dashboard, navigate to the Security page, select Configure, and choose Okta SAML. Copy the generated Single sign on URL (ACS URL) and Audience URI (SP Entity ID).
2. Create SAML App in Identity Provider: In the Okta Admin Console, navigate to Applications > Create App Integration > SAML 2.0. Paste Mintlify’s Single sign-on URL and Audience URI.
3. Map User Attribute Statements: Configure the SAML response attributes required by Mintlify:
   • firstName -> user.firstName
   • lastName -> user.lastName
   • Name (or email identifier) -> user.email with Name ID format set to EmailAddress.
4. Complete Connection: Download or copy your IdP Metadata URL from Okta, paste it into Mintlify’s Metadata URL field, and click Save changes.

Once enabled, visitors landing on your documentation domain are redirected through your corporate IdP before viewing API specifications or MDX guides.

Method 3: JWT-Based Authentication (Custom App Login)

When building documentation for paying SaaS customers or registered API partners, users should not encounter a separate login prompt. Mintlify’s JWT authentication lets your primary application backend sign visitor session data and transition users into the private documentation portal seamlessly.

Architectural Flow

User (Browser)               Your Application Backend               Mintlify Documentation
      |                                   |                                     |
      | 1. Logs in / clicks "API Docs"     |                                     |
      |---------------------------------->|                                     |
      |                                   | 2. Generates payload & signs JWT    |
      |                                   |    using ES256 private key           |
      | 3. Redirects to doc portal        |                                     |
      |    https://docs.example.com/#JWT  |                                     |
      |<----------------------------------|                                     |
      |                                                                         |
      | 4. Requests doc page with JWT in URL fragment                           |
      |------------------------------------------------------------------------>|
      |                                   | 5. Verifies ES256 signature,        |
      |                                   |    extracts claims & groups,         |
      |                                   |    clears hash from URL history     |
      | 6. Renders gated private endpoints & prefilled playground               |
      |<------------------------------------------------------------------------|

Configuration Steps

1. In your Mintlify dashboard, navigate to the Access (or Personalization) settings, select JWT, and provide your application's primary login URL.
2. Generate a dedicated cryptographic keypair in the dashboard and securely save the private signing key in your application's secrets manager.
3. In your backend service, construct a signed JWT using the ES256 algorithm containing user claims, group memberships, and token longevity:

import jwt from "jsonwebtoken";

// Node.js example signing Mintlify authentication payload
export function generateMintlifyDocToken(user, partnerAccount) {
  const payload = {
    // Standard JWT claims
    sub: user.id,
    exp: Math.floor(Date.now() / 1000) + 10, // Short expiration: 10 seconds or less
    
    // Mintlify session expiration timestamp
    expiresAt: Math.floor(Date.now() / 1000) + (60 * 60 * 8), // 8-hour portal session
    
    // Custom user context for conditional rendering
    content: {
      userId: user.id,
      email: user.email,
      organization: partnerAccount.name,
      plan: partnerAccount.tier // e.g., "enterprise" or "growth"
    },
    
    // Role-Based Access Control groups for navigation & page gating
    groups: [partnerAccount.tier, "partner-tier-1"],
    
    // Scoped credentials for interactive API testing
    apiPlaygroundInputs: {
      header: {
        Authorization: `Bearer ${partnerAccount.ephemeralSandboxKey}`
      }
    }
  };

  return jwt.sign(payload, process.env.MINTLIFY_PRIVATE_SIGNING_KEY, {
    algorithm: "ES256"
  });
}

4. When the authenticated partner clicks "Private API Reference", redirect their browser to your docs with the signed JWT appended as a URL fragment:

   https://docs.api.example.com/api/v2/settlement-endpoints#eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
   

   Mintlify extracts the token from the URL fragment in the client, validates the signature against the registered public key, initializes the local session, and immediately strips the hash from the browser address bar to prevent shoulder surfing or referrer leakage.

Role-Based Access Control (RBAC) and Page-Level Gating

Once identity is verified via OAuth or JWT, engineering teams must partition sensitive internal APIs from general developer documentation.

1. Frontmatter Page Gating

Assign target audience groups in the YAML frontmatter of individual .mdx files:

---
title: "Partner Settlement Webhooks"
description: "Core financial webhooks and high-throughput settlement endpoints"
groups: ["enterprise", "fintech-partners"]
---

When a user visits the portal, Mintlify matches their session groups against page frontmatter. Users lacking the matching group are denied access and the page is omitted from navigation.

2. In-Page Conditional Rendering with userContext

For pages that share general instructions but contain restricted endpoints, use the userContext object directly inside MDX:

# Enterprise Rate Limiting Policy

{userContext?.content?.plan === "enterprise" ? (
  <Card title="Dedicated Partner Quota" icon="shield-check">
    Your tier receives 10,000 requests per second with dedicated SLA support.
  </Card>
) : (
  <Card title="Standard Rate Quota" icon="gauge">
    Standard tier access is throttled at 200 requests per minute. Contact enterprise sales to upgrade.
  </Card>
)}

3. Human vs. Agent Content Segregation

Mintlify documentation portals automatically expose Markdown representations to AI agents and LLM tooling. To prevent proprietary implementation guidelines from leaking into agent scraping outputs, wrap sensitive elements with the <Visibility> component:

<Visibility for="humans">
  <Note>Production partner credentials must be rotated every 90 days via your enterprise dashboard.</Note>
</Visibility>

<Visibility for="agents">
  Authentication requires a Bearer token passed in the Authorization header.
</Visibility>

Securing the Interactive API Playground

Mintlify’s interactive API playground lets developers test requests directly from the browser. In private documentation, testing live endpoints presents two critical security hazards: exposing production master API keys or leaking sensitive partner data.

1. Dynamic Header Injection via apiPlaygroundInputs

Rather than asking engineers to copy-paste authorization keys into the browser, supply scoped credentials through the authentication session:

{
  "apiPlaygroundInputs": {
    "server": {
      "environment": "sandbox"
    },
    "header": {
      "Authorization": "Bearer sbx_partner_9981aef0"
    },
    "query": {
      "version": "2026-10"
    }
  }
}

Mintlify automatically injects these values into corresponding request headers and parameters when the playground initializes.

2. Mandatory Playground Security Guidelines

• Enforce Sandbox and Mock Environments: Configure OpenAPI server URLs in docs.json so the playground defaults to isolated mock servers or developer sandboxes rather than production clusters.
• Never Inject Long-Lived Master Keys: Generate ephemeral, client-scoped tokens with granular permissions that expire concurrently with the documentation session.
• Utilize OpenAPI x-default for Placeholders: If using password protection or partial authentication without dynamic user sessions, define generic placeholder templates in your OpenAPI securitySchemes (e.g., x-default: "YOUR_PARTNER_SANDBOX_KEY") so private tokens are never committed to code repositories.

Production Rollout Checklist

• Domain Architecture: Verified documentation is mapped to a dedicated subdomain (docs.partner.example.com) rather than a subpath.
• Authentication Enforcement: Selected Full vs. Partial gating in the Access dashboard according to customer visibility needs.
• Signing Key Security: Private ES256 signing keys are stored in a dedicated KMS or secret vault, not in git repositories.
• Short Token Lifetimes: JWT exp claims are clamped to 10 seconds or less to minimize replay attack windows.
• Frontmatter Group Auditing: All internal and high-tier endpoints are decorated with explicit groups: [...] tags.
• Playground Scoping: Verified apiPlaygroundInputs injects mock or sandbox credentials exclusively.
• Preview Isolation: Confirmed pull request deployments inherit access policies to prevent staging leaks.

Following this architecture enables engineering teams to provide partners with high-converting, interactive documentation while maintaining rigorous zero-trust perimeter control over private APIs and SDKs.

References

• Authentication setup - Mintlify
• SSO - Mintlify
• Personalized content - Mintlify