Skip to main content

How do I use co-host token authentication?

  • Using co-host authentication requires app logic changes. Ensure that you read this article before enabling this function.

  • Co-host authentication applies to scenarios where the channel profile is set to LIVE_BROADCASTING.

Understand the tech

Co-host authentication is the means by which the SDK authenticates whether a user has the privilege to publish streams in a live streaming channel.

This function guarantees that only authorized users can publish streams in a channel and prevents illegal users from deliberately disrupting a streaming session.

Prerequisites

Before proceeding, ensure that your app meets the following requirements:

  • Uses the Agora Video SDK v2.1.0 or later.
  • Uses only token-based authentication on all app clients to authenticate users. For details, see Upgrade authentication mechanism.

Implementation

1. Modify the parameter setting

This section introduces how to set the role parameter when generating a token using C++ as an example. The principles and goals are the same if you are using another programming language.


_31
// API
_31
static std::string buildTokenWithUid(
_31
const std::string& appId,
_31
const std::string& appCertificate,
_31
const std::string& channelName,
_31
uint32_t uid,
_31
UserRole role,
_31
uint32_t privilegeExpiredTs = 0);
_31
_31
_31
// Code sample
_31
int main(int argc, char const *argv[]) {
_31
_31
// Your App ID
_31
std::string appID = "970Cxxxxxxxxxxxxxxxxxxxxxxx1b33";
_31
// Your App Certificate
_31
std::string appCertificate = "5CFdxxxxxxxxxxxxxxxxxxxxxxx5d3b";
_31
// The channel name
_31
std::string channelName= "7d72xxxxxxxxxxxxxxxxxxxxxxbdda";
_31
// The user ID. If you set it as 0, the SDK does not authenticate the user
_31
uint32_t uid = 2882341273;
_31
// The expiration time of the token
_31
uint32_t expirationTimeInSeconds = 3600;
_31
uint32_t currentTimeStamp = time(NULL);
_31
uint32_t privilegeExpiredTs = currentTimeStamp + expirationTimeInSeconds;
_31
std::string result;
_31
_31
result = RtcTokenBuilder::buildTokenWithUid(
_31
appID, appCertificate, channelName, uid, UserRole::Role_Publisher,
_31
privilegeExpiredTs);
_31
std::cout << "Token With Int Uid:" << result << std::endl;

ParameterDescription
roleThe publishing privilege of the user:
  • Role_Publisher(1): (Default) The user has the publishing privilege.
  • Role_Subscriber(2): The user does not have the publishing privilege.

2. Change the app logic

Refer to the following steps to authenticate whether a user has the publishing privilege (in scenarios where an audience member wants to become a host:

  1. Before joining a channel, the app client applies for a token with the privilege of a subscriber. The app server generates a token and passes it to the app client.
  2. The app client calls joinChannel and passes the token to the SDK.
  3. Before changing the user role, the app client applies for a token with the privilege of a publisher. The app client generates a second toke, and passes it to the app client.
  4. The app client calls renewToken and passes the new token to the SDK.
  5. The app client calls setClientRole to change the user role from an audience member to a host. The Agora server authenticates the token when the app client calls setClientRole. If the token is generated with the privilege of a publisher, the app client can publish a stream.
  • If the user wants to switch from a host to an audience member, repeat steps 3 to 5. Apply for a token with the privilege of an audience, call renewToken on the app client, and then call setClientRole.

  • Once the token expires, you need to generate a new token on the app server and call renewToken to pass the new token to the SDK. The new token also has a service validity period.

3. Enable co-host authentication

Refer to the following steps to enable this function in Agora Console:

  1. Log on to Agora Console. Under Projects, choose a project for which you want to enable co-host authentication, click the Edit icon, and enter the Edit Project page.
  2. In the Features area, click Enable authentication.
  3. Follow the on-screen instructions to know more about this function, check the box, and click Enable.

Co-host authentication takes effect in 5 minutes.

Once you have enabled co-host authentication, a user using your app must meet both of the following requirements to publish streams in a channel:

  • The user role in setClientRole is set as BROADCASTER.
  • The user joins the channel with a token that has the privilege of a publisher (by setting the role parameter in the buildToken method as Role_Publisher).

Reference

1. Suppose a user takes the role of broadcaster. After I enable co-host authentication, will the user be able to publish streams?

Answer: Yes. After the token expires, you need to generate a new token with the privilege of a publisher, and call renewToken to pass the new token to the SDK.

2. Suppose a user takes the role of audience. After I enable co-host authentication, what should I do if this user wants to switch to broadcaster and publish streams?

Answer: Once co-host authentication is enabled, a user needs to meet both of the following requirements to publish streams:

  1. The user role in setClientRole is set as BROADCASTER.
  2. The user joins the channel with a token that has the privilege of a publisher (by setting the role parameter in the buildToken method as Role_Publisher).

Therefore, for an audience member to become a host and publish streams, you need to follow steps in Change the app logic: generate a token with the privilege of a publisher, call renewToken to pass the new token to the SDK, and then call setClientRole to change the user role to broadcaster.

Page Content