You are viewing the API documentation for BigBlueButton 3.x. The current version is BigBlueButton 4.x. Planning an upgrade? The migration guide lists every change your API calls need.
getJoinUrl – Generate Join URL
The getJoinUrl endpoint generates a new join URL for a user who has already joined a meeting. This allows the same user to open additional sessions — for example on a second screen or after switching devices — without re-authenticating through the standard join flow. BBB 3.0+
Endpoint
GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters> This endpoint uses session-token authentication instead of the standard shared-secret checksum mechanism. The user must have already joined via the join endpoint and hold a valid sessionToken.
Unlike the checksum-protected BigBlueButton API endpoints, which return XML, this endpoint returns JSON.
Required Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
sessionToken | String | Yes | — | The sessionToken of the user for whom a new join URL should be generated. |
Optional Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
replaceSession | Boolean | No | false | When set to true, the original session is invalidated and replaced by the new one (session transfer). |
sessionName | String | No | — | A descriptive name for the new session. |
enforceLayout | String | No | — | Override the layout for the new session. |
userdata-* | String | No | — | Custom user data for the new session. Keys must be prefixed with userdata-. |
Use Cases
- Hybrid scenarios — a moderator uses one screen for the presentation and a second screen for the participant view.
- Device switching — a user moves from their desktop to a tablet during a meeting.
- Multi-screen setups — a conference room with multiple displays showing different layouts.
Behaviour
The new session shares the user identity with the original session. The user appears only once in the participant list.
Without replaceSession, both sessions exist in parallel.
With replaceSession=true, the original session is invalidated and the user is seamlessly transferred to the new session.
Example Request
GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS Example Response (Success)
{
"response": {
"returncode": "SUCCESS",
"message": "Join URL provided successfully.",
"url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
}
} Error Responses
When a request fails, the endpoint returns a JSON object with a descriptive error message:
{
"response": {
"returncode": "FAILED",
"message": "<error message>"
}
} | Message | Meaning |
|---|---|
You must provide a session token | The sessionToken parameter is missing. |
Invalid session token | The sessionToken is invalid or has expired. |
Invalid Session | The request does not carry the HTTP session cookie created by join, and the meeting does not allow requests without a session (allowRequestsWithoutSession, default false). |
Access denied | The user was not found or does not have permission. |
Meeting not found | The meeting does not exist or is no longer running. |
In BigBlueButton 3.0, only Meeting not found is returned as a JSON error. For the other errors listed above, the endpoint sends no JSON response.
Userdata Blocklist
When using userdata-* parameters with getJoinUrl, a configurable blocklist (getJoinUrlUserdataBlocklist) restricts certain userdata keys for non-moderator users:
- If the blocklist contains the value
"all", all userdata parameters are blocked for viewers. - Moderators bypass the blocklist, except in breakout rooms.
- The
enforceLayoutparameter is always allowed, regardless of the blocklist.
The endpoint is only available when the user already holds a valid sessionToken — that is, they must have joined the meeting via the standard join endpoint first. Expired tokens are rejected.
For device-switching use cases, set replaceSession=true to seamlessly transfer the session to the new device. This avoids having a stale session on the old device that could cause confusion in the participant list.