Skip to navigation
CallingVideoRoom Tokens

Create room token

View as MarkdownOpen in Claude

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.

Authentication

AuthorizationBasic

SignalWire Basic Authentication using Project ID and API Token.

The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.

Example:

Authorization: Basic base64(project_id:token)

Request

This endpoint expects an object.
room_namestringRequiredformat: "^[A-Za-z0-9_-]+$"<=100 characters

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_namestringOptional<=100 characters

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

permissionslist of enumsOptionalDefaults to ["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","room.self.screenshare","room.self.additional_source"]

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_fromdatetimeOptional

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_untildatetimeOptional

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_atdatetimeOptional

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_elapsedintegerOptional<=200000
Remove user after they are in the room for N seconds.
join_audio_mutedbooleanOptionalDefaults to false
Whether the user joins the room with their audio muted.
join_video_mutedbooleanOptionalDefaults to false
Whether the user joins the room with their video muted.
auto_create_roombooleanOptionalDefaults to true
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_previewsbooleanOptionalDefaults to false

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_namestringOptional<=200 characters

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_leavebooleanOptionalDefaults to false
Whether to end the room session when the member using this token leaves the room.
join_asenumOptionalDefaults to member

Whether the user should join as a member or as a non-interactive audience participant. Audience participants cannot send audio or video.

Allowed values:
media_allowedenumOptionalDefaults to all
Indicates what media the user is allowed to receive.
Allowed values:
room_metaobjectOptional
Set the room meta. Maximum of 2000 characters when serialized to JSON.
metaobjectOptional
Set the member meta. Maximum of 2000 characters when serialized to JSON.
sync_audio_videobooleanOptionalDefaults to false

Enable/disable jitter buffer audio-video sync.

Response

The request has succeeded.
tokenstring
A Room Token to be used by clients to connect to the Room.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
500
Internal Server Error