From 26767abbb74585a766e95f1aa92b108ef0305643 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 10:02:05 -0700 Subject: [PATCH 01/19] rename "authentication" to "protected pages" and redirect --- docs.json | 22 ++++++++++++++++++- .../overview.mdx | 0 .../partial-authentication-setup.mdx | 0 .../personalization-setup.mdx | 0 .../sending-data.mdx | 0 .../setup.mdx | 2 +- 6 files changed, 22 insertions(+), 2 deletions(-) rename {authentication-personalization => protected-pages}/overview.mdx (100%) rename {authentication-personalization => protected-pages}/partial-authentication-setup.mdx (100%) rename {authentication-personalization => protected-pages}/personalization-setup.mdx (100%) rename {authentication-personalization => protected-pages}/sending-data.mdx (100%) rename authentication-personalization/authentication-setup.mdx => protected-pages/setup.mdx (99%) diff --git a/docs.json b/docs.json index c2e333f18..0f6d18943 100644 --- a/docs.json +++ b/docs.json @@ -111,7 +111,7 @@ ] }, { - "group": "Authentication and personalization", + "group": "Protected pages", "pages": [ "authentication-personalization/overview", "authentication-personalization/authentication-setup", @@ -498,6 +498,26 @@ { "source": "ai-ingestion", "destination": "ai/llmstxt" + }, + { + "source": "authentication-personalization/overview", + "destination": "protected-pages/overview" + }, + { + "source": "authentication-personalization/authentication-setup", + "destination": "protected-pages/setup" + }, + { + "source": "authentication-personalization/partial-authentication-setup", + "destination": "protected-pages/setup" + }, + { + "source": "authentication-personalization/personalization-setup", + "destination": "protected-pages/overview" + }, + { + "source": "authentication-personalization/sending-data", + "destination": "protected-pages/sending-data" } ], "integrations": { diff --git a/authentication-personalization/overview.mdx b/protected-pages/overview.mdx similarity index 100% rename from authentication-personalization/overview.mdx rename to protected-pages/overview.mdx diff --git a/authentication-personalization/partial-authentication-setup.mdx b/protected-pages/partial-authentication-setup.mdx similarity index 100% rename from authentication-personalization/partial-authentication-setup.mdx rename to protected-pages/partial-authentication-setup.mdx diff --git a/authentication-personalization/personalization-setup.mdx b/protected-pages/personalization-setup.mdx similarity index 100% rename from authentication-personalization/personalization-setup.mdx rename to protected-pages/personalization-setup.mdx diff --git a/authentication-personalization/sending-data.mdx b/protected-pages/sending-data.mdx similarity index 100% rename from authentication-personalization/sending-data.mdx rename to protected-pages/sending-data.mdx diff --git a/authentication-personalization/authentication-setup.mdx b/protected-pages/setup.mdx similarity index 99% rename from authentication-personalization/authentication-setup.mdx rename to protected-pages/setup.mdx index 2af330ffa..3b1b65e38 100644 --- a/authentication-personalization/authentication-setup.mdx +++ b/protected-pages/setup.mdx @@ -1,5 +1,5 @@ --- -title: "Authentication setup" +title: "Protected pages setup" description: "Guarantee privacy of your docs by authenticating users" icon: "file-lock" keywords: ['auth'] From 7a1df5d494a1e63a7a9c6141e80edf71d745fe7c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 10:04:25 -0700 Subject: [PATCH 02/19] Create password-protection.mdx --- protected-pages/password-protection.mdx | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 protected-pages/password-protection.mdx diff --git a/protected-pages/password-protection.mdx b/protected-pages/password-protection.mdx new file mode 100644 index 000000000..e69de29bb From b0dd7db300d5df2bb1e5b8b09156c88be99a2300 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 10:04:36 -0700 Subject: [PATCH 03/19] update protected pages group --- docs.json | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs.json b/docs.json index 0f6d18943..e64caa92d 100644 --- a/docs.json +++ b/docs.json @@ -113,11 +113,10 @@ { "group": "Protected pages", "pages": [ - "authentication-personalization/overview", - "authentication-personalization/authentication-setup", - "authentication-personalization/partial-authentication-setup", - "authentication-personalization/personalization-setup", - "authentication-personalization/sending-data" + "protected-pages/overview", + "protected-pages/setup", + "protected-pages/password-protection", + "protected-pages/sending-data" ] }, { From e68bf249545a0218d0870fee6d1c2a0b9c9edabd Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 10:16:16 -0700 Subject: [PATCH 04/19] add content to password protection article --- protected-pages/password-protection.mdx | 33 +++++++++++++++++++++++++ protected-pages/setup.mdx | 30 ---------------------- 2 files changed, 33 insertions(+), 30 deletions(-) diff --git a/protected-pages/password-protection.mdx b/protected-pages/password-protection.mdx index e69de29bb..a4b0db3dc 100644 --- a/protected-pages/password-protection.mdx +++ b/protected-pages/password-protection.mdx @@ -0,0 +1,33 @@ +--- +title: "Password protection" +description: "Restrict access to your documentation with a password" +icon: "rectangle-ellipsis" +--- + +TODO: add a description of when and why you'd use password protection + +## Prerequisites + +* Your security requirements allow sharing passwords among users. + +## Implementation + +TODO: verify steps with new UI + + + + 1. In your dashboard, go to [Protected pages](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Select **Password**. + 3. Enter a secure password. + 4. Select **Save changes**. + + + Securely share the password and documentation URL with authorized users. + + + +## Example scenario + +You need basic access control without tracking individual users. You want to prevent public access while keeping setup simple. Your user base is small and trusted, so you can share a single password with all users. + +**Create a strong password** in your dashboard. **Share credentials** with authorized users. Rotate the password regularly and you are all set. diff --git a/protected-pages/setup.mdx b/protected-pages/setup.mdx index 3b1b65e38..5a002c86b 100644 --- a/protected-pages/setup.mdx +++ b/protected-pages/setup.mdx @@ -207,34 +207,4 @@ Your documentation is hosted at `docs.foo.com` and your team uses the dashboard **Verify team access** by checking that all team members are added to your organization. - - -Password authentication provides access control only and 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). - 2. Select **Full Authentication** or **Partial Authentication**. - 3. Select **Password**. - 4. Enter a secure password. - 5. Select **Save changes**. - - - Securely 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! - From 4ed24d7ce385c5e253edea80fdfa44899b044f20 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 11:17:04 -0700 Subject: [PATCH 05/19] remove partial auth/personalization from overview --- protected-pages/overview.mdx | 26 +++++++------------------- 1 file changed, 7 insertions(+), 19 deletions(-) diff --git a/protected-pages/overview.mdx b/protected-pages/overview.mdx index 7f807d741..ae54d1347 100644 --- a/protected-pages/overview.mdx +++ b/protected-pages/overview.mdx @@ -1,6 +1,6 @@ --- title: "Overview" -description: "Control who sees your documentation and customize their experience" +description: "Control access to your documentation" icon: "badge-info" keywords: ["auth"] --- @@ -10,23 +10,13 @@ keywords: ["auth"] plans](https://mintlify.com/pricing?ref=authentication). -There are three approaches to manage access and customize your documentation based on user information. +Restrict access to your documentation with a password or with a third-party authentication provider. -- **Authentication**: Complete privacy protection for all content with full content customization. -- **Partial authentication**: Page-by-page access control with full content customization. -- **Personalization**: Content customization with **no security guarantees**. All content remains publicly accessible. - -**Choose authentication** if you need complete security and privacy for all your documentation, including pages, images, search results, and AI assistant features. - -**Choose partial authentication** if you want some pages to be public and others private. - -**Choose personalization** if you want to customize content based on user information and your documentation can be publicly accessible. +You can make all of your content private or control access on a page-by-page basis. ## Handshake methods -Authentication and personalization offer multiple handshake methods for controlling access to your content. - -### Available for all methods +TODO: verify that SSO is still an option **JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow. @@ -48,8 +38,6 @@ Authentication and personalization offer multiple handshake methods for controll - Requires significant work if setting up an OAuth server for the first time. - Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately. -### Available for authentication and partial authentication - **Mintlify dashboard**: Allow all of your dashboard users to access your docs. - Pros of Mintlify dashboard: @@ -66,8 +54,6 @@ Authentication and personalization offer multiple handshake methods for controll - Lose personalization features since there is no way to differentiate users with the same password. - Must change the password to revoke access. -### Available for personalization - **Shared session**: Use the same session token as your dashboard to personalize content. - Pros of shared session: @@ -81,7 +67,9 @@ Authentication and personalization offer multiple handshake methods for controll ## Content customization -All three methods allow you to customize content with these features. +TODO: this might all be moved + +When users are authenticated to your docs, you can customize their experience with dynamic content. ### Dynamic `MDX` content From a216069e7211e259f2d1bebb0bf773ac219fda1d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 11:18:18 -0700 Subject: [PATCH 06/19] remove partial-auth setup --- .../partial-authentication-setup.mdx | 25 ------------------- 1 file changed, 25 deletions(-) delete mode 100644 protected-pages/partial-authentication-setup.mdx diff --git a/protected-pages/partial-authentication-setup.mdx b/protected-pages/partial-authentication-setup.mdx deleted file mode 100644 index f3b0e384a..000000000 --- a/protected-pages/partial-authentication-setup.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Partial authentication setup" -description: "Control access to specific pages" -icon: "file-lock-2" -keywords: ["auth"] ---- - -Partial authentication lets you protect private documentation while keeping other pages publicly viewable. Users can browse public content freely and authenticate only when accessing protected pages. - -Partial authentication shares all the same features as authentication, but with the ability to allow unauthenticated users to view certain pages. - -## Setup - -Follow the [Authentication Setup](/authentication-personalization/authentication-setup) guide and select **Partial Authentication** when configuring your chosen handshake method. - -## Making pages public - -By default, all pages are protected. Add the `public` property to the page's frontmatter to make it viewable without authentication: - -```mdx ---- -title: "My Page" -public: true ---- -``` From 5b5cd25e553e787754f3795ad94248154d458134 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 11:22:06 -0700 Subject: [PATCH 07/19] remove personalization --- protected-pages/personalization-setup.mdx | 216 ---------------------- 1 file changed, 216 deletions(-) delete mode 100644 protected-pages/personalization-setup.mdx diff --git a/protected-pages/personalization-setup.mdx b/protected-pages/personalization-setup.mdx deleted file mode 100644 index 4f8d0e901..000000000 --- a/protected-pages/personalization-setup.mdx +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: "Personalization setup" -description: "Let users log in for customized documentation experiences" -icon: "user-cog" ---- - -Personalization lets you customize your documentation based on user information. This guide covers setup for each available handshake method. - -**Need help choosing?** See the [overview](/authentication-personalization/overview) to compare options. - -## Configuring personalization - -Select the handshake method that you want to configure. - - - -### Prerequisites - -* A login 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). - 2. Select **Personalization**. - 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. - - - Modify your existing login flow to include these steps after user login: - - * Create a JWT containing the logged in user's info in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information. - * Sign the JWT with the secret key, using the ES256 algorithm. - * Create a redirect URL back to your docs, including the JWT as the hash. - - - -### Example - -Your documentation is hosted at `docs.foo.com`. You want your docs to be separate from your dashboard (or you don't have a dashboard) and enable personalization. - -Generate a JWT secret. Then create a login endpoint at `https://foo.com/docs-login` that initiates a login flow to your documentation. - -After verifying user credentials: -* Generate a JWT with user data in Mintlify's format. -* Sign the JWT and redirect to `https://docs.foo.com#{SIGNED_JWT}`. - -```ts -import * as jose from 'jose'; -import { Request, Response } from 'express'; - -const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2; - -const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'ES256'); - -export async function handleRequest(req: Request, res: Response) { - const user = { - expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), - groups: res.locals.user.groups, - content: { - firstName: res.locals.user.firstName, - lastName: res.locals.user.lastName, - }, - }; - - const jwt = await new jose.SignJWT(user) - .setProtectedHeader({ alg: 'ES256' }) - .setExpirationTime('10 s') - .sign(signingKey); - - return res.redirect(`https://docs.foo.com#${jwt}`); -} -``` - -### Preserving page anchors - -To redirect users to specific sections after login, use this URL format: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`. - -**Example**: -* Original URL: `https://docs.foo.com/quickstart#step-one` -* Redirect URL: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one` - - - -### Prerequisites -* An OAuth server that supports the Auth Code with PKCE Flow. -* Ability to create an API endpoint accessible by OAuth access tokens. - -### Implementation - - - Create an API endpoint that: - * Accepts OAuth access tokens for authentication. - * Returns user data in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information. - * Defines the scopes for access. - - - 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). - 2. Select **Personalization**. - 3. Select **OAuth** and configure these fields: - * **Authorization URL**: Your OAuth authorization endpoint. - * **Client ID**: Your OAuth 2.0 client identifier. - * **Scopes**: Permissions to request. Must match the scopes of the endpoint that you configured in the first step. - * **Token URL**: Your OAuth token exchange endpoint. - * **Info API URL**: Endpoint to retrieve user data for personalization. Created in the first step. - 4. Select **Save changes** - - - 1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). - 2. Add this URL as an authorized redirect URL in your OAuth server configuration. - - - -### Example - -Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data. - -**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope and responds with the user's custom data: - -```json -{ - "content": { - "firstName": "Jane", - "lastName": "Doe" - }, - "groups": ["engineering", "admin"] -} -``` - -**Configure your OAuth server details** in your dashboard: -* **Authorization URL**: `https://auth.foo.com/authorization` -* **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH` -* **Scopes**: `['docs-user-info']` -* **Token URL**: `https://auth.foo.com/exchange` -* **Info API URL**: `https://api.foo.com/docs/user-info` - -**Configure your OAuth server** to allow redirects to your callback URL. - - -### Prerequisites - -* A dashboard or user portal with cookie-based session authentication. -* Ability to create an API endpoint at the same origin or subdomain as your dashboard. - * If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com`. - * If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com`. -* Your docs are hosted at the same domain or subdomain as your dashboard. - * If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`. - * If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`. - -### Implementation - - - - Create an API endpoint that: - * Uses your existing session authentication to identify users - * Returns user data in the `User` format (see [Sending Data](/authentication-personalization/sending-data)) - * If the API domain and the docs domain **do not exactly match**: - * Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`). - * Set your API's `Access-Control-Allow-Credentials` header to `true`. - - - Only enable CORS headers on this specific endpoint, not your entire dashboard API. - - - - 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). - 2. Select **Personalization**. - 3. Select **Shared Session**. - 4. Enter your **Info API URL**, which is the endpoint from the first step. - 5. Enter your **Login URL**, where users log into your dashboard. - 6. Select **Save changes**. - - - -### Examples - -#### Dashboard at subdomain, docs at subdomain - -You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `docs.foo.com`. - -**Setup process**: -1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. -2. **Add CORS headers** for this route only: - * `Access-Control-Allow-Origin`: `https://docs.foo.com` - * `Access-Control-Allow-Credentials`: `true` -3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`. - -#### Dashboard at subdomain, docs at root - -You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`. - -**Setup process**: -1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. -2. **Add CORS headers** for this route only: - * `Access-Control-Allow-Origin`: `https://foo.com` - * `Access-Control-Allow-Credentials`: `true` -3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`. - -#### Dashboard at root, docs at root - -You have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`. - -**Setup process**: -1. **Create endpoint** `foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. -2. **Configure API URL** in authentication settings: `https://foo.com/api/docs/user-info` - - -No CORS configuration is needed since the dashboard and docs share the same domain. - - - - From 1116da387c997eed50bb152da3f3f97841f79212 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 13:00:44 -0700 Subject: [PATCH 08/19] update setup --- protected-pages/setup.mdx | 92 +++++++++++++++++++++++++++++++++++---- 1 file changed, 83 insertions(+), 9 deletions(-) diff --git a/protected-pages/setup.mdx b/protected-pages/setup.mdx index 5a002c86b..91a446bd0 100644 --- a/protected-pages/setup.mdx +++ b/protected-pages/setup.mdx @@ -2,17 +2,18 @@ title: "Protected pages setup" description: "Guarantee privacy of your docs by authenticating users" icon: "file-lock" -keywords: ['auth'] +keywords: ['auth', 'authentication'] --- -Authentication requires users to log in before accessing your documentation. This guide covers setup for each available handshake method. -**Need help choosing?** See the [overview](/authentication-personalization/overview) to compare options. +This guide covers setup for each available handshake method to control access to your documentation. Authentication methods are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication). -## Configuring authentication +## Protected pages setup + +TODO: verify steps with new UI Select the handshake method that you want to configure. @@ -37,7 +38,7 @@ Select the handshake method that you want to configure. 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 [Sending Data](/authentication-personalization/sending-data) for more information. + * Create a JWT containing the authenticated user's info in the `User` format. See [Sending Data](/protected-pages/sending-data) 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. @@ -123,7 +124,7 @@ When an unauthenticated user tries to access a protected page, their intended de ### Prerequisites * An OAuth server that supports the Authorization Code Flow. -* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable personalization features). +* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable API prefilling features). ### Implementation @@ -137,7 +138,7 @@ When an unauthenticated user tries to access a protected page, their intended de * **Client Secret**: Your OAuth 2.0 client secret. * **Scopes**: Permissions to request. Use multiple scopes if you need different access levels. * **Token URL**: Your OAuth token exchange endpoint. - * **Info API URL** (optional): Endpoint 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. + * **Info API URL** (optional): Endpoint to retrieve user info for API prefilling. If omitted, the OAuth flow will only be used to verify identity and the user info will be empty. 4. Select **Save changes**. @@ -145,9 +146,9 @@ When an unauthenticated user tries to access a protected page, their intended de 2. Add the redirect URL as an authorized redirect URL for your OAuth server. - To enable personalization features, create an API endpoint that: + To enable API playground prefilling, create an API endpoint that: * Accepts OAuth access tokens for authentication. - * Returns user data in the `User` format. See [Sending Data](/authentication-personalization/sending-data) for more information. + * Returns user data in the `User` format. See [Sending Data](/protected-pages/sending-data) for more information. Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). @@ -207,4 +208,77 @@ Your documentation is hosted at `docs.foo.com` and your team uses the dashboard **Verify team access** by checking that all team members are added to your organization. + +### Prerequisites +TODO: verify this is still an option + +* A dashboard or user portal with cookie-based session authentication. +* Ability to create an API endpoint at the same origin or subdomain as your dashboard. + * If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com`. + * If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com`. +* Your docs are hosted at the same domain or subdomain as your dashboard. + * If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`. + * If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`. + +### Implementation + + + + Create an API endpoint that: + * Uses your existing session authentication to identify users + * Returns user data in the `User` format (see [Sending Data](/protected-pages/sending-data)) + * If the API domain and the docs domain **do not exactly match**: + * Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`). + * Set your API's `Access-Control-Allow-Credentials` header to `true`. + + + Only enable CORS headers on this specific endpoint, not your entire dashboard API. + + + + 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Select **Personalization**. + 3. Select **Shared Session**. + 4. Enter your **Info API URL**, which is the endpoint from the first step. + 5. Enter your **Login URL**, where users log into your dashboard. + 6. Select **Save changes**. + + + +### Examples + +#### Dashboard at subdomain, docs at subdomain + +You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `docs.foo.com`. + +**Setup process**: +1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. +2. **Add CORS headers** for this route only: + * `Access-Control-Allow-Origin`: `https://docs.foo.com` + * `Access-Control-Allow-Credentials`: `true` +3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`. + +#### Dashboard at subdomain, docs at root + +You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`. + +**Setup process**: +1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. +2. **Add CORS headers** for this route only: + * `Access-Control-Allow-Origin`: `https://foo.com` + * `Access-Control-Allow-Credentials`: `true` +3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`. + +#### Dashboard at root, docs at root + +You have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`. + +**Setup process**: +1. **Create endpoint** `foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. +2. **Configure API URL** in authentication settings: `https://foo.com/api/docs/user-info` + + +No CORS configuration is needed since the dashboard and docs share the same domain. + + From a8a861bd006d7ebae99c19633dba2f84545712d7 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 21 Jul 2025 13:05:28 -0700 Subject: [PATCH 09/19] update links --- guides/hidden-page-example.mdx | 2 +- guides/hidden-pages.mdx | 4 ++-- protected-pages/overview.mdx | 2 +- protected-pages/sending-data.mdx | 2 +- settings/preview-deployments.mdx | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/guides/hidden-page-example.mdx b/guides/hidden-page-example.mdx index c8941fc23..852313b9d 100644 --- a/guides/hidden-page-example.mdx +++ b/guides/hidden-page-example.mdx @@ -11,7 +11,7 @@ See [Hidden pages](/guides/hidden-pages) for more information. ## Common use cases for hidden pages - By default, hidden pages are publicly accessible, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [authentication](/authentication-personalization/authentication-setup). + By default, hidden pages are publicly accessible, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [protected pages](/protected-pages/setup). - **Beta documentation**: Information that can be public, but should not be discoverable through the navigation. diff --git a/guides/hidden-pages.mdx b/guides/hidden-pages.mdx index a03592202..873a09ea1 100644 --- a/guides/hidden-pages.mdx +++ b/guides/hidden-pages.mdx @@ -8,9 +8,9 @@ Hidden pages are removed from your site's navigation but remain publicly accessi Use hidden pages for content that you want to be accessible on your site or referenced as context for AI tools, but not discoverable through the navigation. -For content requiring strict access control, you must configure [authentication](/authentication-personalization/authentication-setup). +For content requiring strict access control, you must configure [protected pages](/protected-pages/overview). -If you want to hide pages for specific groups of users, use personalization to control [page visibility](/authentication-personalization/overview#page-visibility). +If you want to hide pages for specific groups of users, use protected pages to control [page visibility](/protected-pages/overview#page-visibility). ## Hiding a page diff --git a/protected-pages/overview.mdx b/protected-pages/overview.mdx index ae54d1347..e70d4c7a8 100644 --- a/protected-pages/overview.mdx +++ b/protected-pages/overview.mdx @@ -75,7 +75,7 @@ When users are authenticated to your docs, you can customize their experience wi Display dynamic content based on user information like name, plan, or organization. -The `user` variable contains information sent to your docs from logged in users. See [Sending data](/authentication-personalization/sending-data) for more information. +The `user` variable contains information sent to your docs from logged in users. See [Sending data](/protected-pages/sending-data) for more information. **Example**: Hello, {user.name ?? 'reader'}! diff --git a/protected-pages/sending-data.mdx b/protected-pages/sending-data.mdx index 2323f0b17..20f25bc54 100644 --- a/protected-pages/sending-data.mdx +++ b/protected-pages/sending-data.mdx @@ -4,7 +4,7 @@ description: "User data format for personalizing your documentation" icon: "send" --- -When implementing authentication or personalization, your system returns user data in a specific format that enables content customization. This data can be sent as either a raw JSON object or within a signed JWT, depending on your handshake method. The shape of the data is the same for both. +When implementing protected pages, your system returns user data in a specific format that enables content customization. This data can be sent as either a raw JSON object or within a signed JWT, depending on your handshake method. The shape of the data is the same for both. ## User data format diff --git a/settings/preview-deployments.mdx b/settings/preview-deployments.mdx index 091ac2297..4889df604 100644 --- a/settings/preview-deployments.mdx +++ b/settings/preview-deployments.mdx @@ -51,4 +51,4 @@ Preview deployments can be publicly accessible or restricted to authenticated us **Public access**: Preview URLs are publicly viewable by default. Share a preview link with anyone who needs to review your changes. -**Restricted access**: Enable preview deployment authentication to limit preview access to authenticated Mintlify users only. See [Authentication Setup](/authentication-personalization/authentication-setup) for more information. +**Restricted access**: Enable preview deployment authentication to limit preview access to authenticated Mintlify users only. See [Protected pages setup](/protected-pages/setup) for more information. From 786950f3b3b7c5b9b446121f052a776ef7e483b6 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 15:34:44 -0700 Subject: [PATCH 10/19] move password protection higher in nav --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index e64caa92d..478d144fd 100644 --- a/docs.json +++ b/docs.json @@ -113,9 +113,9 @@ { "group": "Protected pages", "pages": [ + "protected-pages/password-protection", "protected-pages/overview", "protected-pages/setup", - "protected-pages/password-protection", "protected-pages/sending-data" ] }, From 9c0ac871c667165427906455c6222a5c9cd87aae Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 15:35:00 -0700 Subject: [PATCH 11/19] hide sending data page --- docs.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 478d144fd..4209b4faa 100644 --- a/docs.json +++ b/docs.json @@ -115,8 +115,7 @@ "pages": [ "protected-pages/password-protection", "protected-pages/overview", - "protected-pages/setup", - "protected-pages/sending-data" + "protected-pages/setup" ] }, { From 18a1e4bef45e77a1c9786845cd2978c61d89201f Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 15:50:43 -0700 Subject: [PATCH 12/19] update what data is returned for customization --- protected-pages/sending-data.mdx | 35 -------------------------------- 1 file changed, 35 deletions(-) diff --git a/protected-pages/sending-data.mdx b/protected-pages/sending-data.mdx index 20f25bc54..6824dd30f 100644 --- a/protected-pages/sending-data.mdx +++ b/protected-pages/sending-data.mdx @@ -10,9 +10,6 @@ When implementing protected pages, your system returns user data in a specific f ```tsx type User = { - expiresAt?: number; - groups?: string[]; - content?: Record; apiPlaygroundInputs?: { header?: Record; query?: Record; @@ -22,38 +19,6 @@ type User = { }; ``` - - Session expiration time in **seconds since epoch**. If the user loads a page after this time, their stored data is automatically deleted and they must reauthenticate. - For JWT handshakes: This differs from the JWT's `exp` claim, which determines when a JWT is considered invalid. Set the JWT `exp` claim to a short duration (10 seconds or less) for security. Use `expiresAt` for the actual session length (hours to weeks). - - - A list of groups that the user belongs to. Pages with a matching `groups` field in their metadata will be visible to this user. - - **Example**: User with `groups: ["admin", "engineering"]` can access pages tagged with either the `admin` or `engineering` groups. - - - Custom data accessible in your `MDX` content via the `user` variable. Use this for dynamic personalization throughout your documentation. - - **Example**: - ```json - { "firstName": "Ronan", "company": "Acme Corp", "plan": "Enterprise" } - ``` - - **Usage in `MDX`**: - ```mdx - Welcome back, {user.firstName}! Your {user.plan} plan includes... - ``` - With the example `user` data, this would render as: Welcome back, Ronan! Your Enterprise plan includes... - Date: Tue, 22 Jul 2025 15:55:05 -0700 Subject: [PATCH 13/19] update links --- guides/hidden-page-example.mdx | 2 +- guides/hidden-pages.mdx | 2 -- settings/preview-deployments.mdx | 2 +- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/guides/hidden-page-example.mdx b/guides/hidden-page-example.mdx index 852313b9d..e719afecf 100644 --- a/guides/hidden-page-example.mdx +++ b/guides/hidden-page-example.mdx @@ -11,7 +11,7 @@ See [Hidden pages](/guides/hidden-pages) for more information. ## Common use cases for hidden pages - By default, hidden pages are publicly accessible, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [protected pages](/protected-pages/setup). + By default, hidden pages are publicly accessible, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [protected pages](/protected-pages/overview). - **Beta documentation**: Information that can be public, but should not be discoverable through the navigation. diff --git a/guides/hidden-pages.mdx b/guides/hidden-pages.mdx index 873a09ea1..b594122af 100644 --- a/guides/hidden-pages.mdx +++ b/guides/hidden-pages.mdx @@ -10,8 +10,6 @@ Use hidden pages for content that you want to be accessible on your site or refe For content requiring strict access control, you must configure [protected pages](/protected-pages/overview). -If you want to hide pages for specific groups of users, use protected pages to control [page visibility](/protected-pages/overview#page-visibility). - ## Hiding a page A page is hidden if it is not included in your `docs.json` navigation. To hide a page, remove it from your navigation structure. diff --git a/settings/preview-deployments.mdx b/settings/preview-deployments.mdx index 4889df604..0706ca0dd 100644 --- a/settings/preview-deployments.mdx +++ b/settings/preview-deployments.mdx @@ -51,4 +51,4 @@ Preview deployments can be publicly accessible or restricted to authenticated us **Public access**: Preview URLs are publicly viewable by default. Share a preview link with anyone who needs to review your changes. -**Restricted access**: Enable preview deployment authentication to limit preview access to authenticated Mintlify users only. See [Protected pages setup](/protected-pages/setup) for more information. +**Restricted access**: Enable preview deployment authentication to limit preview access to authenticated Mintlify users only. See the protected pages [Overview](/protected-pages/overview) for more information. From d2347ce4b3ddc4bffc55201887715fb3b1183414 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 15:56:11 -0700 Subject: [PATCH 14/19] move auth0 page to protected pages it's a hidden page, so not configuring a redirect. it's unindexed --- {guides => protected-pages}/auth0.mdx | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {guides => protected-pages}/auth0.mdx (100%) diff --git a/guides/auth0.mdx b/protected-pages/auth0.mdx similarity index 100% rename from guides/auth0.mdx rename to protected-pages/auth0.mdx From 12ae2fa7facad5f141b3f46c10263b3af04b410c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 16:10:06 -0700 Subject: [PATCH 15/19] rename protected pages setup "identity provider authentication" --- docs.json | 6 +++--- .../{setup.mdx => identity-provider-authentication.mdx} | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) rename protected-pages/{setup.mdx => identity-provider-authentication.mdx} (99%) diff --git a/docs.json b/docs.json index 4209b4faa..b0d961acd 100644 --- a/docs.json +++ b/docs.json @@ -113,9 +113,9 @@ { "group": "Protected pages", "pages": [ - "protected-pages/password-protection", "protected-pages/overview", - "protected-pages/setup" + "protected-pages/password-protection", + "protected-pages/identity-provider-authentication" ] }, { @@ -507,7 +507,7 @@ }, { "source": "authentication-personalization/partial-authentication-setup", - "destination": "protected-pages/setup" + "destination": "protected-pages/overview" }, { "source": "authentication-personalization/personalization-setup", diff --git a/protected-pages/setup.mdx b/protected-pages/identity-provider-authentication.mdx similarity index 99% rename from protected-pages/setup.mdx rename to protected-pages/identity-provider-authentication.mdx index 91a446bd0..2cd4eb369 100644 --- a/protected-pages/setup.mdx +++ b/protected-pages/identity-provider-authentication.mdx @@ -1,5 +1,5 @@ --- -title: "Protected pages setup" +title: "Identity provider authentication" description: "Guarantee privacy of your docs by authenticating users" icon: "file-lock" keywords: ['auth', 'authentication'] From 13c413efae818cd4b2205e4335506504d6b85d09 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 16:19:04 -0700 Subject: [PATCH 16/19] remove SSO and personalization info --- protected-pages/overview.mdx | 78 +----------------------------------- 1 file changed, 1 insertion(+), 77 deletions(-) diff --git a/protected-pages/overview.mdx b/protected-pages/overview.mdx index e70d4c7a8..0577efb5c 100644 --- a/protected-pages/overview.mdx +++ b/protected-pages/overview.mdx @@ -2,7 +2,7 @@ title: "Overview" description: "Control access to your documentation" icon: "badge-info" -keywords: ["auth"] +keywords: ["auth", "authentication"] --- @@ -16,8 +16,6 @@ You can make all of your content private or control access on a page-by-page bas ## Handshake methods -TODO: verify that SSO is still an option - **JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow. - Pros of JWT: @@ -53,77 +51,3 @@ TODO: verify that SSO is still an option - Cons of password: - Lose personalization features since there is no way to differentiate users with the same password. - Must change the password to revoke access. - -**Shared session**: Use the same session token as your dashboard to personalize content. - -- Pros of shared session: - - Users that are logged into your dashboard are automatically logged into your docs. - - User sessions are persistent so you can refresh data without requiring a new login. - - Minimal setup. -- Cons of shared session: - - Your docs will make a request to your backend. - - You must have a dashboard that uses session authentication. - - CORS configuration is generally required. - -## Content customization - -TODO: this might all be moved - -When users are authenticated to your docs, you can customize their experience with dynamic content. - -### Dynamic `MDX` content - -Display dynamic content based on user information like name, plan, or organization. - -The `user` variable contains information sent to your docs from logged in users. See [Sending data](/protected-pages/sending-data) for more information. - -**Example**: Hello, {user.name ?? 'reader'}! - -```jsx -Hello, {user.name ?? 'reader'}! -``` - -This feature is more powerful when you pair it with custom data about your users. For example, you can give different instructions based on a user's plan. - -**Example**: Authentication is an enterprise feature. { -user.org === undefined -? <>To access this feature, first create an account at the Mintlify dashboard. -: user.org.plan !== 'enterprise' -? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. -: <>To request this feature for your enterprise org, contact our team. -} - -```jsx -Authentication is an enterprise feature. { - user.org === undefined - ? <>To access this feature, first create an account at the Mintlify dashboard. - : user.org.plan !== 'enterprise' - ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, contact our sales team. - : <>To request this feature for your enterprise org, contact our team. -} -``` - - - The information in `user` is only available for logged in users. For logged - out users, the value of `user` will be `{}`. To prevent the page from crashing - for logged out users, always use optional chaining on your `user` fields. For - example, `{user.org?.plan}`. - - -### API key prefilling - -Automatically populate API playground fields with user-specific values by returning matching field names in your user data. The field names in your user data must exactly match the names in the API playground for automatic prefilling to work. - -### Page visibility - -Restrict which pages are visible to your users by adding `groups` fields to your pages' frontmatter. By default, every page is visible to every user. - -Users will only see pages for `groups` that they are in. - -```mdx ---- -title: "Managing your users" -description: "Adding and removing users from your organization" -groups: ["admin"] ---- -``` From 4b46a25aa71780fb68d8faf40de41d709614998d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 16:36:30 -0700 Subject: [PATCH 17/19] update overview --- protected-pages/overview.mdx | 43 ++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/protected-pages/overview.mdx b/protected-pages/overview.mdx index 0577efb5c..dd7e1350a 100644 --- a/protected-pages/overview.mdx +++ b/protected-pages/overview.mdx @@ -10,22 +10,36 @@ keywords: ["auth", "authentication"] plans](https://mintlify.com/pricing?ref=authentication). -Restrict access to your documentation with a password or with a third-party authentication provider. +Choose how users authenticate to access your documentation. You can make all of your content private or control access on a page-by-page basis. -## Handshake methods +## Authentication methods -**JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow. +Choose between simple shared password access or individual user authentication based on your security needs. + +### Password protection + +Shared access with a single global password. + +- Pros of password protection: + - Simple setup with no configuration required to add new users. Just share the password. +- Cons of password protection: + - Cannot differentiate between users with the same password. + - Must change the password to revoke access. + +### Identity provider authentication +Authenticate individual users with one of the following methods. + +**JSON Web Token (JWT)**: Custom system where you manage user tokens with full control over the login flow. - Pros of JWT: - Reduced risk of API endpoint abuse. - No CORS configuration. - No restrictions on API URLs. - Cons of JWT: - Must be compatible with your existing login flow. - - Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately. - - When you refresh user data, users must log into your docs again. If your users' data changes frequently, they must log in frequently or risk having stale data in your docs. + - Users log into your dashboard and docs separately. **OAuth 2.0**: Third-party login integration like Google, GitHub, or other OAuth providers. @@ -34,7 +48,7 @@ You can make all of your content private or control access on a page-by-page bas - No restrictions on API URLs. - Cons of OAuth 2.0: - Requires significant work if setting up an OAuth server for the first time. - - Dashboard sessions and docs authentication are decoupled, so your team will log into your dashboard and your docs separately. + - Users log into your dashboard and docs separately. **Mintlify dashboard**: Allow all of your dashboard users to access your docs. @@ -44,10 +58,15 @@ You can make all of your content private or control access on a page-by-page bas - Cons of Mintlify dashboard: - Requires all users of your docs to have an account in your Mintlify dashboard. -**Password**: Shared access with a single global password. Used for access control only. Does not allow for personalization. +## Choose your method -- Pros of password: - - Simple setup with no configuration required to add new users, just share the password. -- Cons of password: - - Lose personalization features since there is no way to differentiate users with the same password. - - Must change the password to revoke access. +**Use password protection if**: + +- You want a simple, quick setup. +- All authorized users can share the same password. +- You don't need to track individual users. + +**Use identity provider authentication if**: + +- You need to identify individual users. +- You want to integrate with existing login flows. From 4e2c94e002afc9ea805376a54afb7f2670f48aa8 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 16:43:21 -0700 Subject: [PATCH 18/19] update password protection --- protected-pages/password-protection.mdx | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/protected-pages/password-protection.mdx b/protected-pages/password-protection.mdx index a4b0db3dc..edb0f333e 100644 --- a/protected-pages/password-protection.mdx +++ b/protected-pages/password-protection.mdx @@ -4,11 +4,14 @@ description: "Restrict access to your documentation with a password" icon: "rectangle-ellipsis" --- -TODO: add a description of when and why you'd use password protection +Password protection provides simple access control using a single shared password. All authorized users use the same password to access your documentation. + +Use password protection when you need basic security for your docs. ## Prerequisites -* Your security requirements allow sharing passwords among users. +- You are on a Pro or Enterprise plan +- You can securely distribute passwords to authorized users ## Implementation @@ -21,13 +24,18 @@ TODO: verify steps with new UI 3. Enter a secure password. 4. Select **Save changes**. + + Open your documentation in an incognito window to verify the password prompt appears and your password works. + Securely share the password and documentation URL with authorized users. -## Example scenario - -You need basic access control without tracking individual users. You want to prevent public access while keeping setup simple. Your user base is small and trusted, so you can share a single password with all users. +## Security considerations -**Create a strong password** in your dashboard. **Share credentials** with authorized users. Rotate the password regularly and you are all set. +- Rotate passwords regularly. +- Use a strong, unique password. +- Distribute passwords through secure channels like password managers or encrypted communication. +- Change the password immediately if someone loses access privileges. +- Change the password immediately if you need to revoke access. From 9d84a7a0907f878f46fc7db36e879f3ecade1b3a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 22 Jul 2025 17:08:09 -0700 Subject: [PATCH 19/19] update identity provider page --- .../identity-provider-authentication.mdx | 136 +++++------------- 1 file changed, 39 insertions(+), 97 deletions(-) diff --git a/protected-pages/identity-provider-authentication.mdx b/protected-pages/identity-provider-authentication.mdx index 2cd4eb369..15ad69300 100644 --- a/protected-pages/identity-provider-authentication.mdx +++ b/protected-pages/identity-provider-authentication.mdx @@ -1,21 +1,39 @@ --- title: "Identity provider authentication" -description: "Guarantee privacy of your docs by authenticating users" +description: "Keep your docs private by authenticating users" icon: "file-lock" keywords: ['auth', 'authentication'] --- -This guide covers setup for each available handshake method to control access to your documentation. +Control access to your documentation by authenticating individual users. Authentication methods are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication). -## Protected pages setup +## Choose your method -TODO: verify steps with new UI +**Use JWT if**: + +- You want full control over the login flow and user data. +- You need custom authentication logic. +- You prefer to manage tokens yourself. + +**Use OAuth 2.0 if**: + +- You want to integrate with third-party providers (Google, GitHub, etc.). +- You want to leverage existing OAuth infrastructure. +- You prefer standardized security protocols. -Select the handshake method that you want to configure. +**Use the Mintlify dashboard if**: + +- Your editors are also your documentation users. +- You want a zero configuration setup. + +## Configuration + +Select the method that you want to configure. +TODO: verify steps with new UI @@ -28,17 +46,16 @@ Select the handshake method that you want to configure. - 1. In your dashboard, 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. + 1. In your dashboard, go to [Protected pages](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Select **JWT**. + 3. Enter the URL of your existing login flow and select **Save changes**. + 4. Select **Generate new key**. + 5. Store your key securely where it can be accessed by your backend. 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 [Sending Data](/protected-pages/sending-data) for more information. + * TODO: what format is needed? Create a JWT containing the authenticated user's info in the `User` format. See [Sending Data](/protected-pages/sending-data) 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. @@ -46,7 +63,7 @@ Select the handshake method that you want to configure. ### 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). +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. Create a login endpoint at `https://foo.com/docs-login` that extends your existing authentication. @@ -124,15 +141,14 @@ When an unauthenticated user tries to access a protected page, their intended de ### Prerequisites * An OAuth server that supports the Authorization Code Flow. -* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable API prefilling features). ### Implementation - 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). - 2. Select **Full Authentication** or **Partial Authentication**. - 3. Select **OAuth** and configure these fields: + 1. In your dashboard, go to [Protected pages](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Select **OAuth 2.0**. + 3. Configure these fields: * **Authorization URL**: Your OAuth endpoint. * **Client ID**: Your OAuth 2.0 client identifier. * **Client Secret**: Your OAuth 2.0 client secret. @@ -148,7 +164,7 @@ When an unauthenticated user tries to access a protected page, their intended de To enable API playground prefilling, create an API endpoint that: * Accepts OAuth access tokens for authentication. - * Returns user data in the `User` format. See [Sending Data](/protected-pages/sending-data) for more information. + * TODO: what data format is needed?Returns user data in the `User` format. See [Sending Data](/protected-pages/sending-data) for more information. Add this endpoint URL to the **Info API URL** field in your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication). @@ -179,19 +195,18 @@ Your documentation is hosted at `foo.com/docs` and you have an existing OAuth se **Configure your OAuth server to allow redirects** to your callback URL. - + ### Prerequisites -* Your documentation users are also your documentation editors. +* Your documentation users are also your editors. ### Implementation - 1. In your dashboard, 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**. + 1. In your dashboard, go to [Protected pages](https://dashboard.mintlify.com/settings/deployment/authentication). + 2. Select **Mintlify dashboard**. + 3. Select **Enable Mintlify dashboard**. 1. In your dashboard, go to [Members](https://dashboard.mintlify.com/settings/organization/members). @@ -208,77 +223,4 @@ Your documentation is hosted at `docs.foo.com` and your team uses the dashboard **Verify team access** by checking that all team members are added to your organization. - -### Prerequisites -TODO: verify this is still an option - -* A dashboard or user portal with cookie-based session authentication. -* Ability to create an API endpoint at the same origin or subdomain as your dashboard. - * If your dashboard is at `foo.com`, the **API URL** must start with `foo.com` or `*.foo.com`. - * If your dashboard is at `dash.foo.com`, the **API URL** must start with `dash.foo.com` or `*.dash.foo.com`. -* Your docs are hosted at the same domain or subdomain as your dashboard. - * If your dashboard is at `foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`. - * If your dashboard is at `*.foo.com`, your **docs** must be hosted at `foo.com` or `*.foo.com`. - -### Implementation - - - - Create an API endpoint that: - * Uses your existing session authentication to identify users - * Returns user data in the `User` format (see [Sending Data](/protected-pages/sending-data)) - * If the API domain and the docs domain **do not exactly match**: - * Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`). - * Set your API's `Access-Control-Allow-Credentials` header to `true`. - - - Only enable CORS headers on this specific endpoint, not your entire dashboard API. - - - - 1. In your dashboard, go to [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication). - 2. Select **Personalization**. - 3. Select **Shared Session**. - 4. Enter your **Info API URL**, which is the endpoint from the first step. - 5. Enter your **Login URL**, where users log into your dashboard. - 6. Select **Save changes**. - - - -### Examples - -#### Dashboard at subdomain, docs at subdomain - -You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `docs.foo.com`. - -**Setup process**: -1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. -2. **Add CORS headers** for this route only: - * `Access-Control-Allow-Origin`: `https://docs.foo.com` - * `Access-Control-Allow-Credentials`: `true` -3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`. - -#### Dashboard at subdomain, docs at root - -You have a dashboard at `dash.foo.com`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `dash.foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`. - -**Setup process**: -1. **Create endpoint** `dash.foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. -2. **Add CORS headers** for this route only: - * `Access-Control-Allow-Origin`: `https://foo.com` - * `Access-Control-Allow-Credentials`: `true` -3. **Configure API URL** in authentication settings: `https://dash.foo.com/api/docs/user-info`. - -#### Dashboard at root, docs at root - -You have a dashboard at `foo.com/dashboard`, which uses cookie-based session authentication. Your dashboard API routes are hosted at `foo.com/api`. You want to set up personalization for your docs hosted at `foo.com/docs`. - -**Setup process**: -1. **Create endpoint** `foo.com/api/docs/user-info` that identifies users via session authentication and responds with their user data. -2. **Configure API URL** in authentication settings: `https://foo.com/api/docs/user-info` - - -No CORS configuration is needed since the dashboard and docs share the same domain. - -