From 1ab2457765e9f0c8bc7418e4058ff0a0be3d30d1 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:50:01 +0000 Subject: [PATCH 1/8] Update deploy/authentication-setup.mdx --- deploy/authentication-setup.mdx | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index 5e4313b24..d42e5862b 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -5,22 +5,18 @@ keywords: ['authentication', 'auth', 'OAuth', 'JWT', 'password'] --- - [Pro plans](https://mintlify.com/pricing?ref=authentication) include password authentication. - - [Custom plans](https://mintlify.com/pricing?ref=authentication) include all authentication methods. + [Pro plans](https://mintlify.com/pricing?ref=authentication) include password authentication. [Custom plans](https://mintlify.com/pricing?ref=authentication) include all authentication methods. -Authentication requires users to log in before accessing your documentation. +Require users to log in before accessing your documentation. ## Authentication modes -Choose between full and partial authentication modes based on your access control needs. - -**Full authentication**: All pages are protected. Users must log in before accessing any content. +**Full authentication**: All pages require login. -**Partial authentication**: Some pages are publicly viewable while others require authentication. Users can browse public content freely and authenticate only when accessing protected pages. +**Partial authentication**: Some pages are public, others require login. -When configuring any handshake method below, you'll select either **Full authentication** or **Partial authentication** in your dashboard settings. +Select your mode when configuring any method below. ## Configure authentication From 7ad2d9030c481b26324acbe709188ac9f8d74d06 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:50:11 +0000 Subject: [PATCH 2/8] Update deploy/authentication-setup.mdx --- deploy/authentication-setup.mdx | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index d42e5862b..fb12547f5 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -25,33 +25,20 @@ Select the handshake method that you want to configure. -Password authentication provides access control only and does **not** support content personalization. +Password authentication does **not** support content personalization. -### Prerequisites - -* Your security requirements allow sharing passwords among users. - -### Implementation - - - 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + + 1. Go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). 2. Select **Full Authentication** or **Partial Authentication**. - 3. Select **Password**. - 4. Enter a secure password. - 5. Select **Save changes**. + 3. Select **Password** and enter a secure password. + 4. Select **Save changes**. - - Securely share the password and documentation URL with authorized users. + + Share the password and documentation URL with authorized users. - -### Example - -Your documentation is hosted 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. That's it! ### Prerequisites From 5b3d5ae28f107e2564049bc212bb78794b43a492 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:50:21 +0000 Subject: [PATCH 3/8] Update deploy/authentication-setup.mdx --- deploy/authentication-setup.mdx | 28 ++++++---------------------- 1 file changed, 6 insertions(+), 22 deletions(-) diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index fb12547f5..8f7be3a93 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -41,33 +41,17 @@ Password authentication does **not** support content personalization. -### Prerequisites - -* Everyone who needs to access your documentation must be a member of your Mintlify organization. - -### Implementation - - - 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + + 1. Go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). 2. Select **Full Authentication** or **Partial Authentication**. - 3. Select **Mintlify Auth**. - 4. Select **Enable Mintlify Auth**. + 3. Select **Mintlify Auth** and enable it. - - 1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members). - 2. Add each person who should have access to your documentation. - 3. Assign appropriate roles based on their editing permissions. + + 1. Go to [Members](https://dashboard.mintlify.com/settings/organization/members). + 2. Add users who need access and assign roles. - -### Example - -Your documentation is hosted 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 added to your organization. ### Prerequisites From 9c0aac4d5b605e8552a5223f5313f191c55dd297 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:50:47 +0000 Subject: [PATCH 4/8] Update deploy/authentication-setup.mdx --- deploy/authentication-setup.mdx | 57 +++++++++------------------------ 1 file changed, 16 insertions(+), 41 deletions(-) diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index 8f7be3a93..23a147655 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -54,55 +54,32 @@ Password authentication does **not** support content personalization. -### 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 personalization features). - -### Implementation - - - 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + + 1. Go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). 2. Select **Full Authentication** or **Partial Authentication**. - 3. Select **OAuth** and configure these fields: - * **Authorization URL**: Your OAuth endpoint. - * **Client ID**: Your OAuth 2.0 client identifier. - * **Client Secret**: Your OAuth 2.0 client secret. - * **Scopes**: Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Use multiple scopes if you need different access levels. - * **Token URL**: Your OAuth token exchange endpoint. - * **Info API URL** (optional): Endpoint on your server that Mintlify calls to retrieve user info for personalization. If omitted, the OAuth flow will only be used to verify identity and the user info will be empty. - * **Logout URL**: The native logout URL for your OAuth provider. If your provider has a `returnTo` or similar parameter, point it back to your docs URL. + 3. Select **OAuth** and configure: + * **Authorization URL**: Your OAuth endpoint + * **Client ID**: Your OAuth 2.0 client identifier + * **Client Secret**: Your OAuth 2.0 client secret + * **Scopes**: Permissions to request (copy the entire scope string) + * **Token URL**: Your OAuth token exchange endpoint + * **Info API URL** (optional): Endpoint for user info personalization + * **Logout URL**: Your OAuth provider's logout URL 4. Select **Save changes**. - - 1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). - 2. Add the redirect URL as an authorized redirect URL for your OAuth server. + + 1. Copy the **Redirect URL** from [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Add it as an authorized redirect URL in your OAuth server. - - To enable personalization features, create an API endpoint that: - * Accepts OAuth access tokens for authentication. - * Returns user data in the `User` format. See [User data format](/deploy/personalization-setup#user-data-format) for more information. - - Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). + + For personalization, create an endpoint that accepts OAuth access tokens and returns user data in the [User format](/deploy/personalization-setup#user-data-format). ### Example -Your documentation is hosted 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: - -```json +```json User info endpoint response { "content": { "firstName": "Jane", @@ -111,8 +88,6 @@ Your documentation is hosted at `foo.com/docs` and you have an existing OAuth se "groups": ["engineering", "admin"] } ``` - -**Configure your OAuth server to allow redirects** to your callback URL. ### Prerequisites From 4f1a6f9f9d3101585d70a2d37fa230f292564973 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:51:03 +0000 Subject: [PATCH 5/8] Update deploy/authentication-setup.mdx --- deploy/authentication-setup.mdx | 36 +++++++++------------------------ 1 file changed, 9 insertions(+), 27 deletions(-) diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index 23a147655..f822372c1 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -90,41 +90,23 @@ Password authentication does **not** support content personalization. ``` -### Prerequisites - -* An authentication system that can generate and sign JWTs. -* A backend service that can create redirect URLs. - -### Implementation - - - 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + + 1. Go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). 2. Select **Full Authentication** or **Partial Authentication**. - 3. Select **JWT**. - 4. Enter the URL of your existing login flow and select **Save changes**. - 5. Select **Generate new key**. - 6. Store your key securely where it can be accessed by your backend. + 3. Select **JWT** and enter your login flow URL. + 4. Select **Generate new key** and store it securely. - - Modify your existing login flow to include these steps after user authentication: - - * Create a JWT containing the authenticated user's info in the `User` format. See [User data format](/deploy/personalization-setup#user-data-format) for more information. - * Sign the JWT with your secret key, using the EdDSA algorithm. - * Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash. + + After user authentication: + * Create a JWT with user info in the [User format](/deploy/personalization-setup#user-data-format) + * Sign the JWT with your secret key using EdDSA + * Redirect to `/login/jwt-callback` with the JWT as the hash ### Example -Your documentation is hosted 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}`. - ```ts TypeScript import * as jose from 'jose'; From 450cd0219c4b285eb68be472d3ffb006e964e5b7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:51:17 +0000 Subject: [PATCH 6/8] Update deploy/authentication-setup.mdx --- deploy/authentication-setup.mdx | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index f822372c1..86765c424 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -164,14 +164,11 @@ async def return_mintlify_auth_status(current_user): ``` -### Redirect unauthenticated users +### Redirect flow -When an unauthenticated user tries to access a protected page, their intended destination is preserved in the redirect to your login URL: +Unauthenticated users are redirected to your login URL with a `redirect` parameter preserving their 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. +`https://foo.com/docs-login?redirect=%2Fquickstart` → `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}` From 6aead6f2a998934db935a631f60fd77a5ba46b0e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:51:28 +0000 Subject: [PATCH 7/8] Update deploy/authentication-setup.mdx --- deploy/authentication-setup.mdx | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index 86765c424..bdc4c5fa5 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -174,44 +174,31 @@ Unauthenticated users are redirected to your login URL with a `redirect` paramet ## Make pages public -When using partial authentication, all pages are protected by default. You can make specific pages viewable without authentication at the page or group level with the `public` property. +With partial authentication, pages are protected by default. Make pages public with the `public` property. ### Individual pages -To make a page public, add `public: true` to the page's frontmatter. +Add `public: true` to the page's frontmatter: -```mdx Public page example +```mdx --- title: "Public page" public: true --- ``` -### Groups of pages +### Groups -To make all pages in a group public, add `"public": true` beneath the group's name in the `navigation` object of your `docs.json`. +Add `"public": true` to the group in `docs.json`: -```json Public group example +```json { "navigation": { "groups": [ { "group": "Public group", "public": true, - "icon": "play", - "pages": [ - "quickstart", - "installation", - "settings" - ] - }, - { - "group": "Private group", - "icon": "pause", - "pages": [ - "private-information", - "secret-settings" - ] + "pages": ["quickstart", "installation"] } ] } From 66aca01ab71cfdf83f3a1cf6fd53d6768abd1b24 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 24 Nov 2025 18:51:44 +0000 Subject: [PATCH 8/8] Update deploy/authentication-setup.mdx --- deploy/authentication-setup.mdx | 37 ++++++++++++++------------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/deploy/authentication-setup.mdx b/deploy/authentication-setup.mdx index bdc4c5fa5..e10025223 100644 --- a/deploy/authentication-setup.mdx +++ b/deploy/authentication-setup.mdx @@ -207,11 +207,9 @@ Add `"public": true` to the group in `docs.json`: ## 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. +With OAuth or JWT authentication, restrict pages to specific user groups. Pass groups in user data during authentication: -Groups are managed through user data passed during authentication. - -```json Example user info highlight={2} +```json User info with groups { "groups": ["admin", "beta-users"], "content": { @@ -221,44 +219,41 @@ Groups are managed through user data passed during authentication. } ``` -Specify which groups can access specific pages using the `groups` property in frontmatter. +Restrict pages using the `groups` property in frontmatter: -```mdx Example page restricted to the admin group highlight={3} +```mdx --- 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. +Users need at least one matching group to access the page. Without a match, they receive a 404 error. -### Interaction with authentication modes +### With authentication modes -Groups work differently depending on your authentication mode. +**Full authentication:** +- Pages without `groups`: accessible to all authenticated users +- Pages with `groups`: accessible only to users in those groups -**Full authentication with groups:** -- All pages require authentication. -- Pages without a `groups` property are accessible to all authenticated users. -- Pages with a `groups` property are only accessible to authenticated users in those groups. +**Partial authentication:** +- Pages with `public: true` and no `groups`: accessible to everyone +- Pages with `groups`: accessible only to authenticated users in those groups -**Partial authentication with groups:** -- Pages require authentication unless you make them public. -- Pages with `public: true` and no `groups` are accessible to everyone. -- Pages with `groups` (with or without `public: true`) are only accessible to authenticated users in those groups. - -```mdx Anyone can view this page +```mdx Public page --- title: "Public guide" public: true --- ``` -```mdx Only authenticated users can view this page +```mdx Authenticated users only --- title: "API reference" --- +``` -```mdx Only authenticated users in the pro or enterprise groups can view this page +```mdx Specific groups only --- title: "Advanced configurations" groups: ["pro", "enterprise"]