This page describes the token (Agora’s authentication mechanism). Before you start, check if your SDK version supports the token:
|Agora SDK||Version that Supports the Token|
To get the SDK version information, 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.
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.
Getting an App ID
Sign up for a developer account at https://dashboard.agora.io/.
Click Add New Project on the Projects page of Dashboard.
Fill in the Project Name and click Submit. You have created your first project at Agora.
Find the App ID under the created project.
Using an App ID
You can access the Agora services with the 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.
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 in 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.
Deploying a Token Generator
Before using a token, you need to deploy a token generator on your server to generate a token.
Agora provides the server-side sample code.
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.
Generating 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.|
Role of the user who wants to join a channel. Choose one of the following roles:
||Privileges corresponding to the specified roles. See Role-privilege Model.|
||The token 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.|
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
Getting 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 Add New Project on the Projects page of Dashboard.
Fill in the Project Name and click Submit. Find the App ID under the created project.
Enable the App Certificate for the project.
Click Edit on the top-right of the project.
Click Enable to the right of the App Certificate. Read About App Certificate before confirming the operation.
Click the ‘eye’ icon to view the App Certificate. You can re-click this icon to hide the App Certificate.
Contact email@example.com to renew an App Certificate.
Keep the App Certificate on the server, never on any client machine.
The App Certificate takes about an hour 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.
The design of a token is based on the authentication of different user roles, each of which is associated with a set of privileges.
- You must define the user role and expiration time when creating a token.
- When you join a channel with a token, the SDK sends the token to the Agora servers for authenticating the assigned privileges.
- During a call or live broadcast, you can update the token for the clients in the channel to modify their privileges.
|Attendee||Participants in a voice or video call.||
|Publisher||Users (Hosts) who publish video or/and voice streams in a live broadcast.||
|Subscriber||Users (Audience) who need to subscribe to the voice and video streams in a live broadcast.||
Using 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)|