feat: Enhance OpenAPI documentation by adding required field formatting and providing a description for the bearerAuth security scheme.

authentication-personalization/authentication-setup.mdx

@@ -103,7 +103,7 @@
       * **Authorization URL**: Your OAuth endpoint.
       * **Client ID**: Your OAuth 2.0 client identifier.
       * **Client Secret**: Your OAuth 2.0 client secret.
-      * **Scopes**: Permissions to request. Use multiple scopes if you need different access levels.
+      * **Scopes**: Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). 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.
       * **Logout URL**: The native logout URL for your OAuth provider. If your provider has a `returnTo` or similar parameter, point it back to your docs URL.
@@ -129,18 +129,18 @@
 **Configure your OAuth server details** in your dashboard:
 - **Authorization URL**: `https://auth.foo.com/authorization`
 - **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
-- **Scopes**: `['docs-user-info']`
+- **Scopes**: `['provider.users.docs']`
 - **Token URL**: `https://auth.foo.com/exchange`
 - **Info API URL**: `https://api.foo.com/docs/user-info`
 - **Logout URL**: `https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs`
 
-**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope, and returns:
+**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `provider.users.docs` scope, and returns:
 
 ```json
 {
   "content": {
     "firstName": "Jane",
     "lastName": "Doe"
   },
   "groups": ["engineering", "admin"]
 }
@@ -258,7 +258,7 @@
 
 ### Page level
 
 To make a page public, add `public: true` to the page's frontmatter.
 
 ```mdx Public page example
 ---

authentication-personalization/personalization-setup.mdx

@@ -4,15 +4,15 @@
 icon: "user-cog"
 ---
 
 Personalization customizes your documentation for each user when they are logged in. For example, you can prefill their API keys, show content specific to their plan or role, or hide sections they don't need access to.
 
 ## Personalization features
 
 Customize content with these personalization capabilities.
 
 ### 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.
 
 ### Dynamic MDX content
 
@@ -26,7 +26,7 @@
 
 ### Page visibility
 
 Restrict which pages are visible to your users by adding `groups` fields to your pages' frontmatter. By default, every page is visible to every user.
 
 Users will only see pages for `groups` that they are in.
 
@@ -60,14 +60,14 @@
   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[]"
 >
   List of groups the user belongs to. Pages with matching `groups` in their frontmatter are visible to this user.
 
   **Example**: User with `groups: ["admin", "engineering"]` can access pages tagged with either the `admin` or `engineering` groups.
 </ParamField>
@@ -86,7 +86,7 @@
   ```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...
 
   **Advanced conditional rendering**:
   ```jsx
@@ -107,7 +107,7 @@
   path="apiPlaygroundInputs"
   type="object"
 >
   User-specific values that prefill API playground fields. Saves users time by auto-populating their data when testing APIs.
 
   **Example**:
   ```json
@@ -117,7 +117,7 @@
     "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>
@@ -126,11 +126,11 @@
 
 ```json
 {
   "expiresAt": 1735689600,
   "groups": ["admin", "beta-users"],
   "content": {
     "firstName": "Jane",
     "lastName": "Smith",
     "company": "TechCorp",
     "plan": "Enterprise",
     "region": "us-west"
@@ -138,7 +138,7 @@
   "apiPlaygroundInputs": {
     "header": {
       "Authorization": "Bearer abc123",
       "X-Org-ID": "techcorp"
     },
     "server": {
       "environment": "production",
@@ -244,7 +244,7 @@
     3. Select **OAuth** and configure these fields:
       * **Authorization URL**: Your OAuth authorization endpoint.
       * **Client ID**: Your OAuth 2.0 client identifier.
-      * **Scopes**: Permissions to request. Must match the scopes of the endpoint that you configured in the first step.
+      * **Scopes**: Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Must match the scopes of the endpoint that you configured in the first step.
       * **Token URL**: Your OAuth token exchange endpoint.
       * **Info API URL**: Endpoint to retrieve user data for personalization. Created in the first step.
     4. Select **Save changes**
@@ -259,7 +259,7 @@
 
 Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data.
 
-**Create a user info endpoint** at `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:
+**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `provider.users.docs` scope and responds with the user's custom data:
 
 ```json
 {