neoris/openvidu-meet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

openapi: enhance user and room member schemas with registration and membership dates; update API documentation for clarity

Browse Source
This commit is contained in:
juancarmore 2026-01-07 19:01:43 +01:00
parent e7f61aa2c2
commit 0deae8ad29
14 changed files with 81 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
meet-ce/backend/openapi/components/requestBodies/add-room-member-request.yaml
View File

@ -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.

4
meet-ce/backend/openapi/components/responses/internal/success-get-users.yaml
View File

@ -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

2
meet-ce/backend/openapi/components/responses/success-get-room-members.yaml
View File

@ -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:

53
meet-ce/backend/openapi/components/schemas/internal/global-security-config.yaml
View File

@ -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

5
meet-ce/backend/openapi/components/schemas/internal/meet-user.yaml
View File

@ -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']

8
meet-ce/backend/openapi/components/schemas/internal/room-member-token-options.yaml
View File

@ -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'

13
meet-ce/backend/openapi/components/schemas/meet-room-config.yaml
View File

@ -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:

9
meet-ce/backend/openapi/components/schemas/meet-room-member.yaml
View File

@ -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

6
meet-ce/backend/openapi/components/schemas/meet-room.yaml
View File

@ -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:

5
meet-ce/backend/openapi/paths/internal/auth.yaml
View File

@ -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:

7
meet-ce/backend/openapi/paths/recordings.yaml
View File

@ -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:

6
meet-ce/backend/openapi/paths/room-members.yaml
View File

@ -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'

5
meet-ce/backend/openapi/paths/rooms.yaml
View File

@ -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:

6
meet-ce/typings/src/room-member.ts
View File

@ -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<MeetRoomMemberPermissions>; // 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