Build real-time video experiences

1Get an API access token

The Mux Video API uses a token key pair that consists of a Token ID and Token Secret for authentication. If you haven't already, generate a new Access Token in the Access Token settings of your Mux account dashboard.

The access token should have Mux Video Read and Write permissions.

Access Tokens also belong to an Environment. Be sure to use the same Environment when using Mux Video and Mux Data together, so the data from Mux Data can be used to optimize your Mux Video streams.

2Get a JWT keypair

The basic abstraction for creating real-time communications with Mux is a space. In order for clients to authenticate to a space, they need to provide a signed JSON Web Token, or JWT. This signed JWT is the way that the real-time client authenticates to a particular space.

In order to sign the JWT before sending it to your client, you must create a signing key. Signing keys can be managed (created, deleted, listed) either from the Mux dashboard or via the Mux Video API. When creating a new signing key, the API generates a 2048-bit RSA key-pair and returns the private key and the public key. As the name implies, you should securely store the private key, and never pass it to a real-time communications client. The other portion of the key-pair, the public key, will be stored by Mux in order to validate the signed tokens were actually signed by the private key. As it's name suggests, it's perfectly fine to share your public key if you so desire.

Signing keys are created and deleted independently of assets, spaces, or API tokens. You probably only need one signing key active at a time, but if you so choose you can create multiple key-pairs to enable key rotation. In this case, you would create a new key-pair to sign new JWTs but hold off deleting the old key-pair until after any JWTs signed with that older key-pair have expired.

3Create a space

Full API Reference

As explained above, a space is the basic level of abstraction for building real-time communications with the Mux API. The first step to building real-time communications into your application is to create a space. You can create a space through the Mux dashboard or via the Mux API. To create a space using the Mux API, simply POST an empty body to the video/v1/spaces endpoint, as shown below. (Don't forget to substitute your actual Mux token ID and token secret for ${MUX_TOKEN_ID} and ${MUX_TOKEN_SECRET}.)

copy
curl https://api.mux.com/video/v1/spaces \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{}' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET} 

You should receive back a response that looks something like the following:

copy
{
  "data": {
    "type": "server",
    "status": "idle",
    "id": "oXvx1ydOr2FLIgnatM00L5hDwIlld2BjVp0rdoxryvkE",
    "created_at": "1653365403"
  }
} 

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. We’ll refer to this ID in the following guides as ${SPACE_ID}.

4Sign a JWT

As explained above, client authentication to a space is controlled by using a signed JWT. You can use an existing signing key from your Mux account to sign a JWT for a real-time space.

The workflow for signing a JWT typically goes like this:

• A JWT is created with an expiration in the future. See the section below on how to create a JWT.
• The JWT is signed on the server using a signing key. The signing key used to sign the JWT and the space ID specified in the JWT must be from the same Mux account and environment.
• The signed JWT is passed to the client.
• The client uses the signed JWT to authenticate to the Mux Spaces API when joining a space.

JWT Payload and authentication behavior

Access to a space is controlled by a JWT, which is passed in as the only parameter to the SDK when you want to join a space.

The signing keys for this JWT are the same ones that are used today to sign Video URLs. Signing keys are un-scoped and all existing signing keys are valid for spaces.

The layout of a JWT is a simple JSON object with a few fields. Here's an example JWT for accessing a space:

copy
{
  // 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 authenticate to the Mux Spaces SDK with that JWT.

What's the deal with participant_id, I hear you ask? The participant_id is an optional ID that you 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 choose.

Participant Enforcement

If a participant_id is not provided in the JWT, the Mux Space API will auto-generate an participant ID. Using the same JWT multiple times is allowed if there's no participant_id specified.

User-provided participant_ids can be used to optionally 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.

Signing the JWT

The next step is to use your signing key to sign the JWT. There are JWT-signing libraries available in most if not all of the major programming languages. Just remember to put your signing key and an appropriate expiration in the JWT itself, and sign the signing key that matches your signing key ID.

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.

5Integrate a Mux Spaces SDK

Once you've gone through these steps, you're ready to integrate real-time communications in to your application by following one of the following guides:

• Send and receive real-time video from a web application
• Send and receive real-time video from a React application
• Send and receive real-time video from an Android application
• Send and receive real-time video from an iOS application

Next Steps