The Token, also known as the dynamic key, is used for authenticating app users when a user joins a channel, or logs onto the service system.

This article introduces how to generate a token on your server using the code provided by Agora.

Introduction

Tokens are generated on your server. When an app user joins a channel or logs onto the service system, the app client interacts with the app server in the following way:

1. The app client sends a request for token to the app server.
2. The app server generates a token.
3. The app server passes the token back to the app client.
4. The app client then passes the token to the Agora server by calling the method provided by the SDK, such as joinChannel.

Prerequisites

Before proceeding, ensure that your project and the Agora product that you use meet the following requirements:

• Your Agora project has enabled the App Certificate on Console.

• The version of the Agora product that you use meet the following requirements:

  Product	Versions that support tokens
  RTC SDK	The Native SDK: v2.1.0 or later The Web SDK: v2.4.0 or later Third-party framework SDKs: All versions
  On-premise Recording SDK	v2.1.0 or later
  Cloud Recording	No version requirement
  Interactive Gaming SDK	v2.2.0 or later

Implementation

Agora provides an open-source AgoraDynamicKey repository on GitHub, which enables you to generate tokens on your server with programming languages such as C++, Java, Python, PHP, Ruby, Node.js, and Go. Take C++ as an example, the following picture shows the code structure:

Under the cpp directory:

• ./sample/RtcTokenBuilderSample.cpp contains the sample code for generating a token.
• ./src/RtcTokenBuilder.h contains the API used for generating a token.

Generate a token with the sample code

Under the sample directory of each programming language, you can find the sample code for generating a token. Take C++ as an example:

int main(int argc, char const *argv[]) {

  // Fill in your App ID
  std::string appID  = "970Cxxxxxxxxxxxxxxxxxxxxxxx1b33";
  // Fill in your App Certificate
  std::string  appCertificate = "5CFdxxxxxxxxxxxxxxxxxxxxxxx5d3b";
  // Fill in the channel name
  std::string channelName= "7d72xxxxxxxxxxxxxxxxxxxxxxbdda";
  // Fill in the user ID. 0 means that the server does not authenticate user IDs.
  uint32_t uid = 2882341273;
  // The timestamp for the token to expire
  uint32_t expirationTimeInSeconds = 3600;
  uint32_t currentTimeStamp = time(NULL);
  uint32_t privilegeExpiredTs = currentTimeStamp + expirationTimeInSeconds;
  std::string result;

  result = RtcTokenBuilder::buildTokenWithUid(
      appID, appCertificate, channelName, uid, UserRole::Role_Publisher,
      privilegeExpiredTs);
  std::cout << "Token With Int Uid:" << result << std::endl;

Refer to the following steps to generate a token with the sample code above.

Before proceeding, ensure that you have installed OpenSSL.

1. Download or clone the AgoraDynamicKey repository.

2. Open the AgoraDynamicKey/cpp/sample/RtcTokenBuilderSample.cpp file, replace the value of appID, appCertificate, channelName, and uid with your own, and comment out the code snippets of buildTokenWithUserAccount.

3. Open your Terminal, navigate to the same directory that holds RtcTokenBuilderSample.cpp, and run the following command. After that, an executable file RtcTokenBuilderSample appears in the folder:

    g++ -std=c++0x -O0 -I../../ -L. RtcTokenBuilderSample.cpp -lz -lcrypto -o RtcTokenBuilderSample

4. Run the following command. You token is generated and printed in your Terminal window.

    ./RtcTokenBuilderSample

Steps for generating a token with the sample code of different programming languages are as follows:

Python -V

Python -V

ruby -version

API reference

This section introduces the method to generate a token. Take C++ as an example:

static std::string buildTokenWithUid(
    const std::string& appId,
    const std::string& appCertificate,
    const std::string& channelName,
    uint32_t uid,
    UserRole role,
    uint32_t privilegeExpiredTs = 0);

Deploy a token server

Agora also provides blog posts that introduce how to deploy a token generator on your server. Refer to the following links per your server-side programming language:

• Go
• Node.js

Considerations

Channel name and user ID

The channel name and user ID that you use to generate the token must be the same with those that you use to join the channel.

App Certificate and token

To use the token for authentication, you need to enable the App Certificate for your project on Console. Once a project has enabled the App Certificate, you must use tokens to authenticate its users.

Token expiration

A token is valid for 24 hours at most. To ensure the experience of your app user, the Agora SDK that you use triggers the following callbacks when a token expires:

• onTokenPrivilegeWillExpire: Occurs when the token expires in 30 seconds.
• onRequestToken (onTokenPrivilegeDidExpire on the Web platform): Occurs when the token has expired.

Upon receiving either callback, you need to generate a new token on your server, and call renewToken to pass the new token to the SDK.

Reference

You can also refer to the following documents according to your needs:

• How to solve token-related errors?
• What causes the 101 error on Cloud Recording SDK?
• How to use co-host token authentication?