Distribute Participant Tokens - Amazon IVS

Distribute Participant Tokens

                Distribute participant tokens: Stage token workflow

Now that you have a stage, you need to create and distribute tokens to participants to enable them to join the stage and start sending and receiving video.

As shown above, a client application asks your server application for a token, and the server application calls CreateParticipantToken using an AWS SDK or SigV4 signed request. Since AWS credentials are used to call the API, the token should be generated in a secure server-side application, not the client-side application.

When creating a participant token, you can optionally specify the capabilities enabled by that token. The default is PUBLISH and SUBSCRIBE, which allows the participant to send and receive audio and video, but you could issue tokens with a subset of capabilities. For example, you could issue a token with only the SUBSCRIBE capability for moderators. In that case, the moderators could see the participants that are sending video but not send their own video.

You can create participant tokens via the console or CLI for testing and development, but most likely you will want to create them with the AWS SDK in your production environment.

You will need a way to distribute tokens from your server to each client (e.g., via an API request). We do not provide this functionality. For this guide, you can simply copy and paste the tokens into client code in the following steps.

Important: Treat tokens as opaque; i.e., do not build functionality based on token contents. The format of tokens could change in the future.

Console Instructions

  1. Navigate to the stage you created in the prior step.

  2. Select Create a participant token. The Create a participant token window appears.

  3. Enter a user ID to be associated with the token. This can be any UTF-8 encoded text.

  4. Select Create a participant token.

  5. Copy the token. Important: Be sure to save the token; IVS does not store it and you cannot retrieve it later.

CLI Instructions

Creating a token with the AWS CLI requires that you first download and configure the CLI on your machine. For details, see the AWS Command Line Interface User Guide. Note that generating tokens with the AWS CLI is good for testing purposes, but for production use, we recommend that you generate tokens on the server side with the AWS SDK (see instructions below).

  1. Run the create-participant-token command with the stage ARN. Include any or all of the following capabilities: "PUBLISH", "SUBSCRIBE".

    aws ivs-realtime create-participant-token --stage-arn arn:aws:ivs:us-west-2:376666121854:stage/VSWjvX5XOkU3 --capabilities '["PUBLISH", "SUBSCRIBE"]'
  2. This returns a participant token:

    { "participantToken": { "capabilities": [ "PUBLISH", "SUBSCRIBE" ], "expirationTime": "2023-06-03T07:04:31+00:00", "participantId": "tU06DT5jCJeb", "token": "eyJhbGciOiJLTVMiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NjE1NDE0MjAsImp0aSI6ImpGcFdtdmVFTm9sUyIsInJlc291cmNlIjoiYXJuOmF3czppdnM6dXMtd2VzdC0yOjM3NjY2NjEyMTg1NDpzdGFnZS9NbzhPUWJ0RGpS123JldmVudHNfdXJsIjoid3NzOi8vdXMtd2VzdC0yLmV2ZW50cy5saXZlLXZpZGVvLm5ldCIsIndoaXBfdXJsIjoiaHR0cHM6Ly82NmY3NjVhYzgzNzcuZ2xvYmFsLndoaXAubGl2ZS12aWRlby5uZXQiLCJjYXBhYmlsaXRpZXMiOnsiYWxsb3dfcHVibGlzaCI6dHJ1ZSwiYWxsb3dfc3Vic2NyaWJlIjp0cnVlfX0.MGQCMGm9affqE3B2MAb_DSpEm0XEv25hfNNhYn5Um4U37FTpmdc3QzQKTKGF90swHqVrDgIwcHHHIDY3c9eanHyQmcKskR1hobD0Q9QK_GQETMQS54S-TaKjllW9Qac6c5xBrdAk" } }
  3. Save this token. You will need this to join the stage and send and receive video.

AWS SDK Instructions

You can use the AWS SDK to create tokens. Below are instructions for the AWS SDK using JavaScript.

Important: This code must be executed on the server side and its output passed to the client.

Prerequisite: To use the code sample below, you need to install the aws-sdk/client-ivs-realtime package. For details, see Getting started with the AWS SDK for JavaScript.

import { IVSRealTimeClient, CreateParticipantTokenCommand } from "@aws-sdk/client-ivs-realtime"; const ivsRealtimeClient = new IVSRealTimeClient({ region: 'us-west-2' }); const stageArn = 'arn:aws:ivs:us-west-2:123456789012:stage/L210UYabcdef'; const createStageTokenRequest = new CreateParticipantTokenCommand({ stageArn, }); const response = await ivsRealtimeClient.send(createStageTokenRequest); console.log('token', response.participantToken.token);