Authentication setup

Authentication requires users to log in before accessing your content.

You can configure full authentication for all pages or partial authentication where some pages are public and others require authentication.

Authentication is only available for sites hosted on a custom domain or Mintlify subdomain. For example, docs.example.com or example.mintlify.site. Authentication is not supported for sites with a custom subpath. For example, example.com/docs.

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

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 the public property.

Individual pages

To make a page public, add public: true to the page’s frontmatter.

---
title: "Public page"
public: true
---

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.

{
  "navigation": {
    "groups": [
      {
        "group": "Public group",
        "public": true,
        "icon": "play",
        "pages": [
          "quickstart",
          "installation",
          "settings"
        ]
      },
      {
        "group": "Private group",
        "icon": "pause",
        "pages": [
          "private-information",
          "secret-settings"
        ]
      }
    ]
  }
}

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.

{
  "groups": ["admin", "beta-users"],
  "expiresAt": 1735689600
}

Specify which groups can access specific pages using the groups property in frontmatter.

---
title: "Admin dashboard"
groups: ["admin"]
---

Users must belong to at least one of the listed groups to access the page. If a user tries to access a page without the required group, they’ll receive a 404 error.

How groups interact with public pages

• All pages require authentication by default.
• Pages with a groups property are only accessible to authenticated users in those groups.
• Pages without a groups property are accessible to all authenticated users.
• Pages with public: true and no groups property are accessible to everyone.

---
title: "Public guide"
public: true
---

User data format

When using OAuth or JWT authentication, your system returns user data that controls session length, group membership, and content personalization.

type User = {
  host?: string;
  expiresAt?: number;
  groups?: string[];
  content?: Record<string, any>;
  apiPlaygroundInputs?: {
    server?: Record<string, string>;
    header?: Record<string, unknown>;
    query?: Record<string, unknown>;
    cookie?: Record<string, unknown>;
    path?: Record<string, unknown>;
  };
};

Feature availability

Some features behave differently or are unavailable when you enable authentication.