update setup

Author: ethanpalm

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. 
 
 <Info>
   Authentication methods are available on [Growth and Enterprise plans](https://mintlify.com/pricing?ref=authentication).
 </Info>
 
-## 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.
   <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](/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.
   </Step>
@@ -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,17 +138,17 @@ 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**.
   </Step>
   <Step title="Configure your OAuth server.">
     1. Copy the **Redirect URL** from your [authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication).
     2. Add the redirect URL as an authorized redirect URL for your OAuth server.
   </Step>
   <Step title="Create your user info endpoint (optional).">
-    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).
   </Step>
@@ -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.
 </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>