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.
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:
joinChannel
.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 |
|
On-premise Recording SDK | v2.1.0 or later |
Cloud Recording | No version requirement |
Interactive Gaming SDK | v2.2.0 or later |
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.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.
Download or clone the AgoraDynamicKey repository.
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
.
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
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:
AgoraDynamicKey/java
file in your IDE.AgoraDynamicKey/java/src/io/agora/sample/RtcTokenBuilderSample.java
file, replace the value of appID
, appCertificate
, channelName
, and uid
with your own, and comment out the code snippets of buildTokenWithUserAccount
.Python -V
AgoraDynamicKey/python/sample/RtcTokenBuilderSample.py
file, replace the value of appID
, appCertificate
, channelName
, and uid
with your own, and comment out the code snippets of buildTokenWithUserAccount
.RtcTokenBuilderSample.py
, and run the following command. The token is generated and printed in your Terminal window.
python RtcTokenBuilderSample.py
Python -V
AgoraDynamicKey/python/sample/RtcTokenBuilderSample.py
file, replace the value of appID
, appCertificate
, channelName
, and uid
with your own, and comment out the code snippets of buildTokenWithUserAccount
.RtcTokenBuilderSample.py
, and run the following command. The token is generated and printed in your Terminal window.
python RtcTokenBuilderSample.py
AgoraDynamicKey/sample/RtcTokenBuilderSample.php
file, replace the value of appID
, appCertificate
, channelName
, and uid
with your own, and comment out the code snippets of buildTokenWithUserAccount
.RtcTokenBuilderSample.php
, and run the following command. The token is generated and printed in your Terminal window.
php RtcTokenBuilderSample.php
npm install
AgoraDynamicKey/nodejs/sample/RtcTokenBuilderSample.js
file, replace the value of appID
, appCertificate
, channelName
, and uid
with your own, and comment out the code snippets of buildTokenWithUserAccount
.RtcTokenBuilderSample.js
, and run the following command. The token is generated and printed in your Terminal window.
node RtcTokenBuilderSample.js
AgoraDynamicKey/go/sample/RtcTokenBuilder/sample.go
file, replace the value of appID
, appCertificate
, channelName
, and uid
with your own, and comment out the code snippets of buildTokenWithUserAccount
.sample.go
, and run the following command. After that, an executable file RtcTokenBuilder
appears in the folder
go build
./RtcTokenBuilder
ruby -version
AgoraDynamicKey/ruby/sample/rtc_token_builder_sample.rb
file, replace the value of appID
, appCertificate
, channelName
, and uid
with your own, and comment out the code snippets of buildTokenWithUserAccount
.rtc_token_builder_sample.rb
, and run the following command. The token is generated and printed in your Terminal window.
ruby rtc_token_builder_sample.rb
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);
Parameter | Description |
---|---|
appId |
The App ID of your Agora project. |
appCertificate |
The App Certificate of your Agora project. |
channelName |
The unique channel name for the Agora RTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are:
|
uid |
The user ID. A 32-bit unsigned integer with a value range from 1 to (232 - 1). It must be unique. Set uid as 0, if you do not want to authenticate the user ID, that is, any uid from the app client can join the channel or log onto the service system. |
role |
The privilege of the user:
|
privilegeExpiredTs |
The Unix timestamp (s) when the token expires, represented by the sum of the current timestamp and the valid time of the token. For example, if you set privilegeExpiredTs as the current timestamp plus 600 seconds, the token expires in 10 minutes. A token is valid for 24 hours at most. If you set this parameter as 0 or a period longer than 24 hours, the token is valid for 24 hours. |
buildTokenWithUserAccount
method which enables you to generate a token with a user account in the string format, though we recommend not using it.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:
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.
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.
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.
You can also refer to the following documents according to your needs: