move Sending data into Personalization

Author: ethanpalm

authentication-personalization/personalization-setup.mdx

@@ -4,9 +4,102 @@ 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.
+Customize your documentation based on user information, including prefilling API playground inputs and adding dynamic content.
+
+## User data format
+
+When implementing 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.
+
+```tsx
+type User = {
+  expiresAt?: number;
+  groups?: string[];
+  content?: Record<string, any>;
+  apiPlaygroundInputs?: {
+    header?: Record<string, any>;
+    query?: Record<string, any>;
+    cookie?: Record<string, any>;
+    server?: Record<string, string>;
+  };
+};
+```
+
+<ParamField
+  path="expiresAt"
+  type="number"
+>
+  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.
+  <Warning><b>For JWT handshakes:</b> 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).</Warning>
+</ParamField>
+<ParamField
+  path="groups"
+  type="string[]"
+>
+  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.
+</ParamField>
+<ParamField
+  path="content"
+  type="object"
+>
+  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...
+</ParamField>
+<ParamField
+  path="apiPlaygroundInputs"
+  type="object"
+>
+  User-specific values that will be prefilled in the API playground if supplied. Save users time when testing your APIs with their own data.
+
+  **Example**:
+  ```json
+  {
+  "header": { "X-API-Key": "user_api_key_123" },
+  "server": { "subdomain": "foo" },
+  "query": { "org_id": "12345" }
+  }
+  ```
+  If a user makes requests at a specific subdomain, you can send `{ server: { subdomain: 'foo' } }` as an `apiPlaygroundInputs` field. This value will be prefilled on any API page with the `subdomain` value.
+
+  <Note>The `header`, `query`, and `cookie` fields will only prefill if they are part of your [OpenAPI security scheme](https://swagger.io/docs/specification/authentication/). If a field is in either the `Authorization` or `Server` sections, it will prefill. Creating a standard header parameter named `Authorization` will not enable this feature.</Note>
+</ParamField>
+
+### Example user data
 
-**Need help choosing?** See the [overview](/authentication-personalization/overview) to compare options.
+```json
+{
+  "expiresAt": 1735689600,
+  "groups": ["admin", "beta-users"],
+  "content": {
+    "firstName": "Jane",
+    "lastName": "Smith",
+    "company": "TechCorp",
+    "plan": "Enterprise",
+    "region": "us-west"
+  },
+  "apiPlaygroundInputs": {
+    "header": {
+      "Authorization": "Bearer abc123",
+      "X-Org-ID": "techcorp"
+    },
+    "server": {
+      "environment": "production",
+      "region": "us-west"
+    }
+  }
+}
+```
 
 ## Configuring personalization
 
@@ -33,7 +126,7 @@ Select the handshake method that you want to configure.
   <Step title="Integrate Mintlify personalization into your login flow.">
     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.
+    * Create a JWT containing the logged in user's info in the `User` format. See the [User data format](#user-data-format) section above 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.
   </Step>
@@ -95,7 +188,7 @@ To redirect users to specific sections after login, use this URL format: `https:
   <Step title="Create user info API endpoint.">
     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 the [User data format](#user-data-format) section above for more information.
     * Defines the scopes for access.
   </Step>
   <Step title="Configure your OAuth personalization settings.">
@@ -157,7 +250,7 @@ Your documentation is hosted at `foo.com/docs` and you have an existing OAuth se
   <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](/authentication-personalization/sending-data))
+    * Returns user data in the `User` format (see the [User data format](#user-data-format) section above)
     * 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`.