This page describes the token (Agora’s authentication mechanism). Before you start, check if your SDK version supports token:
|Agora SDK||Version that Supports the Token|
To get the SDK version, call the following API methods:
- Native SDK:
- Web SDK:
- Gaming SDK:
Agora’s Authentication Mechanisms
joinChannel method requires a security key as an essential parameter. The Agora SDK provides two different security key mechanisms based on your security requirements:
- For low-security requirements, such as for testing: App ID.
- For high-security requirements, such as for production: App ID + App Certificate + Token. Note that an App Certificate is enabled solely for the purposes of generating a Channel Key and cannot be used alone.
Authenticate using an App ID only
After signing up at Dashboard, you can create multiple projects and each project will have a unique App ID.
Anyone with your App ID can use it on any Agora SDK. Hence, it is prudent to safeguard the App IDs.
Get an App ID
- Sign up for a developer account at Agora Dashboard and follow the on-screen instructions to create a project.
- Click the Project Management icon in the left navigation panel.
- Find the corresponding App ID under the created project.
Use an App ID
You can access the Agora services with a unique App ID:
- Enter the App ID in the start window to enable communications.
- Add the App ID to the code when developing the application.
- Set the
appIdparameter as the App ID when initializing the client.
- Set the
tokenparameter as NULL when joining the channel.
Authenticate using Token
Agora recommends using a combination of App ID, App certificate, and token for authentication in production scenarios.
The following process generates a token:
- Deploy a token generator on your server.
- The client sends a request for a token to the server.
- The server uses the token generator to create a token and sends the token back to the client.
- The client passes the token when joining a channel.
- When the token is about to expire or has expired, repeat Steps 2 to 4.
- The application client calls
renewTokento use the new token.
Deploy a Token Generator
To use token for authentication, you need to deploy a token generator on your server to generate a token.
Agora provides the server-side sample codes supporting the following languages:
You can deploy the corresponding sample code on your server, or write your own code in a different programming language.
If you have implemented Agora’s algorithm in other languages, you can file a pull request on GitHub. Agora will merge any valid implementations and test cases.
Generate a Token
The application client needs to send the following parameters to the server to generate a token:
||The App ID of the user’s project in the Agora Dashboard, see Getting an App ID.|
||The App Certificate of the user’s project in the Agora Dashboard, see Getting an App Certificate.|
||Name of the channel that the user wants to join.|
||ID of the user who wants to join a channel.|
||The privilege expiration time. The default value is 0, where the token never expires. A user can join a channel indefinitely within the designated expiration time and will be removed from the channel after the expiration time.|
 Agora does not support signing Token with a non-zero string uid for the time being.
expireTimestampis 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
expireTimestampas the current timestamp + 600 (seconds). The expiration time for each token is independent, and you can set it through the
Get an App Certificate
Each Agora account can create multiple projects, and each project has a unique App ID and App Certificate.
To get an App Certificate:
Login to https://dashboard.agora.io.
Click the Edit button of the corresponding project on the Project Management page.
Click the Enable button next to the App Certificate.
Read the pop-up description of the App Certificate and click Save as promped.
The system sends your mail account a confirmation Email. Please follow the instruction to enable the App Certificate.
On the Project Management page, click the 'eye' icon to view and copy the App Certificate. You can re-click this icon to hide the App Certificate.
Keep the App Certificate on the server, never on any client machine.
The App Certificate takes about five minutes to take effect after it is enabled.
Once the App Certificate is enabled for a project, a token must be used. For example, before enabling the App Certificate, an App ID can be used to join a channel; but once an App Certificate is enabled, a token or a Channel Key must be used to join a channel.
Use a Token
Before a user joins a channel from the client：
The client requests authentication from your organization’s business server.
The server, upon receiving the request, generates a token using the token generator and sends the token back to the client.
To join a channel, the client calls the
joinmethod, which requires the token as the first parameter.
The Agora server receives the token and confirms that the call comes from a legitimate user, and then allows the user to access the Agora SD-RTN™ (Software Defined Real-time Network).
When you deploy the token, the token replaces the original App ID when a user joins a channel.
The token expires after a certain period of time. The application must call
renewTokenwhen notified by the
onTokenPrivilegeWillExpirecallback that the token is about to expire or has expired.
The token encoding uses the industry-standard HMAC/SHA1 approach and the libraries are available on most server-side development platforms, such as Node.js, Java, PHP, Python, and C++. For more information, see http://en.wikipedia.org/wiki/Hash-based_message_authentication_code.
If your SDK version is earlier than v2.1.0 and you wish to migrate to the latest version, see Token Migration Guide.
Learn how to generate a token on the server on the Generating a Token page.
The following table lists the API methods that require a token as a parameter:
|Platform||Join a Channel||Renew the Token|
|Android||Join a Channel (joinChannel)||Renew the Token (renewToken)|
|iOS/macOS||Join a Channel (joinChannelByToken)||Renew the Token (renewToken)|
|Windows||Join a Channel (joinChannel)||Renew the Token (renewtoken)|
|Web||Join an AgoraRTC Channel (join)||Renew the Token (renewToken)|