Authentication setup - Mintlify

Prerequisites

• Your security requirements allow sharing passwords among users.

Set up

Example

You host your documentation at docs.foo.com and you need basic access control without tracking individual users. You want to prevent public access while keeping setup simple.Create a strong password in your dashboard. Share credentials with authorized users.

Prerequisites

• Everyone who needs to access your documentation must be a member of your Mintlify organization.

Set up

Example

You host your documentation at docs.foo.com and your entire team has access to your dashboard. You want to restrict access to team members only.Enable Mintlify authentication in your dashboard settings.Verify team access by checking that all team members are active in your organization.

Prerequisites

• An OAuth or OIDC server that supports the Authorization Code Flow.
• Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable group-based access control).

Set up

Example

You host your documentation at foo.com/docs and you have an existing OAuth server at auth.foo.com that supports the Authorization Code Flow.Configure your OAuth server details in your dashboard:

• Authorization URL: https://auth.foo.com/authorization
• Client ID: ydybo4SD8PR73vzWWd6S0ObH
• Scopes: ['provider.users.docs']
• Token URL: https://auth.foo.com/exchange
• Info API URL: https://api.foo.com/docs/user-info
• Logout URL: https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs

Create a user info endpoint at api.foo.com/docs/user-info, which requires an OAuth access token with the provider.users.docs scope, and returns:

{
  "groups": ["engineering", "admin"],
  "expiresAt": 1735689600,
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

Configure your OAuth server to allow redirects to your callback URL.

Prerequisites

• An authentication system that can generate and sign JWTs.
• A backend service that can create redirect URLs.

Set up

Example

You host your documentation at docs.foo.com with an existing authentication system at foo.com. You want to extend your login flow to grant access to the docs while keeping your docs separate from your dashboard (or you don’t have a dashboard).Create a login endpoint at https://foo.com/docs-login that extends your existing authentication.After verifying user credentials:

• Generate a JWT with user data in Mintlify’s format.
• Sign the JWT and redirect to https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}.

Redirect unauthenticated users

When an unauthenticated user tries to access a protected page, the redirect to your login URL preserves the user’s intended destination.

1. User attempts to visit a protected page: https://docs.foo.com/quickstart.
2. Redirect to your login URL with a redirect query parameter: https://foo.com/docs-login?redirect=%2Fquickstart.
3. After authentication, redirect to https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}.
4. User lands in their original destination.