Build real-time video experiences

1Create a space

Full API Reference

A space is where real-time communication happens in the Mux Video API. It is the basic level of abstraction for building real-time communication into your application. You can create a space through the Mux Dashboard.

From the Spaces section, click Create your first space.

Click Run Request to create the space.

Take note of the new space's id.

This response will contain information about your new space. Be sure to take note of the id field, as you’ll need this space identifier for the rest of the real-time guides.

You can also use the Create Space APIAPI to manage spaces programmatically. Follow this guide to learn how to call the Mux API. You will need to create an Access Token if you've never called the API before.

2Sign a JWT

Now that you have a space to join, you need a JWT signed using a Mux signing key-pair. Follow this guide to learn more.

Once the JWT has been signed, the signed JWT can be safely passed to the client. The client will then use the signed JWT to authenticate to the Mux Spaces API. You should only sign a JWT on the server, where you can keep your signing key secret. You should not put your signing key in the client itself.

JWT Payload and authentication behavior

JWTs are used to join a space. The payload of a JWT is a simple JSON object with a few fields. Here's an example JWT for accessing a space:

{
  // The ID of the space
  "sub": "${SPACE_ID}",         

  // Set the audience to "rt" for real-time
  "aud": "rt",                 

  // Put your signing key ID here
  "kid": "${SIGNING_KEY_ID}",    

  // The expiration date in the future, in epoch format
  "exp": 1680602773, 

  // One of "publisher", "subscriber"
  // This is optional, defaults to "publisher"
  "role": "publisher",

  // Optional external Participant ID - See below
  "participant_id": "MY_CUSTOM_ID" 
}

The expiration in the exp field must be in the future. Please note that once the JWT expires, the client will no longer be able to join using that JWT.

The participant_id is an optional field which you can provide to identify a participant within a space. The Mux Spaces SDKs will also represent each participant with a connection_id. The SDKs will expose both of these IDs so that you can choose to use whichever identifier you wish.

Participant Enforcement

If a participant_id is not provided in the JWT payload, the server will auto-generate one. Using the same JWT multiple times is allowed if there's no participant_id specified.

A participant_id can be used to enforce participant uniqueness in a space. If participant_id is provided in the JWT, and a client joins a space with that JWT, the Mux Spaces API will check to see if there is already a participant with that particular ID, and if so, it will reject the new connection.

This hybrid approach enables you as the developer to pick between strong access control and more fluid use cases where granular access control is not as important.

3Integrate a Mux Spaces SDK

Now you're ready to integrate real-time communications into your application. Follow the guides depending on which platforms you want to support.

Next Steps