update identity provider page

Author: ethanpalm

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.
 
 <Info>
   Authentication methods are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication).
 </Info>
 
-## 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
 
 <Tabs>
 <Tab title="JWT">
@@ -28,25 +46,24 @@ Select the handshake method that you want to configure.
 
 <Steps>
   <Step title="Generate a private key.">
-    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.
   </Step>
   <Step title="Integrate Mintlify authentication into your login flow.">
     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.
   </Step>
 </Steps>
 
 ### 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
 
 <Steps>
   <Step title="Configure your OAuth settings.">
-    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
   <Step title="Create your user info endpoint (optional).">
     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).
   </Step>
@@ -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.
 </Tab>
-<Tab title="Mintlify Dashboard">
+<Tab title="Mintlify dashboard">
 ### Prerequisites
 
-* Your documentation users are also your documentation editors.
+* Your documentation users are also your editors.
 
 ### Implementation
 
 <Steps>
   <Step title="Enable Mintlify dashboard authentication.">
-    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**.
   </Step>
   <Step title="Add authorized users.">
     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.
 </Tab>
-<Tab title="Shared session">
-### 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
-
-<Steps>
-  <Step title="Create user info API endpoint.">
-    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`.
-    
-      <Warning>
-        Only enable CORS headers on this specific endpoint, not your entire dashboard API.
-      </Warning>
-  </Step>
-  <Step title="Configure your settings.">
-    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**.
-  </Step>
-</Steps>
-
-### 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`
-
-<Note>
-No CORS configuration is needed since the dashboard and docs share the same domain.
-</Note>
-  </Tab>
 </Tabs>