Generate a Token from Your Server

This page provides Agora RTC SDK v2.1+, Agora Web SDK v2.4+, Agora Recording SDK v2.1+, and Agora RTSA SDK users with a quick guide on generating a sample token using the RtcTokenBuilderSample demos we provide, as well as token-generating API references in C++.

An introduction to Agora's token repository

Your token needs to be generated on your own server, hence you are required to first deploy a token generator on the server. In our GitHub Repository, we provide source codes and token generator demos in the following programming languages:

• CPP
• Java
• Python
• PHP
• Node.js
• Go
• Ruby

The ./<language>/src folder of each language holds source codes for generating different types of dynamic keys and tokens. Note that both AccessToken and SimpleTokenBuilder can generate a token for the following SDKs:

• Agora RTC SDK (Java, Objective-C, C++, Electron) v2.1+
• Agora Web SDK v2.4+
• Agora Recording SDK v2.1+
• Agora RTSA SDK

However, we recommend using RtcTokenBuilder instead of AccessToken. AccessToken implements all the core algorithms for generating a token, while RtcTokenBuilder is a wrapper of AccessToken and provides much more simplified Interfaces.

The ./<language>/sample folder of each language holds token generator demos we create for demonstration purposes. RtcTokenBuilderSample is a demo for generating a token for the Agora RTC SDK, Agora Web SDK, Agora Recording SDK or Agora RTSA SDK. You can customize it based on your real business needs.

Generate a token using RtcTokenBuilderSample

We take RtcTokenBuilderSample.cpp as an example:

1. Ensure that you have installed openssl. If you are using macOS, try the following command:
   brew install openssl
2. Synchronize the GitHub repository to your local drive.
3. Navigate to the /cpp/sample/ folder and open RtcTokenBuilderSample.cpp.

   Our demo provides pseudo-App ID, appCertificate, channelName, uid, and userAccount for demonstration purposes.

4. Replace the pseudo-App ID, appCertificate, and channelName with your own. For information about getting an App ID and an App certificate, see Token Security.
   • If you use an int uid to join a channel, comment out the following code block:

     result = SimpleTokenBuilder::buildTokenWithUserAccount(
     appID, appCertificate, channelName, userAccount, UserRole::Role_Attendee,
     privilegeExpiredTs);
     std::cout << "Token With UserAccount:" << result << std::endl;

   • If you use a string userAccount to join a channel, comment out the following code block:

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

     Skip this step if you just want to take a quick look at how a token is generated.

5. Open your terminal and navigate to the local folder holding RtcTokenBuilderSample.cpp.
6. Run the following command:
   g++ -std=c++0x -O0 -I../../ RtcTokenBuilderSample.cpp -lz -lcrypto -o RtcTokenBuilderSample
   An executable file RtcTokenBuilderSample appears in the folder.
7. In your terminal, run ./RtcTokenBuilderSample to generate a Token.
   Your token is printed in your terminal window.

Ensure that you have correctly set the environment variant of openssl. Suppose you are using macOS and if fatal error: 'openssl/hmac.h' file not found appears, try the followling command to debug:

1. Run the which openssl command in your terminal.
   The terminal prints: /usr/bin/openssl
2. cd /usr/local/include
3. ln -s ../opt/openssl/include/openssl .

API Reference

Source code: ../cpp/src/RtcTokenBuilder.h

You can create your own token generator using the public methods that RtcTokenBuilder.h provides. Note that RtcTokenBuilder.h supports both int uid and string userAccount. Ensure that you choose the right method.

buildTokenWithUid

   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);

This method build a token with your int uid.

buildTokenWithUserAccount

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

This method build a token with your string userAccount.