API Documentation

BBBLB implements the BBB API and serves those routes under the standard /bigbluebutton/api/* path.

It also provides its own management API under the /bbblb/api/v1/* path. This API is described here.

Token Authentication

Most non-public BBBLB APIs are protected with JWT tokens that need to be signed by a trusted party and provided as an Authorization: bearer <token> header.

There are three types of tokens:

  • Admin Tokens are signed with the global BBBLB_SECRET and allow admins or automation tools to manage and control BBBLB at runtime. Only BBBLB admins can create those tokens. Their permissions can be limited with scopes (see below).

  • Tenant Tokens are signed with the tenant-specific API secret, which allows tenants to create their own tokens. Those are of course limited to tenant-owned resources.

  • Server Tokens are signed with the back-end server API secret, which allows back-end BBB servers to generate their own tokens. Those are limited to very specific actions, e.g. uploading recordings or signaling server state.

You can use the bbblb maketoken command to create all three types of token.

# Admin Token
$ bbblb maketoken -v --expire 600 admin1 admin
Token Header: {}
Token Payload: {'sub': 'admin1', 'aud': 'bbb.example.com', 'scope': 'admin', 'jti': 'd31651f68f8b7a4c', 'exp': 1763460734}
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1p[...]

# Server Token
$ bbblb maketoken -v --expire 600 --server node01.example.com bbb1
Token Header: {'kid': 'bbb:node01.example.com'}
Token Payload: {'sub': 'bbb1', 'aud': 'bbb.example.com', 'jti': 'b9a1383f61b39585', 'exp': 1763460734}
eyJhbGciOiJIUzI1NiIsImtpZCI6ImJiYjpub2RlMDEuZXhhbXBsZ[...]

# Tenant Token
$ bbblb maketoken -v --expire 600 --tenant default default1
Token Header: {'kid': 'tenant:default'}
Token Payload: {'sub': 'default1', 'aud': 'bbb.example.com', 'jti': '7e48835a2bef9315', 'exp': 1763460734}
eyJhbGciOiJIUzI1NiIsImtpZCI6InRlbmFudDpkZWZhdWx0Iiwid[...]

Token Scopes

The scope claim can be used to limit permissions for Admin tokens. The claim should be a space-separates string of scopes.

Scopes have no effect for tenant- or server-tokens. Those have hard-coded scopes and are limited to very specific actions.

  • rec Manage recordings. This parent scope implies all rec:* scopes.

    • rec:list List recordings.

    • rec:create Import new recordings.

    • rec:update Edit or publish/unpublish recordings.

    • rec:delete Delete recordings.

  • tenant Manage tenants. This parent scope implies all tenant:* scopes.

    • tenant:list List tenants.

    • tenant:create Create new tenants.

    • tenant:update Update tenants.

    • tenant:delete Delete tenants.

    • tenant:secret View and change the tenant secret.

  • server Manage backend servers. This parent scope implies all server:* scopes.

    • server:list List all servers.

    • server:create Register new servers.

    • server:update Update servers and server state.

    • server:delete Delete servers.

  • self:tenant Special scope that is assigned to self-signed tenant tokens.

  • self:server Special scope that is assigned to self-signed server tokens.

  • admin This scope grants full access. It implies all other scopes.

API Endpoints

BBB API

BBBLB implements the official BBB API available under the standard /bigbluebutton/api/* path. With BBBLB, each tenant uses their own private API secret to generate the checksum for BBB API calls.

To learn how to access this API and how to authenticate, please refer to the official documentation.

Limitations

Some BBB APIs cannot be fully implemented by a load balancer or require additional work. None of this should affect the typical front-end application, but here is a list of all known limitations or deviations:

  • getJoinUrl is an internal API used exclusively by HTML5client and not available to front-end applications. See Issue #24212.

  • putRecordingTextTracks and getRecordingTextTracks require processing steps on the back-end BBB server that would not be reflected in already transferred recordings. We may find a way to implement this in the future. Scalelite does not implement those APIs.

  • The root resource at /bigbluebutton/api/ will only return minimal information and not the recently added graphql endpoint information. Those are used exclusively by HTML5client and should not be of any interest for front-end applications.

  • The getRecordings listing has an upper limit of BBBLB_MAX_ITEMS even if the client requested more items.

  • The join API will redirect the client twice. The first redirect will point to a new join url on the actual BBB server. This only affects clients that handle the redirect target in some special way instead of just following it.

Webhooks

BBB defines a bunch of webhooks that front-ends can use to get notified about ended meetings or finished recordings. BBBLB hooks into those webhooks and forwards them to the actual front-end.

Most newer webhooks in BBB are protected by wrapping their entire payload into a non-standard JWT token that is signed with the BBB API secret. Since BBBLB sits in between the front-end and the actual BBB server, it has to intercept those webhooks, verify the token against the back-end secret, re-sign the token with the tenant-specific font-end secret, and then forward the request to the original target url. This happens automatically for all known callbacks, and can be enabled for additional callbacks if needed.

The endMeetingURL and meta_endMeetingURL webhooks are usually not authenticated at all. BBBLB intercepts the endMeetingURL webhook to quickly clean up its own meeting state after a meeting ends. To protect this webhook from abuse, BBBLB will create a signed URL using its own BBBLB_SECRET. This is transparent to the front-end, tenants are allowed to use both webhooks without limitations.

Recording Upload

  • POST /bbblb/api/v1/recording/upload (Content-Type: application/x-tar)

The recording upload API expects an application/x-tar archive of a recording directory, optionally compressed with gzip. The tar archive can actually contain multiple recordings or recording formats. Any directory that contains a metadata.xml is considered during the import process.

Authentication

This endpoint requires a Server Token, or an Admin Token with the record:create scope.

Parameters

Parameter

Location

Description

Content-Type

header

Must be application/x-tar.

*

body

A tar or tar.gz archive with recording data.

tenant

query

Assign all records to a specific tenant instead of auto-detecting the tenant from recording metadata.

Response

Recording import triggers background tasks for the actual import. A 202 Accepted response will indicate that the upload was successful, but the actual import will happen later.

Examples

API="https://bbblb.example.com/bbblb/api/v1/recording/upload"
TOKEN="..."
MEETING="d48a35e5c9bef7d5ca0f507c969e3d17a6005abf-1763452847184"
FORMAT="presentation"

tar -c "/var/bigbluebutton/published/$FORMAT/$MEETING/" \
| curl -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/x-tar" \
       -X POST -T - "$API"

Tenant Management

TODO (API is not stable yet)

Server Management

TODO (API is not stable yet)