Sign in
Room Tokens

Create room token

Creates a Room Token that a client consumes to join a named Video Room with the supplied identity, permissions, join window, and media settings. Call this operation from your server when granting a user access to an SDK-based room; never expose the project API token used to create it. Managed Video Conferences use their own Conference Tokens.

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Video.

Learn more about API scopes.

post/api/video/room_tokens

Request body

room_namestring required

Room's unique named identifier. Allowed characters: A-Za-z0-9_-. Up to 100 characters. The room does not have to exist when the token is created, but must exist prior to joining, or ensure auto_create_room is set to true.

user_namestring

A display name to use for the user. Up to 100 characters. (If not supplied, a random alphanumeric string will be returned for each authorization with this token.)

permissionsVideoRoomTokenPermission[]

A list of permissions, which define what user can do once they join the room. If join_as is audience, permissions are set to an empty array regardless of the value provided.

join_fromstring date-time

The user can't join the room before this time. Expects RFC 3339 datetime: 2022-01-01T23:59:60Z. Date only: 2022-01-01 will be converted to 2022-01-01T00:00:00Z

join_untilstring date-time

The user can't join the room after this time. Expects RFC 3339 datetime: 2022-01-01T23:59:60Z. Date only: 2022-01-01 will be converted to 2022-01-01T00:00:00Z

remove_atstring date-time

Remove user from the room at this time. Expects RFC 3339 datetime: 2022-01-01T23:59:60Z. Date only: 2022-01-01 will be converted to 2022-01-01T00:00:00Z

remove_after_seconds_elapsedinteger

Remove user after they are in the room for N seconds.

join_audio_mutedboolean

Whether the user joins the room with their audio muted.

join_video_mutedboolean

Whether the user joins the room with their video muted.

auto_create_roomboolean

By default, if the user tries to use this token to join a room that doesn't exist, it will be created with default configuration. Set this to false to require the room to exist beforehand.

enable_room_previewsboolean

Whether to generate a video with a preview of the content of the room. This parameter has effect only if this token auto-creates the room, thus it will be ignored if the room already exists.

room_display_namestring

Display name used if a room is auto-created when the token joins. Maximum of 200 characters. Defaults to the value of room_name.

end_room_session_on_leaveboolean

Whether to end the room session when the member using this token leaves the room.

join_as'audience' | 'member'

Join as type for room tokens.

media_allowed'all' | 'video-only' | 'audio-only'

Media allowed type for room tokens.

room_metaobject

Set the room meta. Maximum of 2000 characters when serialized to JSON.

metaobject

Set the member meta. Maximum of 2000 characters when serialized to JSON.

sync_audio_videoboolean

Enable/disable jitter buffer audio-video sync.

Example request

{
  "room_name": "my_room",
  "user_name": "John Smith",
  "permissions": [
    "room.self.audio_mute",
    "room.self.audio_unmute",
    "room.self.video_mute",
    "room.self.video_unmute",
    "room.self.deaf",
    "room.self.undeaf",
    "room.self.set_input_volume",
    "room.self.set_output_volume",
    "room.self.set_input_sensitivity"
  ],
  "join_from": "2022-01-01T00:00:00Z",
  "join_until": "2022-12-31T23:59:59Z",
  "remove_at": "2022-12-31T23:59:59Z",
  "remove_after_seconds_elapsed": 900,
  "auto_create_room": true,
  "enable_room_previews": true,
  "room_display_name": "My Room",
  "room_meta": {
    "topic": "team-meeting"
  },
  "meta": {
    "name": "John Smith"
  },
  "sync_audio_video": true
}

Response

The request has succeeded.

tokenstring required

A Room Token to be used by clients to connect to the Room.

Example response

{
  "token": "eyJ0eXAiOiJWUlQiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2MjIxMjAxMjMsImp0aSI6ImRmMzFjYTQ4LWRiZGMtNGJjZi1hYWU2LTQ1NWEwOGM5NDg2YSIsInN1YiI6IjBjOTdmNjM1LTFjMTMtNGZjMS04NmY3LWJiMmJlODU5ZDhiOSIsInUiOiJKb2huIERvZSIsInIiOiJteV9zdXBlcl9hd2Vzb21lX3Jvb20iLCJzIjpbInJvb20uc2VsZi5hdWRpb191bm11dGUiXSwiYWNyIjp0cnVlLCJqZiI6MTYyMDg5NjQwMCwianUiOjE2MjA5MDU5NjgsInJhdCI6MTYyMDkwMDAwMCwicnNlIjo5MDB9.5mu_H2PjQLtNBbMsBlS0c91EgsDjJzvZUFgj5-tP4VA0VoHZPIGgV_DLRGKt-BqG-DqC5LhpsdMWEFjhVkTBpQ"
}

Changes

No changes found, but 3 of the 138 revisions have a changelog that could not be searched — this endpoint may have changed in one of them.