Combine information into overview

Author: ethanpalm

authentication-personalization/overview.mdx

@@ -0,0 +1,133 @@
+---
+title: "Overview"
+description: "Control who sees your documentation and customize their experience"
+icon: "badge-info"
+---
+<Info>
+  Authentication methods are available on the [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication). Please{" "}
+  <a href="mailto:[email protected]">contact sales</a> for more information.
+</Info>
+
+There are three approaches to manage access and customize your documentation based on user information.
+
+* **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.
+
+## Handshake methods
+
+Authentication and personalization offer multiple handshake methods for controlling access to your content.
+
+### Available for all 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 in to your dashboard and your docs separately.
+  * When you refresh user data, users must login to your docs again. If your users' data changes frequently, they must log in frequently or risk having stale data in your docs.
+
+**OAuth 2.0**: Third-party login integration like Google, GitHub, or other OAuth providers.
+* Pros of OAuth 2.0:
+  * Heightened security standard.
+  * 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 in to 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:
+  * No configuration required.
+* 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.
+* 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.
+
+### Available for personalization
+
+**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
+
+All three methods allow you to customize content with these personalization features.
+
+### Dynamic 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.
+
+**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 <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
+: user.org.plan !== 'enterprise'
+? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
+: <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
+}
+
+```jsx
+Authentication is an enterprise feature. {
+  user.org === undefined
+    ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</>
+    : user.org.plan !== 'enterprise'
+      ? <>You are currently on the ${user.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</>
+      : <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</>
+}
+```
+
+<Note>
+  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}`.
+</Note>
+
+### 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.
+
+Users will only see pages for `groups` that they are in.
+
+```md
+---
+title: "Managing your users"
+description: "Adding and removing users from your organization"
+groups: ["admin"]
+---
+```

docs.json

@@ -100,7 +100,7 @@
           { 
             "group": "Authentication and Personalization",
             "pages": [
-              "settings/authentication-personalization/comparison",
+              "authentication-personalization/overview",
               "settings/authentication-personalization/authentication",
               "settings/authentication-personalization/partial-authentication",
               "settings/authentication-personalization/personalization",
@@ -382,7 +382,27 @@
   "redirects": [
     {
       "source": "settings/authentication-personalization/authentication-vs-personalization",
-      "destination": "settings/authentication-personalization/comparison"
+      "destination": "authentication-personalization/overview"
+    },
+    {
+      "source": "settings/authentication-personalization/authentication-setup/choosing-a-handshake",
+      "destination": "authentication-personalization/overview"
+    },
+    {
+      "source": "settings/authentication-personalization/personalization-setup/choosing-a-handshake",
+      "destination": "authentication-personalization/overview"
+    },
+    {
+      "source": "settings/authentication-personalization/authentication",
+      "destination": "authentication-personalization/authentication-setup"
+    },
+    {
+      "source": "settings/authentication-personalization/personalization",
+      "destination": "authentication-personalization/personalization-setup"
+    },
+    {
+      "source": "settings/authentication-personalization/partial-authentication",
+      "destination": "authentication-personalization/partial-authentication-setup"
     }
   ]
 }