From b9c0b871545500d89aa8232f2abd0397a28abce4 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Mon, 1 Jun 2026 21:12:12 +0000
Subject: [PATCH] Document scope field serialization format in sessions OpenAPI
 schema

Co-Authored-By: mantra <mantra@stack-auth.com>
---
 apps/backend/src/app/api/latest/auth/sessions/route.tsx | 2 +-
 docs-mintlify/openapi/admin.json                        | 7 +++++--
 docs-mintlify/openapi/server.json                       | 7 +++++--
 3 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/apps/backend/src/app/api/latest/auth/sessions/route.tsx b/apps/backend/src/app/api/latest/auth/sessions/route.tsx
index 490f55b42..fc27eaff9 100644
--- a/apps/backend/src/app/api/latest/auth/sessions/route.tsx
+++ b/apps/backend/src/app/api/latest/auth/sessions/route.tsx
@@ -25,7 +25,7 @@ export const POST = createSmartRouteHandler({
       // Space-separated list of scopes to restrict the created session to (OAuth `scope`
       // convention). Omitted = unrestricted session. Access tokens minted from this session
       // carry these scopes and are gated by each endpoint's `requiredScopes`. See `scopes.ts`.
-      scope: yupString().optional(),
+      scope: yupString().optional().meta({ openapiField: { description: "Space-separated list of registered scopes to restrict the created session to (OAuth `scope` convention), e.g. `teams:read contact_channels:read`. Omitted means the session is unrestricted.", exampleValue: "teams:read contact_channels:read" } }),
     }).defined(),
   }),
   response: yupObject({
diff --git a/docs-mintlify/openapi/admin.json b/docs-mintlify/openapi/admin.json
index 634ea1088..3fafc56db 100644
--- a/docs-mintlify/openapi/admin.json
+++ b/docs-mintlify/openapi/admin.json
@@ -8265,14 +8265,17 @@
                     "type": "boolean"
                   },
                   "scope": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "teams:read contact_channels:read",
+                    "description": "Space-separated list of registered scopes to restrict the created session to (OAuth `scope` convention), e.g. `teams:read contact_channels:read`. Omitted means the session is unrestricted."
                   }
                 },
                 "required": [
                   "user_id"
                 ],
                 "example": {
-                  "user_id": "3241a285-8329-4d69-8f3d-316e08cf140c"
+                  "user_id": "3241a285-8329-4d69-8f3d-316e08cf140c",
+                  "scope": "teams:read contact_channels:read"
                 }
               }
             }
diff --git a/docs-mintlify/openapi/server.json b/docs-mintlify/openapi/server.json
index b99b476ff..a79c610ec 100644
--- a/docs-mintlify/openapi/server.json
+++ b/docs-mintlify/openapi/server.json
@@ -7516,14 +7516,17 @@
                     "type": "boolean"
                   },
                   "scope": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "teams:read contact_channels:read",
+                    "description": "Space-separated list of registered scopes to restrict the created session to (OAuth `scope` convention), e.g. `teams:read contact_channels:read`. Omitted means the session is unrestricted."
                   }
                 },
                 "required": [
                   "user_id"
                 ],
                 "example": {
-                  "user_id": "3241a285-8329-4d69-8f3d-316e08cf140c"
+                  "user_id": "3241a285-8329-4d69-8f3d-316e08cf140c",
+                  "scope": "teams:read contact_channels:read"
                 }
               }
             }