diff --git a/changelog/overview.mdx b/changelog/overview.mdx
index 22d83458a..2ab381bac 100644
--- a/changelog/overview.mdx
+++ b/changelog/overview.mdx
@@ -99,7 +99,7 @@ mode: "wide"
## Filter search based on the current user
- When user auth is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content.
+ When personalization is enabled, search results are now filtered based on the current logged in user so that they only see the relevant content.
## Custom Prompts for AI Chat
diff --git a/mint.json b/mint.json
index 502a9e4d0..59a4fd2d8 100644
--- a/mint.json
+++ b/mint.json
@@ -111,6 +111,35 @@
{
"group": "Configurations",
"pages": [
+ {
+ "icon": "user-lock",
+ "group": "Auth & Personalization",
+ "pages": [
+ "settings/authentication-personalization/authentication",
+ "settings/authentication-personalization/personalization",
+ "settings/authentication-personalization/authentication-vs-personalization",
+ {
+ "group": "Authentication Setup",
+ "pages": [
+ "settings/authentication-personalization/authentication-setup/choosing-a-handshake",
+ "settings/authentication-personalization/authentication-setup/password",
+ "settings/authentication-personalization/authentication-setup/jwt",
+ "settings/authentication-personalization/authentication-setup/oauth",
+ "settings/authentication-personalization/authentication-setup/mintlify"
+ ]
+ },
+ {
+ "group": "Personalization Setup",
+ "pages": [
+ "settings/authentication-personalization/personalization-setup/choosing-a-handshake",
+ "settings/authentication-personalization/personalization-setup/shared-session",
+ "settings/authentication-personalization/personalization-setup/jwt",
+ "settings/authentication-personalization/personalization-setup/oauth"
+ ]
+ },
+ "settings/authentication-personalization/sending-data"
+ ]
+ },
"settings/custom-domain",
"settings/seo",
"settings/broken-links",
@@ -156,23 +185,6 @@
"advanced/rest-api/update-status"
]
},
- {
- "icon": "user-lock",
- "group": "User Auth",
- "pages": [
- "advanced/user-auth/overview",
- {
- "group": "Authenticating",
- "pages": [
- "advanced/user-auth/choosing-an-auth-method",
- "advanced/user-auth/shared-session",
- "advanced/user-auth/jwt",
- "advanced/user-auth/oauth"
- ]
- },
- "advanced/user-auth/sending-data"
- ]
- },
"settings/authentication"
]
},
diff --git a/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx
new file mode 100644
index 000000000..c3f7afd6e
--- /dev/null
+++ b/settings/authentication-personalization/authentication-setup/choosing-a-handshake.mdx
@@ -0,0 +1,84 @@
+---
+title: 'Choosing a Handshake'
+description: 'How to decide which Handshake method is right for your docs'
+---
+
+
+ This is the documentation for **Authentication** Handshake methods. Personalization offers a [different set of Handshake methods](/settings/authentication-personalization/personalization-setup/choosing-a-handshake).
+
+
+Before your users can access personalized content, they must be authenticated. Mintlify supports four Authentication Handshake methods:
+
+1. **Password**: Configure a set of global passwords for your documentation site.
+2. **JWT**: Use your own login flow to authenticate your users via a JWT in the URL.
+3. **OAuth 2.0**: Integrate with your OAuth server to enable user login via the standard Authorization Code flow.
+4. **Mintlify Dashboard**: Allow all of your dashboard users to access your docs, zero configuration required.
+
+## Prerequisites
+
+
+
+
+ - Your security requirements allow for password sharing between documentation readers.
+
+
+
+ - You have some existing login flow.
+ - You can add a final step in this login flow that creates a JWT and redirects to the docs.
+
+
+
+ - You have an existing OAuth server that supports the Authorization Code flow.
+ - You can create a new API endpoint that can be accessed by the returned OAuth access token.
+
+
+
+ - Your documentation readers are also your documentation editors.
+
+
+
+## Pros & Cons
+
+
+
+ Pros:
+
+ - Super simple setup
+ - No configuration required for adding new users - just share the password
+
+ Cons:
+
+ - Difficult to revoke access to your docs without resetting the password
+ - Lose personalization features, as there is no way to differentiate users with the same password
+
+
+ Pros:
+
+ - Reduced risk of API endpoint abuse
+ - Zero CORS configuration
+ - No restrictions on API URLs
+
+ Cons:
+
+ - Must be able to hook into your existing login flow
+
+
+ Pros:
+
+ - Heightened security standard
+
+ Cons:
+
+ - Requires significant work if setting up OAuth server for the first time
+ - Might be overkill for some applications
+
+
+ Pros:
+
+ - Zero-config setup
+
+ Cons:
+
+ - Requires all docs readers to have an account in your Mintlify dashboard
+
+
diff --git a/settings/authentication-personalization/authentication-setup/jwt.mdx b/settings/authentication-personalization/authentication-setup/jwt.mdx
new file mode 100644
index 000000000..16d6f59eb
--- /dev/null
+++ b/settings/authentication-personalization/authentication-setup/jwt.mdx
@@ -0,0 +1,102 @@
+---
+title: 'JWT Handshake'
+description: 'Use a customized login flow to authenticate users'
+---
+
+
+ This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different.
+
+
+If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.
+
+## Implementation
+
+
+
+ Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
+
+
+ Create a login flow that does the following:
+ - Authenticate the user
+ - Create a JWT containing the authenticated user's info in the [UserInfo](../sending-data) format
+ - Sign the JWT with the 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
+
+
+ Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings.
+
+
+
+## Example
+
+I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
+to be completely separate from my dashboard (or I don’t have a dashboard at all).
+
+To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
+JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
+for my users. At the end of this login flow, once I have verified the identity of the user,
+I create a JWT containing the user’s custom data according to Mintlify’s specification.
+I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
+form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user.
+
+I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
+Login URL field.
+
+Here's what the code might look like:
+
+
+```ts TypeScript
+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, 'EdDSA');
+
+export async function handleRequest(req: Request, res: Response) {
+ const userInfo = {
+ expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 week session expiration
+ groups: res.locals.user.groups,
+ content: {
+ firstName: res.locals.user.firstName,
+ lastName: res.locals.user.lastName,
+ },
+ };
+
+ const jwt = await new jose.SignJWT(userInfo)
+ .setProtectedHeader({ alg: 'EdDSA' })
+ .setExpirationTime('10 s') // 10 second JWT expiration
+ .sign(signingKey);
+
+ return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
+}
+```
+
+```python Python
+import jwt # pyjwt
+import os
+
+from datetime import datetime, timedelta
+from fastapi.responses import RedirectResponse
+
+private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
+
+@router.get('/auth')
+async def return_mintlify_auth_status(current_user):
+ jwt_token = jwt.encode(
+ payload={
+ 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
+ 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
+ 'groups': ['admin'] if current_user.is_admin else [],
+ 'content': {
+ 'firstName': current_user.first_name,
+ 'lastName': current_user.last_name,
+ },
+ },
+ key=private_key,
+ algorithm='EdDSA'
+ )
+
+ return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
+```
+
diff --git a/settings/authentication-personalization/authentication-setup/mintlify.mdx b/settings/authentication-personalization/authentication-setup/mintlify.mdx
new file mode 100644
index 000000000..0ed517c96
--- /dev/null
+++ b/settings/authentication-personalization/authentication-setup/mintlify.mdx
@@ -0,0 +1,35 @@
+---
+title: 'Mintlify Dashboard Handshake'
+description: 'Use the Mintlify Dashboard to authenticate users'
+---
+
+
+ This is the documentation for the Mintlify Dashboard **Authentication** Handshake. The Mintlify Dashboard Handshake is not available for Personalization.
+
+
+If your documentation readers are also your documentation editors, you can allow Mintlify to manage access to your documentation. Anyone that can access
+your dashboard will automatically be able to access your documentation.
+
+## Implementation
+
+
+
+ Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and enable the Mintlify Dashboard Handshake.
+
+
+ Ensure that any users that should be able to view your documentation have been added as users in your
+ [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/organization/members).
+
+
+
+## Example
+
+I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
+to be internal, and the people that will be viewing my docs are the same people that
+contribute to my docs.
+
+To set up authentication with Mintlify, I go to my [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication)
+and enable Authentication with the Mintlify Dashboard Handshake.
+
+I then ensure that anyone that should be able to read the docs has been added as a user in
+my [Mintlify dashboard settings](https://dashboard.mintlify.com/settings/organization/members).
diff --git a/settings/authentication-personalization/authentication-setup/oauth.mdx b/settings/authentication-personalization/authentication-setup/oauth.mdx
new file mode 100644
index 000000000..bd90afae4
--- /dev/null
+++ b/settings/authentication-personalization/authentication-setup/oauth.mdx
@@ -0,0 +1,49 @@
+---
+title: 'OAuth 2.0 Handshake'
+description: 'Integrate with your OAuth server to enable user login via the Authorization Code flow'
+---
+
+
+ This is the documentation for the OAuth **Authentication** Handshake. The steps for setting up the [OAuth **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/oauth) are slightly different.
+
+
+If you have an existing OAuth server, you can integrate with Mintlify for a seamless login experience.
+
+## Implementation
+
+
+
+ Go to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields:
+
+ - **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
+ - **Client ID**: An ID for the OAuth 2.0 client to be used.
+ - **Scopes**: An array of scopes that will be requested.
+ - **Token URL**: The base URL for the token exchange request.
+ - **Info API URL** (optional): The endpoint that will be hit to retrieve user info. If omitted, the OAuth flow will only be used to verify identity, and the user info will be empty.
+
+
+ Copy the Redirect URL listed in the [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server.
+
+
+ If you want to take advantage of authentication's customization features, you'll need to create an endpoint to retrieve info about your users.
+ Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [UserInfo](../sending-data) format.
+
+ Return to your [Mintlify authentication settings](https://dashboard.mintlify.com/products/authentication) and add the Info API URL
+ to your OAuth configuration.
+
+
+
+## Example
+
+I have an existing OAuth server that supports the Authorization Code flow. I want to set up authentication for my docs hosted at `foo.com/docs`.
+
+To set up authentication with Mintlify, I create an endpoint `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 according to Mintlify’s specification.
+
+I then go to the Mintlify dashboard settings, navigate to the Authentication settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
+- **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`
+
+Finally, I copy the Redirect URL displayed in the dashboard settings and add it as an authorized redirect URL in my OAuth client configuration settings.
diff --git a/settings/authentication-personalization/authentication-setup/password.mdx b/settings/authentication-personalization/authentication-setup/password.mdx
new file mode 100644
index 000000000..2ce275cc8
--- /dev/null
+++ b/settings/authentication-personalization/authentication-setup/password.mdx
@@ -0,0 +1,34 @@
+---
+title: 'Password Handshake'
+description: 'Use a set of shared passwords to authenticate users'
+---
+
+
+ This is the documentation for the Password **Authentication** Handshake. The Password Handshake is not available for Personalization.
+
+
+If you don't have strict security requirements, or you don't want to manage a
+database of documentation readers, you can use a set of shared passwords to
+protect your docs.
+
+## Implementation
+
+
+
+ Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and create a password.
+
+
+ Securely share the password with your documentation readers. That's it!
+
+
+
+## Example
+
+I want to set up authentication for my docs hosted at `docs.foo.com`. I don't want
+to have to keep track of who can and cannot access the docs. My main use case for
+authentication is to prevent competitors from snooping - password sharing is secure
+enough for my team.
+
+To set up authentication with Mintlify, I go to my Mintlify dashboard and add at
+least one password. I then share that password, along with the private docs URL,
+with potential customers.
diff --git a/settings/authentication-personalization/authentication-vs-personalization.mdx b/settings/authentication-personalization/authentication-vs-personalization.mdx
new file mode 100644
index 000000000..25e1221ae
--- /dev/null
+++ b/settings/authentication-personalization/authentication-vs-personalization.mdx
@@ -0,0 +1,37 @@
+---
+title: 'Auth vs Personalization'
+description: 'How to determine which product is best for you'
+---
+
+Mintlify offers both Authentication and Personalization. For the most part, Authentication is
+just Personalization + privacy. However, there are some key differences that are important to
+be aware of, from most important to least:
+
+### Security Guarantees
+
+Authentication is a fully-fledged private documentation solution. Every aspect of your docs,
+including page content, images, search results, and AI chat features, are completely inaccessible to
+unauthenticated users.
+
+Personalization, on the other hand, offers no security guarantees for your documentation content.
+All page content, images, search results, and AI chat features can be accessed by the public. Even
+if you are using the hidden pages feature of Personalization, a motivated attacker would still
+be able to access the content of a hidden page.
+
+### Handshake Methods
+
+Due to the difference in security requirements for Authentication and Personalization, different
+handshake methods are available for each. Both methods offer a JWT and OAuth Handshake, although
+the setup steps are slightly different.
+
+Authentication offers two additional Handshake methods:
+
+- **Password Handshake**, which protects your website with a single configurable global password.
+
+- **Mintlify Dashboard Handshake**, which will allow users to view your documentation only if they have
+access to your dashboard.
+
+Personalization offers one additional Handshake method:
+
+- **Shared Session Handshake**, a super simple method which only requires setting up a single endpoint
+that returns data for already-authenticated users.
diff --git a/settings/authentication-personalization/authentication.mdx b/settings/authentication-personalization/authentication.mdx
new file mode 100644
index 000000000..b645e1fb5
--- /dev/null
+++ b/settings/authentication-personalization/authentication.mdx
@@ -0,0 +1,21 @@
+---
+title: 'Authentication'
+description: 'Features available with the Authentication product'
+---
+
+
+ Authentication is an enterprise feature. To get access, [contact sales](mailto:sales@mintlify.com).
+
+
+As the name suggests, Authentication offers full privacy for all of your
+documentation content. This includes all of the following:
+
+- Documentation page content
+- Images used in documentation pages
+- Search results
+- AI chat interactions
+
+Authentication can be thought of as Personalization + privacy. In addition
+to securing your documentation content, all features that are available via
+Personalization are also available via Authentication. For more information
+about the features of Personalization, [visit our docs on Personalization](./personalization).
diff --git a/advanced/user-auth/choosing-an-auth-method.mdx b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx
similarity index 88%
rename from advanced/user-auth/choosing-an-auth-method.mdx
rename to settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx
index 9cc97c080..9c7823cc3 100644
--- a/advanced/user-auth/choosing-an-auth-method.mdx
+++ b/settings/authentication-personalization/personalization-setup/choosing-a-handshake.mdx
@@ -1,9 +1,13 @@
---
-title: 'Choosing an Auth Method'
-description: 'How to decide which auth method is right for your docs'
+title: 'Choosing a Handshake'
+description: 'How to decide which Handshake method is right for your docs'
---
-Before your users can access personalized content, they must be authenticated. Mintlify supports three methods of authenticating users:
+
+ This is the documentation for **Personalization** Handshake methods. Authentication offers a [different set of Handshake methods](/settings/authentication-personalization/authentication-setup/choosing-a-handshake).
+
+
+Before your users can access personalized content, they must be authenticated. Mintlify supports three Personalization Handshake methods:
1. **Shared Session**: Utilize the same session token used by your dashboard to authenticate users.
2. **JWT**: Use your own login flow to send user info to your docs via a JWT in the URL.
diff --git a/advanced/user-auth/jwt.mdx b/settings/authentication-personalization/personalization-setup/jwt.mdx
similarity index 80%
rename from advanced/user-auth/jwt.mdx
rename to settings/authentication-personalization/personalization-setup/jwt.mdx
index 3385f0485..7d2b4470e 100644
--- a/advanced/user-auth/jwt.mdx
+++ b/settings/authentication-personalization/personalization-setup/jwt.mdx
@@ -1,25 +1,30 @@
---
-title: 'JWT Auth'
+title: 'JWT Handshake'
description: 'Use a customized login flow to authenticate users'
---
+
+ This is the documentation for the JWT **Personalization** Handshake. The steps for setting up the [JWT **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/jwt) are slightly different.
+
+
+
If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user info to your docs via a JWT in the URL.
## Implementation
- Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
+ Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
Create a login flow that does the following:
- Authenticate the user
- - Create a JWT containing the authenticated user's info in the [UserInfo](./sending-data) format
- - Sign the JWT with the secret, using the EdDSA algorithm
+ - Create a JWT containing the authenticated user's info in the [UserInfo](../sending-data) format
+ - Sign the JWT with the secret key, using the EdDSA algorithm
- Create a redirect URL back to your docs, including the JWT as the hash
-
- Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the login URL to your User Auth settings.
+
+ Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Personalization settings.
diff --git a/advanced/user-auth/oauth.mdx b/settings/authentication-personalization/personalization-setup/oauth.mdx
similarity index 68%
rename from advanced/user-auth/oauth.mdx
rename to settings/authentication-personalization/personalization-setup/oauth.mdx
index 98251eb9f..b90859f9b 100644
--- a/advanced/user-auth/oauth.mdx
+++ b/settings/authentication-personalization/personalization-setup/oauth.mdx
@@ -1,18 +1,22 @@
---
-title: 'OAuth 2.0'
+title: 'OAuth 2.0 Handshake'
description: 'Integrate with your OAuth server to enable user login via the PKCE flow'
---
+
+ This is the documentation for the OAuth **Personalization** Handshake. The steps for setting up the [OAuth **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/oauth) are slightly different.
+
+
If you have an existing OAuth server that supports the PKCE flow, you can integrate with Mintlify for a seamless login experience.
## Implementation
- Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [UserInfo](./sending-data) format. Take note of the scope or scopes required to access this endpoint.
+ Create an API endpoint that can be accessed with an OAuth access token, and responds with a JSON payload following the [UserInfo](../sending-data) format. Take note of the scope or scopes required to access this endpoint.
-
- Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication), select the OAuth option, and fill out the required fields:
+
+ Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication), select the OAuth option, and fill out the required fields:
- **Authorization URL**: The base URL for the authorization request, to which we will add the appropriate query parameters.
- **Client ID**: An ID for the OAuth 2.0 client to be used.
@@ -21,7 +25,7 @@ If you have an existing OAuth server that supports the PKCE flow, you can integr
- **Info API URL**: The endpoint that will be hit to retrieve user info.
- Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add it as an authorized redirect URL for your OAuth server.
+ Copy the Redirect URL listed in the [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add it as an authorized redirect URL for your OAuth server.
@@ -31,7 +35,7 @@ I have an existing OAuth server that supports the PKCE flow. I want to set up au
To set up authentication with Mintlify, I create an endpoint `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 according to Mintlify’s specification.
-I then go to the Mintlify dashboard settings, navigate to the User Auth settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
+I then go to the Mintlify dashboard settings, navigate to the Personalization settings, select OAuth, and enter the relevant values for the OAuth flow and Info API endpoint:
- **Authorization URL**: `https://auth.foo.com/authorization`
- **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
- **Scopes**: `['docs-user-info']`
diff --git a/advanced/user-auth/shared-session.mdx b/settings/authentication-personalization/personalization-setup/shared-session.mdx
similarity index 89%
rename from advanced/user-auth/shared-session.mdx
rename to settings/authentication-personalization/personalization-setup/shared-session.mdx
index d2925a269..a73aa0a83 100644
--- a/advanced/user-auth/shared-session.mdx
+++ b/settings/authentication-personalization/personalization-setup/shared-session.mdx
@@ -1,15 +1,19 @@
---
-title: 'Shared Session Auth'
+title: 'Shared Session Handshake'
description: 'Seamlessly share user sessions between your dashboard and your docs'
---
+
+ This is the documentation for the Shared Session **Personalization** Handshake. The Shared Session Handshake is not available for Authentication.
+
+
This method utilizes the session authentication info already stored in your user’s browser to create a seamless documentation experience.
## Implementation
- Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](./sending-data) format.
+ Create an API endpoint that uses session authentication to identify users, and responds with a JSON payload following the [UserInfo](../sending-data) format.
If the API domain does not *exactly match* the docs domain:
- Add the docs domain to your API's `Access-Control-Allow-Origin` header (must not be `*`)
@@ -18,8 +22,8 @@ This method utilizes the session authentication info already stored in your user
These CORS options only need to be enabled on the *single endpoint* responsible for returning user information. We do not recommend enabling these options on all dashboard endpoints.
-
- Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/user-authentication) and add the API URL and your Login URL to your User Auth settings.
+
+ Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the API URL and your Login URL to your Personalization settings.
diff --git a/advanced/user-auth/overview.mdx b/settings/authentication-personalization/personalization.mdx
similarity index 72%
rename from advanced/user-auth/overview.mdx
rename to settings/authentication-personalization/personalization.mdx
index c4d4da70f..37c4af910 100644
--- a/advanced/user-auth/overview.mdx
+++ b/settings/authentication-personalization/personalization.mdx
@@ -1,27 +1,21 @@
---
-title: 'Introduction'
-description: 'Give your users a personalized docs experience'
+title: 'Personalization'
+description: 'A list of features unlocked with Personalization'
---
-User Auth allows you to identify and authenticate your users so that you can personalize docs content for them. Your users.
-
-Example use cases:
-
-1. **Customize MDX content** with a user's information, such as their name, plan, or title.
-
-2. **Prefill API keys** in the API Playground for streamlined use.
-
-3. **Selectively show pages** in the navigation based on a user's groups.
-
-## What *isn't* User Auth
+
+ Personalization is an enterprise feature. To get access, [contact sales](mailto:sales@mintlify.com).
+
-At this time, User Auth is not meant for the following use cases:
+Personalization refers to a suite of features that allow you to customize your
+documentation experience based on some information about the user. There are
+three major features of Personalization:
-1. **Private docs content.** While you can hide pages from unauthenticated users, those pages are still accessible by anyone who can guess the URL. If your documentation contains sensitive information, User Auth is not enough to hide it.
+- **Customize MDX content** with a user's information, such as their name, plan, or title.
-2. **A Mintlify-backed user database.** Mintlify does not store *any* information about your users. Rather, it relies on your existing infrastructure to serve as the source-of-truth for user data.
+- **Prefill API keys** in the API Playground for streamlined use.
-If you are interested in private docs content, [contact our team](mailto:sales@mintlify.com) to explore solutions.
+- **Selectively show pages** in the navigation based on a user's groups.
## How to Use
@@ -35,9 +29,9 @@ Hello, {userContext.name ?? 'reader'}!
Hello, {userContext.name ?? 'reader'}!
```
-This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the User Auth feature based on the customer's existing plan:
+This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the Personalization feature based on the customer's existing plan:
-User Auth is an enterprise feature. {
+Personalization is an enterprise feature. {
userContext.org === undefined
? <>To access this feature, first create an account at the Mintlify dashboard.
: userContext.org.plan !== 'enterprise'
@@ -46,7 +40,7 @@ userContext.org === undefined
}
```jsx
-User Auth is an enterprise feature. {
+Personalization is an enterprise feature. {
userContext.org === undefined
? <>To access this feature, first create an account at the Mintlify dashboard.
: userContext.org.plan !== 'enterprise'
diff --git a/advanced/user-auth/sending-data.mdx b/settings/authentication-personalization/sending-data.mdx
similarity index 75%
rename from advanced/user-auth/sending-data.mdx
rename to settings/authentication-personalization/sending-data.mdx
index 019dc0581..bb7b17d17 100644
--- a/advanced/user-auth/sending-data.mdx
+++ b/settings/authentication-personalization/sending-data.mdx
@@ -1,9 +1,9 @@
---
title: 'Sending Data'
-description: 'The types and shape of user data you can send to Mintlify'
+description: 'The shape of user data you can use to personalize your docs'
---
-Depending on your authentication configuration, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both:
+Depending on your Handshake method, your API will respond with either a raw JSON object or a signed JWT. The shape of the data is the same for both:
```tsx
type UserInfo = {
@@ -24,7 +24,7 @@ type UserInfo = {
type="number"
>
The time at which this information should expire, in **seconds since epoch**. If the user loads the page and the current time is after this value, the stored data will be deleted.
- For JWT Auth: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks.
+ For JWT Handshakes: This is *not* the same as the `exp` claim of the JWT. The `exp` claim determines when a JWT should no longer be considered valid, and should be set as low as possible. In this case, it can probably be set to 10 seconds or lower. The `expiresAt` field determines when retrieved data should be considered stale, and can be anywhere from one day to several weeks.
- Within the [Mintlify dashboard](https://dashboard.mintlify.com/mintlify/mintlify/settings/deployment/git-settings), add the project ID and access token from the previous steps alongside the other configurations. Click "Save Changes" when you're done.
+ Within the [Mintlify dashboard](https://dashboard.mintlify.com/settings/deployment/git-settings), add the project ID and access token from the previous steps alongside the other configurations. Click "Save Changes" when you're done.
