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:
- Ensure that you have installed openssl. If you are using macOS, try the following command:
brew install openssl
- Synchronize the GitHub repository to your local drive.
- Navigate to the /cpp/sample/ folder and open RtcTokenBuilderSample.cpp.
Our demo provides pseudo-App ID, appCertificate, channelName, uid, and userAccount for demonstration purposes.
- 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.
- If you use an int uid to join a channel, comment out the following code block:
- Open your terminal and navigate to the local folder holding RtcTokenBuilderSample.cpp.
- Run the following command:
g++ -std=c++0x -O0 -I../../ RtcTokenBuilderSample.cpp -lz -lcrypto -o RtcTokenBuilderSample
An executable file RtcTokenBuilderSample appears in the folder. - 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:
- Run the
which openssl
command in your terminal.
The terminal prints:/usr/bin/openssl
cd /usr/local/include
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 builds a token with your int uid.
Parameter | Description |
---|---|
appID |
The App ID issued to you by Agora. Apply for a new App ID from Agora Console if it is missing from your kit. See Get an App ID. |
appCertificate |
Certificate of the application that you registered in the Agora Console. See Get an App Certificate. |
channelName |
Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are: |
uid |
User ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). optionalUid must be unique. |
role 1 |
Role_Publisher = 1 : (Recommended) A broadcaster (host) in a live-broadcast profile.Role_Subscriber = 2 : An audience in a live-broadcast profile. |
privilegeExpiredTs |
Time represented by the number of seconds elapsed since 1/1/1970. If, for example, you want to access the Agora Service within 10 minutes after the token is generated, set expireTimestamp as the current timestamp + 600 (seconds). Set it as 0 if the privilege never expires. |
role
enums share exactly the same privileges. To enable privilege authentication with a Token, e.g., to remove the upstreaming privilege of the audience, contact sales-us@agora.io.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 builds a token with your string userAccount.
Parameter | Description |
---|---|
appID |
The App ID issued to you by Agora. Apply for a new App ID from Agora Console if it is missing from your kit. See Get an App ID. |
appCertificate |
Certificate of the application that you registered in the Agora Console. See Get an App Certificate. |
channelName |
Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are: |
userAccount |
The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: |
role 2 |
Role_Publisher = 1 : (Recommended) A broadcaster (host) in a live-broadcast profile.Role_Subscriber = 2 : An audience in a live-broadcast profile. |
privilegeExpiredTs |
Time represented by the number of seconds elapsed since 1/1/1970. If, for example, you want to access the Agora Service within 10 minutes after the token is generated, set expireTimestamp as the current timestamp + 600 (seconds). Set it as 0 if the privilege never expires. |
role
enums share exactly the same privileges. To enable privilege authentication with a Token, e.g., to remove the upstreaming privilege of the audience, contact sales-us@agora.io.
You can also