openapi: add recording token generation endpoint and associated API responses; add recordingTokenCookie authentication method to recording endpoints

backend/openapi/components/headers/set-cookie-recording-token.yaml

@@ -0,0 +1,6 @@
+description: >
+    The cookie containing the recording token.
+    This cookie is used to access the recordings in a room.
+schema:
+    type: string
+    example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict'

backend/openapi/components/requestBodies/internal/recording-token-request.yaml

@@ -0,0 +1,10 @@
+description: Room secret
+required: true
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                secret:
+                    type: string
+                    description: The secret value from the room URL used to connect to the room.

backend/openapi/components/responses/internal/error-participant-not-found.yaml

@@ -1,8 +0,0 @@
-description: Participant not found
-content:
-    application/json:
-        schema:
-            $ref: '../../schemas/error.yaml'
-        example:
-            error: 'Participant Error'
-            message: 'Participant "Alice" not found in room "room_123"'

backend/openapi/components/responses/internal/error-room-metadata-not-found.yaml

@@ -0,0 +1,8 @@
+description: Room metadata not found
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/error.yaml'
+        example:
+            error: 'Room Error'
+            message: 'Room metadata for "room_123" not found. Room "room_123" does not exist or has no recordings associated'

backend/openapi/components/responses/internal/error-room-participant-not-found.yaml

@@ -0,0 +1,16 @@
+description: Room or participant not found
+content:
+    application/json:
+        schema:
+            $ref: '../../schemas/error.yaml'
+        examples:
+            participant_not_found:
+                summary: Participant not found
+                value:
+                    error: 'Participant Error'
+                    message: 'Participant "Alice" not found in room "room_123"'
+            room_not_found:
+                summary: Room not found
+                value:
+                    error: 'Room Error'
+                    message: 'Room "room_123" not found'

backend/openapi/components/responses/internal/success-generate-recording-token.yaml

@@ -0,0 +1,13 @@
+description: Successfully generated the recording token
+headers:
+    Set-Cookie:
+        $ref: '../../headers/set-cookie-recording-token.yaml'
+content:
+    application/json:
+        schema:
+            type: object
+            properties:
+                token:
+                    type: string
+                    description: >
+                        The token to access the recordings in the specified OpenVidu Meet room.

backend/openapi/components/security.yaml

@@ -22,3 +22,9 @@ participantTokenCookie:
     in: cookie
     description: >
         The JWT token to authenticate the participant when entering the room.
+recordingTokenCookie:
+    type: apiKey
+    name: OvMeetRecordingToken
+    in: cookie
+    description: >
+        The JWT token containing permissions to access the recordings in a room.

backend/openapi/openvidu-meet-internal-api.yaml

@@ -18,6 +18,8 @@ paths:
         $ref: './paths/internal/auth.yaml#/~1auth~1profile'
     /rooms/{roomId}:
         $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}'
+    /rooms/{roomId}/recording-token:
+        $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1recording-token'
     /rooms/{roomId}/roles:
         $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1roles'
     /rooms/{roomId}/roles/{secret}:

backend/openapi/paths/internal/meetings.yaml

@@ -44,6 +44,6 @@
             '403':
                 $ref: '../../components/responses/forbidden-error.yaml'
             '404':
-                $ref: '../../components/responses/internal/error-participant-not-found.yaml'
+                $ref: '../../components/responses/internal/error-room-participant-not-found.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'

backend/openapi/paths/internal/participants.yaml

@@ -23,6 +23,8 @@
                 $ref: '../../components/responses/error-room-not-found.yaml'
             '409':
                 $ref: '../../components/responses/internal/error-participant-already-exists.yaml'
+            '422':
+                $ref: '../../components/responses/validation-error.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'
 /participants/token/refresh:
@@ -47,8 +49,10 @@
             '403':
                 $ref: '../../components/responses/forbidden-error.yaml'
             '404':
-                $ref: '../../components/responses/error-room-not-found.yaml'
+                $ref: '../../components/responses/internal/error-room-participant-not-found.yaml'
             '409':
                 $ref: '../../components/responses/internal/error-participant-token-still-valid.yaml'
+            '422':
+                $ref: '../../components/responses/validation-error.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'

backend/openapi/paths/internal/rooms.yaml

@@ -25,6 +25,36 @@
                 $ref: '../../components/responses/validation-error.yaml'
             '500':
                 $ref: '../../components/responses/internal-server-error.yaml'
+/rooms/{roomId}/recording-token:
+    post:
+        operationId: generateRecordingToken
+        summary: Generate recording token
+        description: >
+            Generates a token with recording permissions for a specified OpenVidu Meet room.
+            This token can be used to access the recordings in a room.
+        tags:
+            - Internal API - Rooms
+        security:
+            - accessTokenCookie: []
+        parameters:
+            - $ref: '../../components/parameters/room-id-path.yaml'
+        requestBody:
+            $ref: '../../components/requestBodies/internal/recording-token-request.yaml'
+        responses:
+            '200':
+                $ref: '../../components/responses/internal/success-generate-recording-token.yaml'
+            '400':
+                $ref: '../../components/responses/internal/error-invalid-room-secret.yaml'
+            '401':
+                $ref: '../../components/responses/unauthorized-error.yaml'
+            '403':
+                $ref: '../../components/responses/forbidden-error.yaml'
+            '404':
+                $ref: '../../components/responses/internal/error-room-metadata-not-found.yaml'
+            '422':
+                $ref: '../../components/responses/validation-error.yaml'
+            '500':
+                $ref: '../../components/responses/internal-server-error.yaml'
 /rooms/{roomId}/roles:
     get:
         operationId: getRoomRolesAndPermissions

backend/openapi/paths/recordings.yaml

@@ -5,11 +5,15 @@
         description: >
             Retrieves a paginated list of all recordings available in the system.
             You can apply filters to narrow down the results based on specific criteria.
+
+            > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
+            the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned.
         tags:
             - OpenVidu Meet - Recordings
         security:
             - apiKeyInHeader: []
             - accessTokenCookie: []
+            - recordingTokenCookie: []
         parameters:
             # - name: status
             #   in: query
@@ -90,6 +94,7 @@
         security:
             - apiKeyInHeader: []
             - accessTokenCookie: []
+            - recordingTokenCookie: []
         parameters:
             - $ref: '../components/parameters/recording-id.yaml'
         responses:
@@ -116,6 +121,7 @@
         security:
             - apiKeyInHeader: []
             - accessTokenCookie: []
+            - recordingTokenCookie: []
         parameters:
             - $ref: '../components/parameters/recording-id.yaml'
         responses:
@@ -147,6 +153,7 @@
         security:
             - apiKeyInHeader: []
             - accessTokenCookie: []
+            - recordingTokenCookie: []
         parameters:
             - $ref: '../components/parameters/recording-id.yaml'
             - $ref: '../components/parameters/recording-range.yaml'