Private authentication for your Mintlify organization is available on all plans.Password authentication requires a Pro or Enterprise plan.OAuth and JWT authentication require an Enterprise plan.
docs.example.com or example.mintlify.site. Authentication is not supported for sites with a custom subpath. For example, example.com/docs.
When you turn on authentication, you can delete existing preview deployments that would otherwise stay publicly accessible. See Existing previews when you turn on authentication.
To identify visitors while keeping pages public, use personalization. Personalization supports custom subpaths and can prefill API playground inputs without requiring visitors to authenticate before viewing a page.
Choose an authentication method
Use this comparison to pick the method that fits your use case. See Feature availability for how each method interacts with other Mintlify features.Configure authentication
- Password
- Private authentication
- OAuth 2.0
- JWT
Password authentication provides access control only and does not support user-specific features like group-based access control or API playground prefilling.
Password prerequisites
- Your security requirements allow sharing passwords among users.
Password setup
1
Create a password.
- In your dashboard, go to Access.
- Set Visibility to Private.
- Set Method to Password.
- Enter a secure password.
- Click Save.
2
Distribute access.
Securely share the password and documentation URL with authorized users.
Password example
You host your documentation atdocs.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.Make pages public
When using authentication, all pages require authentication to access by default. You can make specific pages viewable without authentication at the page or group level with thepublic property.
Individual pages
To make a page public, addpublic: true to the page’s frontmatter.
Public page example
Groups of pages
To make all pages in a group public, add"public": true beneath the group’s name in the navigation object of your docs.json.
Public group example
Control access with groups
When you use OAuth or JWT authentication, you can restrict specific pages to certain user groups. This is useful when you want different users to see different content based on their role or attributes. Manage groups through user data passed during authentication. See User data format for details.Example user info
groups property in frontmatter.
Example page restricted to the admin group
groups for sensitive content.
How groups interact with public pages
- All pages require authentication by default.
- Pages with a
groupsproperty are only accessible to authenticated users in those groups. - Pages without a
groupsproperty are accessible to all authenticated users. - Pages with
public: trueand nogroupsproperty are accessible to everyone.
User data format
When using OAuth or JWT authentication or standalone personalization, your system returns user data that controls session length, group membership, and content personalization.string
Required for JWT authentication. The hostname of your documentation site. The string must exactly match the domain where you deploy your documentation. Mintlify validates that the JWT’s host matches the requesting host to prevent token reuse across different sites.
number
Session expiration time in seconds since epoch. When the current time passes this value, Mintlify expires the stored user data. The visitor must authenticate again or repeat the identification flow to refresh it.
string[]
List of groups the user belongs to. With authentication, pages with matching
groups in their frontmatter are accessible to this user. With standalone personalization, groups control page and content visibility but do not restrict access to a page’s direct URL.Example: A user with groups: ["admin", "engineering"] matches content tagged with either the admin or engineering groups.Record<string, any>
Custom data accessible in MDX pages via the
user variable for personalized content.object
Prefills API playground fields with user-specific values. When a user authenticates, these values populate the corresponding input fields in the API playground. Users can override prefilled values, and their overrides persist in local storage.Mintlify applies only values that match the current endpoint’s security scheme.