docs: reorder & testing

backend/openapi.yaml

@@ -1062,6 +1062,86 @@ paths:
           $ref: "#/components/responses/NotImplementedError"
         "500":
           $ref: "#/components/responses/InternalError"
+  /api/v1/user/sessions:
+    get:
+      tags: [User]
+      operationId: userSessionsList
+      summary: List the caller's active device sessions
+      security:
+        - UserHeader: []
+      parameters:
+        - $ref: "#/components/parameters/XUserID"
+      responses:
+        "200":
+          description: Caller's active device sessions.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UserSessionList"
+        "400":
+          $ref: "#/components/responses/InvalidRequestError"
+        "501":
+          $ref: "#/components/responses/NotImplementedError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /api/v1/user/sessions/revoke-all:
+    post:
+      tags: [User]
+      operationId: userSessionsRevokeAll
+      summary: Revoke every device session belonging to the caller
+      description: |
+        Logout from every device. Subsequent authenticated requests on
+        any of the caller's sessions are rejected. Each revocation is
+        recorded in `session_revocations` with `actor_kind=user_self`.
+      security:
+        - UserHeader: []
+      parameters:
+        - $ref: "#/components/parameters/XUserID"
+      responses:
+        "200":
+          description: Caller's sessions revoked.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeviceSessionRevocationSummary"
+        "400":
+          $ref: "#/components/responses/InvalidRequestError"
+        "501":
+          $ref: "#/components/responses/NotImplementedError"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /api/v1/user/sessions/{device_session_id}/revoke:
+    post:
+      tags: [User]
+      operationId: userSessionsRevoke
+      summary: Revoke one of the caller's device sessions
+      description: |
+        Logout from a single device. The target `device_session_id`
+        must belong to the caller; otherwise the endpoint returns
+        `404 not_found` (the same shape as a missing session) so the
+        endpoint cannot be used to probe foreign session ids. The
+        revocation is recorded in `session_revocations` with
+        `actor_kind=user_self`.
+      security:
+        - UserHeader: []
+      parameters:
+        - $ref: "#/components/parameters/XUserID"
+        - $ref: "#/components/parameters/DeviceSessionID"
+      responses:
+        "200":
+          description: Device session revoked.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeviceSession"
+        "400":
+          $ref: "#/components/responses/InvalidRequestError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "501":
+          $ref: "#/components/responses/NotImplementedError"
+        "500":
+          $ref: "#/components/responses/InternalError"
   /api/v1/admin/admin-accounts:
     get:
       tags: [Admin]
@@ -2013,48 +2093,6 @@ paths:
           $ref: "#/components/responses/NotImplementedError"
         "500":
           $ref: "#/components/responses/InternalError"
-  /api/v1/internal/sessions/{device_session_id}/revoke:
-    post:
-      tags: [Internal]
-      operationId: internalSessionsRevoke
-      summary: Revoke a device session (gateway-only)
-      security: []
-      parameters:
-        - $ref: "#/components/parameters/DeviceSessionID"
-      responses:
-        "200":
-          description: Session revoked.
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/DeviceSession"
-        "404":
-          $ref: "#/components/responses/NotFoundError"
-        "501":
-          $ref: "#/components/responses/NotImplementedError"
-        "500":
-          $ref: "#/components/responses/InternalError"
-  /api/v1/internal/sessions/users/{user_id}/revoke-all:
-    post:
-      tags: [Internal]
-      operationId: internalSessionsRevokeAllForUser
-      summary: Revoke every device session belonging to a user
-      security: []
-      parameters:
-        - $ref: "#/components/parameters/UserID"
-      responses:
-        "200":
-          description: Sessions revoked.
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/DeviceSessionRevocationSummary"
-        "404":
-          $ref: "#/components/responses/NotFoundError"
-        "501":
-          $ref: "#/components/responses/NotImplementedError"
-        "500":
-          $ref: "#/components/responses/InternalError"
   /api/v1/internal/users/{user_id}/account-internal:
     get:
       tags: [Internal]
@@ -3456,6 +3494,15 @@ components:
           format: uuid
         revoked_count:
           type: integer
+    UserSessionList:
+      type: object
+      additionalProperties: false
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeviceSession"
   responses:
     NotImplementedError:
       description: Endpoint is documented but not implemented yet.