From 0deae8ad29005e8dd5d09d6e94f79a7a84d462f7 Mon Sep 17 00:00:00 2001 From: juancarmore Date: Wed, 7 Jan 2026 19:01:43 +0100 Subject: [PATCH] openapi: enhance user and room member schemas with registration and membership dates; update API documentation for clarity --- .../add-room-member-request.yaml | 14 ++--- .../responses/internal/success-get-users.yaml | 4 ++ .../responses/success-get-room-members.yaml | 2 + .../internal/global-security-config.yaml | 53 +++++++++++-------- .../schemas/internal/meet-user.yaml | 5 ++ .../internal/room-member-token-options.yaml | 8 +-- .../components/schemas/meet-room-config.yaml | 13 ----- .../components/schemas/meet-room-member.yaml | 9 +++- .../openapi/components/schemas/meet-room.yaml | 6 +-- .../backend/openapi/paths/internal/auth.yaml | 5 +- meet-ce/backend/openapi/paths/recordings.yaml | 7 +-- .../backend/openapi/paths/room-members.yaml | 6 +++ meet-ce/backend/openapi/paths/rooms.yaml | 5 +- meet-ce/typings/src/room-member.ts | 6 +-- 14 files changed, 81 insertions(+), 62 deletions(-) diff --git a/meet-ce/backend/openapi/components/requestBodies/add-room-member-request.yaml b/meet-ce/backend/openapi/components/requestBodies/add-room-member-request.yaml index 9aed5903..e00e95d6 100644 --- a/meet-ce/backend/openapi/components/requestBodies/add-room-member-request.yaml +++ b/meet-ce/backend/openapi/components/requestBodies/add-room-member-request.yaml @@ -9,16 +9,16 @@ content: type: string example: 'alice_smith' description: | - The unique identifier for an internal OpenVidu Meet user. This field should be provided when adding an internal Meet user as a member. + The unique identifier for a registered OpenVidu Meet user. This field should be provided when adding a registered Meet user as a member. If provided: - The member will be associated with the Meet user account identified by this userId. - - The 'name' field should be left blank or an error will be fired. It will be automatically set based on the Meet user's profile name. + - The 'name' field must be left blank or an error will be fired. It will be automatically set based on the Meet user's profile name. - The memberId will be set to this userId value. If omitted, the member will be treated as an external user and 'name' must be provided. - Important: You must provide either 'userId' (for internal users) or 'name' (for external users), but NOT both. + Important: You must provide either 'userId' (for registered users) or 'name' (for external users), but NOT both. If both are provided, a validation error will be returned. name: type: string @@ -27,9 +27,9 @@ content: description: | The display name for the participant when joining the meeting with this member access. It is recommended to be unique for the members of the room to easily identify them in the meeting. - This field is required only when adding an external user. The 'userId' field should be left blank or an error will be fired. + This field is required only when adding an external user. The 'userId' field must be left blank or an error will be fired. - Important: You must provide either 'userId' (for internal users) or 'name' (for external users), but NOT both. + Important: You must provide either 'userId' (for registered users) or 'name' (for external users), but NOT both. If both are provided, a validation error will be returned. baseRole: type: string @@ -62,7 +62,7 @@ content: description: | Request body to add a new member to a room. - Important: You must provide either 'userId' (for internal Meet users) or 'name' (for external users), but NOT both. - - If 'userId' is provided, the member will be linked to an internal user account and 'name' will be set from that account. + Important: You must provide either 'userId' (for registered Meet users) or 'name' (for external users), but NOT both. + - If 'userId' is provided, the member will be linked to a registered user account and 'name' will be set from that account. - If 'name' is provided, the member will be treated as an external user without a linked account. - If both 'userId' and 'name' are provided or neither is provided, the request will fail with a validation error. diff --git a/meet-ce/backend/openapi/components/responses/internal/success-get-users.yaml b/meet-ce/backend/openapi/components/responses/internal/success-get-users.yaml index 692023d3..f955d42c 100644 --- a/meet-ce/backend/openapi/components/responses/internal/success-get-users.yaml +++ b/meet-ce/backend/openapi/components/responses/internal/success-get-users.yaml @@ -17,12 +17,15 @@ content: users: - userId: 'admin' name: 'Admin' + registrationDate: 1620000000000 role: 'admin' - userId: 'alice_smith' name: 'Alice Smith' + registrationDate: 1620050000000 role: 'user' - userId: 'bob_jones' name: 'Bob Jones' + registrationDate: 1620100000000 role: 'room_member' pagination: nextPageToken: 'eyJvZmZzZXQiOjEwfQ==' @@ -34,6 +37,7 @@ content: users: - userId: 'admin' name: 'Admin' + registrationDate: 1620000000000 role: 'admin' pagination: isTruncated: false diff --git a/meet-ce/backend/openapi/components/responses/success-get-room-members.yaml b/meet-ce/backend/openapi/components/responses/success-get-room-members.yaml index b6e82d1c..8acf1d22 100644 --- a/meet-ce/backend/openapi/components/responses/success-get-room-members.yaml +++ b/meet-ce/backend/openapi/components/responses/success-get-room-members.yaml @@ -18,6 +18,7 @@ content: members: - memberId: 'alice_smith' name: 'Alice Smith' + membershipDate: 1620000000000 accessUrl: 'http://localhost:6080/room/room-123' baseRole: 'moderator' customPermissions: @@ -39,6 +40,7 @@ content: canChangeVirtualBackground: true - memberId: 'ext-abc123' name: 'Bob' + membershipDate: 1620003600000 accessUrl: 'http://localhost:6080/room/room-123?secret=ext-abc123' baseRole: 'speaker' customPermissions: diff --git a/meet-ce/backend/openapi/components/schemas/internal/global-security-config.yaml b/meet-ce/backend/openapi/components/schemas/internal/global-security-config.yaml index 871b9e04..eadb2041 100644 --- a/meet-ce/backend/openapi/components/schemas/internal/global-security-config.yaml +++ b/meet-ce/backend/openapi/components/schemas/internal/global-security-config.yaml @@ -7,28 +7,35 @@ properties: AuthenticationConfig: type: object properties: - authMethod: - type: object - properties: - type: - type: string - enum: - - single_user - default: single_user - example: single_user - description: | - Specifies the authentication method used to access the application. - - `single_user`: Only one user account exists, which has administrative privileges and is used for all access. - authModeToAccessRoom: + allowUserCreation: + type: boolean + description: Allow admins to create new user accounts. + example: true + oauthProviders: + type: array + description: Optional list of allowed OAuth providers for user registration. + items: + $ref: '#/OAuthProviderConfig' + +OAuthProviderConfig: + type: object + properties: + provider: type: string enum: - - none - - moderators_only - - all_users - default: none - example: none - description: | - Specifies who is required to authenticate before accessing a room: - - `none`: No authentication required. - - `moderators_only`: Only moderators need to authenticate. - - `all_users`: All users must authenticate. + - google + - github + description: Supported OAuth provider. + example: google + clientId: + type: string + description: OAuth client ID. + example: your-client-id.apps.googleusercontent.com + clientSecret: + type: string + description: OAuth client secret. + example: your-client-secret + redirectUri: + type: string + description: OAuth redirect URI. + example: https://your-domain.com/auth/callback diff --git a/meet-ce/backend/openapi/components/schemas/internal/meet-user.yaml b/meet-ce/backend/openapi/components/schemas/internal/meet-user.yaml index bce0803a..a57ab7fd 100644 --- a/meet-ce/backend/openapi/components/schemas/internal/meet-user.yaml +++ b/meet-ce/backend/openapi/components/schemas/internal/meet-user.yaml @@ -10,6 +10,11 @@ properties: example: 'Alice Smith' description: | The display name (profile name) of the user. + registrationDate: + type: number + example: 1620000000000 + description: | + The registration date of the user in milliseconds since the Unix epoch. role: type: string enum: ['admin', 'user', 'room_member'] diff --git a/meet-ce/backend/openapi/components/schemas/internal/room-member-token-options.yaml b/meet-ce/backend/openapi/components/schemas/internal/room-member-token-options.yaml index 9567edfc..cbc8431b 100644 --- a/meet-ce/backend/openapi/components/schemas/internal/room-member-token-options.yaml +++ b/meet-ce/backend/openapi/components/schemas/internal/room-member-token-options.yaml @@ -6,15 +6,15 @@ properties: type: string description: A secret key for room access. Determines the member's role. example: 'abc123456' - grantJoinMeetingPermission: + joinMeeting: type: boolean - description: Whether to grant permission to join the meeting. If true, participantName must be provided. + description: Whether the token is intended for joining a meeting. If true, participantName must be provided. example: true participantName: type: string - description: The name of the participant when joining the meeting. Required if `grantJoinMeetingPermission` is true and this is a new token (not a refresh). + description: The name of the participant when joining the meeting. Required if `joinMeeting` is true. example: 'Alice' participantIdentity: type: string - description: The identity of the participant in the meeting. Required when refreshing an existing token with meeting permissions. + description: The identity of the participant in the meeting. Required when refreshing an existing token used for joining a meeting. example: 'Alice' diff --git a/meet-ce/backend/openapi/components/schemas/meet-room-config.yaml b/meet-ce/backend/openapi/components/schemas/meet-room-config.yaml index 860d7401..61ae2ae9 100644 --- a/meet-ce/backend/openapi/components/schemas/meet-room-config.yaml +++ b/meet-ce/backend/openapi/components/schemas/meet-room-config.yaml @@ -29,19 +29,6 @@ MeetRecordingConfig: default: true example: true description: If true, the room will be allowed to record the video of the participants. - allowAccessTo: - type: string - enum: - - admin - - admin_moderator - - admin_moderator_speaker - default: admin_moderator_speaker - example: admin_moderator_speaker - description: | - Defines who can access the recording. Options are: - - `admin`: Only administrators can access the recording. - - `admin_moderator`: Administrators and moderators can access the recording. - - `admin_moderator_speaker`: Administrators, moderators and speakers can access the recording. MeetVirtualBackgroundConfig: type: object properties: diff --git a/meet-ce/backend/openapi/components/schemas/meet-room-member.yaml b/meet-ce/backend/openapi/components/schemas/meet-room-member.yaml index e82a6841..459ec839 100644 --- a/meet-ce/backend/openapi/components/schemas/meet-room-member.yaml +++ b/meet-ce/backend/openapi/components/schemas/meet-room-member.yaml @@ -6,7 +6,7 @@ properties: description: | The unique identifier of the room member. - - For internal users: This is set to the userId of the linked Meet user account. + - For registered Meet users: This is set to the userId of the linked Meet user account. - For external users: This is an automatically generated unique identifier starting from 'ext-'. name: type: string @@ -14,8 +14,13 @@ properties: description: | The display name for the participant when joining the meeting with this member access. - - For OpenVidu Meet users, this is their profile name. + - For registered Meet users, this is their profile name. - For external users, this is the assigned name. + membershipDate: + type: number + example: 1620000000000 + description: > + The timestamp (in milliseconds since Unix epoch) when this member was added to the room. accessUrl: type: string format: uri diff --git a/meet-ce/backend/openapi/components/schemas/meet-room.yaml b/meet-ce/backend/openapi/components/schemas/meet-room.yaml index 4bdf7581..f0e9b671 100644 --- a/meet-ce/backend/openapi/components/schemas/meet-room.yaml +++ b/meet-ce/backend/openapi/components/schemas/meet-room.yaml @@ -14,7 +14,7 @@ properties: type: string example: 'alice_smith' description: | - The userId of the internal Meet user who owns this room. + The userId of the registered Meet user who owns this room. If the room was created by a registered Meet user, this will be their userId. If the room was created via the REST API using an API key, this will be the userId of the global admin (root user). @@ -131,8 +131,8 @@ properties: The general access URL for authenticated users to join the room. This URL should be used by: - - The room owner (internal Meet user who created the room) - - Internal Meet users who are members of the room + - The room owner (registered Meet user who created the room) + - Registered Meet users who are members of the room status: type: string enum: diff --git a/meet-ce/backend/openapi/paths/internal/auth.yaml b/meet-ce/backend/openapi/paths/internal/auth.yaml index 50378891..af5e734e 100644 --- a/meet-ce/backend/openapi/paths/internal/auth.yaml +++ b/meet-ce/backend/openapi/paths/internal/auth.yaml @@ -3,7 +3,7 @@ operationId: loginUser summary: Login to OpenVidu Meet description: > - Authenticates a user and returns an access and refresh token in cookies. + Authenticates a user and returns an access and refresh token. tags: - Internal API - Authentication requestBody: @@ -22,7 +22,7 @@ operationId: logoutUser summary: Logout from OpenVidu Meet description: > - Logs out the user and clears the access and refresh tokens from cookies. + Logs out the user. tags: - Internal API - Authentication responses: @@ -34,7 +34,6 @@ summary: Refresh access token description: > Refreshes the access token using the refresh token. - The new access token is returned in a cookie. tags: - Internal API - Authentication security: diff --git a/meet-ce/backend/openapi/paths/recordings.yaml b/meet-ce/backend/openapi/paths/recordings.yaml index 7d0e99b4..a1ebeac0 100644 --- a/meet-ce/backend/openapi/paths/recordings.yaml +++ b/meet-ce/backend/openapi/paths/recordings.yaml @@ -3,13 +3,14 @@ operationId: getRecordings summary: Get all recordings description: | - Retrieves a paginated list of all recordings available in the system. + Retrieves a paginated list of recordings available in the system. You can apply filters to narrow down the results based on specific criteria. By default, the recordings are sorted by start date in descending order (newest first). - > **Note:** If this endpoint is called using the `roomMemberTokenHeader` authentication method, - > the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned. + > **Note:** + > - When using `accessTokenHeader` authentication: Returns only recordings the authenticated user has access to. + > - When using `roomMemberTokenHeader` authentication: The `roomId` filter is ignored and only recordings associated with the room included in the token are returned. tags: - OpenVidu Meet - Recordings security: diff --git a/meet-ce/backend/openapi/paths/room-members.yaml b/meet-ce/backend/openapi/paths/room-members.yaml index e2cfed3e..26ce98ea 100644 --- a/meet-ce/backend/openapi/paths/room-members.yaml +++ b/meet-ce/backend/openapi/paths/room-members.yaml @@ -13,6 +13,7 @@ - OpenVidu Meet - Room Members security: - apiKeyHeader: [] + - accessTokenHeader: [] parameters: - $ref: '../components/parameters/room-id-path.yaml' requestBody: @@ -42,6 +43,7 @@ - OpenVidu Meet - Room Members security: - apiKeyHeader: [] + - accessTokenHeader: [] parameters: - $ref: '../components/parameters/room-id-path.yaml' - $ref: '../components/parameters/room-member-name.yaml' @@ -72,6 +74,7 @@ - OpenVidu Meet - Room Members security: - apiKeyHeader: [] + - accessTokenHeader: [] parameters: - $ref: '../components/parameters/room-id-path.yaml' - $ref: '../components/parameters/room-member-ids.yaml' @@ -100,6 +103,7 @@ - OpenVidu Meet - Room Members security: - apiKeyHeader: [] + - accessTokenHeader: [] - roomMemberTokenHeader: [] parameters: - $ref: '../components/parameters/room-id-path.yaml' @@ -129,6 +133,7 @@ - OpenVidu Meet - Room Members security: - apiKeyHeader: [] + - accessTokenHeader: [] parameters: - $ref: '../components/parameters/room-id-path.yaml' - $ref: '../components/parameters/room-member-id.yaml' @@ -159,6 +164,7 @@ - OpenVidu Meet - Room Members security: - apiKeyHeader: [] + - accessTokenHeader: [] parameters: - $ref: '../components/parameters/room-id-path.yaml' - $ref: '../components/parameters/room-member-id.yaml' diff --git a/meet-ce/backend/openapi/paths/rooms.yaml b/meet-ce/backend/openapi/paths/rooms.yaml index 84db6dd2..2fd81fd5 100644 --- a/meet-ce/backend/openapi/paths/rooms.yaml +++ b/meet-ce/backend/openapi/paths/rooms.yaml @@ -27,10 +27,13 @@ operationId: getRooms summary: Get all rooms description: | - Retrieves a paginated list of all rooms available in the system. + Retrieves a paginated list of rooms available in the system. You can apply filters to narrow down the results based on specific criteria. By default, the rooms are sorted by creation date in descending order (newest first). + + > **Note:** If this endpoint is called using the `accessTokenHeader` authentication method, + > only rooms the authenticated user has access to will be returned. tags: - OpenVidu Meet - Rooms security: diff --git a/meet-ce/typings/src/room-member.ts b/meet-ce/typings/src/room-member.ts index 94dc245d..9aca4f6e 100644 --- a/meet-ce/typings/src/room-member.ts +++ b/meet-ce/typings/src/room-member.ts @@ -5,7 +5,7 @@ import { SortAndPagination } from './sort-pagination.js'; * Options for adding a member to a room. */ export interface MeetRoomMemberOptions { - userId?: string; // userId of an internal Meet user (mutually exclusive with name) + userId?: string; // userId of a registered Meet user (mutually exclusive with name) name?: string; // Name for an external user (mutually exclusive with userId) baseRole: MeetRoomMemberRole; // The base role assigned to the member customPermissions?: Partial; // Custom permissions for the member (overrides base role permissions) @@ -16,9 +16,9 @@ export interface MeetRoomMemberOptions { * A member can be an internal user (identified by userId) or an external user (identified by name). */ export interface MeetRoomMember { - memberId: string; // Unique identifier for the member (equals userId for internal users, or generated for external users) + memberId: string; // Unique identifier for the member (equals userId for registered users, or generated for external users) roomId: string; // ID of the room the member belongs to - name: string; // Name of the member (either internal or external user name) + name: string; // Name of the member (either registered or external user name) membershipDate: number; // Timestamp when the member was added to the room accessUrl: string; // URL for the member to access the room baseRole: MeetRoomMemberRole; // The base role of the member in the room