To ensure communication security, when users join an RTC channel or you start recording on the server, Agora needs to check their authentication information. Agora provides three authentication mechanisms. According to your scenarios, you can choose one of the following mechanisms:
|App ID||All clients in a channel use App ID for authentication.||Scenarios with low-security requirements.|
|Token||All clients in a channel use Token for authentication.||Scenarios with high-security requirements.|
|App ID or Token||In a channel, some clients use App ID for authentication, while others use Token.||Transition scenarios where your project upgrades from low-security to high-security requirements.|
After signing up for a developer account in Agora Console, you can create multiple projects. Each project has an App ID, which is the unique identity of the project. If others steal your App ID, they can use it in their own projects. Therefore, using an App ID for authentication is less secure. Agora recommends using an App ID for authentication only in a test environment, or if your project has low security requirements.
Sign up for a developer account at Agora Console. See Sign up for an Agora account.
Click in the left navigation menu to enter the Project Management page.
Enter your project name, choose the App ID authentication mechanism in the dialog box, and click Submit.
When the project is created successfully, you can see the newly created project in the project list. Click to view and copy the App ID.
You may need to enter the App ID when you call an API of an Agora project, such as initializing the SDK.
If you need to use a token for authentication, click Edit and enter the Edit Project page to enable an app certificate.No certificate means that your project uses only the App ID for authentication. No certificate appears only if you choose the APP ID authentication mechanism when creating a project.
Token is a dynamic key generated by App ID, App Certificate, user ID, channel name, token expiration timestamp, and other information. For scenarios requiring high-security, such as the production environment, Agora recommends using a token for authentication.
Scope of application
The following table lists Agora products which support tokens for authentication:
|Products||Versions of products which support tokens||Methods for getting SDK version|
|Voice or Video SDK (Native)||v2.1.0 or later||
|Voice or Video SDK (Web)||v2.4.0 or later||
|Voice or Video SDK (Electron)||All versions||
|Voice or Video SDK (Unity)||All versions||
|On-premise Recording SDK||v2.1.0 or later||/|
|Cloud Recording||All versions||/|
|Interactive Gaming SDK||v2.2.0 or later||
If you use an Agora product of a version earlier than mentioned above, you can upgrade your product version or use Channel Keys for authentication. If you upgrade your product from a version that supports channel keys to a version that supports tokens, please refer to Token Migration Guide.
Generate a token
You need to generate a token on your server. Follow the steps below to get the App ID, enable App Certificate, and call an API to generate a token.
1. Get an App ID
See Get an App ID.
An App Certificate is a string generated from Agora Console, and it enables token authentication. For different security requirements, Agora provides two types of app certificates. The differences are as follows:
- Primary certificate: You can use a primary certificate to generate tokens, including temporary tokens. You cannot delete a primary certificate.
- Secondary certificate: You can use a secondary certificate to generate tokens, except for temporary tokens. After enabling a secondary certificate, you can swap it for a primary certificate, or delete it.
If you enable an app certificate for the first time, you need to enable a primary certificate first.
To enable a primary certificate, do the following:
If you choose the APP ID + APP Certificate + Token authentication mechanism when creating a project, Agora enables the primary certificate for you by default. On the Edit Project page, you can click to view and copy the primary certificate.
If you choose the APP ID authentication mechanism when creating a project, you need to enable the primary certificate manually. On the Edit Project page, find Primary certificate and click Enable. Once the primary certificate is enabled, you can click to view and copy the primary certificate, and use either an App ID or the token generated by the primary certificate for authentication.
3. Generate a token
Generate a temporary token
- Ensure that you have enabled a primary certificate before generating a temporary token. See Enable a primary app certificate.
- A temporary token applies to scenarios requiring low security. Agora recommends using a token generated on your server for production environment.
- A temporary token does not apply to the Agora RTM SDK.
On the Project Management page, find the project for which you want to generate a temporary token, and click .
On the Token page, enter the name of the channel that you want to join, and click Generate Temp Token to get a temporary token.
- For production environment, Agora recommends generating a token at your server by calling
buildTokenWithUid. See Generate a token.
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);
|appId||The App ID of your project.|
|appCertificate||The app certificate of your project.|
|channelName||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.|
|role||The user role. Agora supports only one user role. Set the value as the default value
|privilegeExpiredTs||Expiration time of the token. A Unix timestamp, represented by the number of seconds elapsed since 1/1/1970. For example, if you set this parameter as the current timestamp + 600 seconds, the token expires 10 minutes after it is generated. 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.|
We provide an open source Agora Dynamic Key repository on GitHub, which covers developer languages such as C++, C#, Go, Java, Node.js, Perl, PHP, Python and Ruby. You can choose a language according to your development environment, and view the source code in the
src folder or the sample code in the
4. Switch and delete the primary certificate
After enabling a primary certificate, you can enable a secondary certificate. if the primary certificate is exposed to security risks, you can swap the secondary certificate for the primary certificate and delete the original primary certificate.
To switch and delete the primary app certificate, do the following:
- On the Edit Project page, find Secondary certificate, and click Enable. After successfully enabling a secondary certificate, users can use either the primary certificate or the secondary certificate to generate tokens for authentication.
- Click Set as primary to switch the secondary certificate and the primary certificate. Once you switch the primary certificate to the secondary certificate, all temporary tokens generated by the original primary certificate become invalid.
- Click Delete to delete the original primary certificate. You cannot restore the deleted certificate, and all tokens generated by the original primary certificate become invalid. You need to use the new primary certificate to generate tokens for authentication.
- After deletion, the status of the secondary certificate becomes Disabled. A new secondary certificate is generated when you click Enable next time.
Use the token
After generating a token, see the following steps to use the token:
- When a client app calls an Agora API for certain functions, such as joining a channel, the client app needs to fill in the generated token, the user name, the channel name, and other information.
- After the Agora server receives the token and other information, it authenticates the user's identity and decides if the user have the permission to join the channel. If the authentication is passed, the user can successfully join the channel and use the Agora services.
- Token has expiration time. Once the token expires, it becomes invalid, and you need to generate a new token on your app server. Use the new token for joining a channel or using the Agora services.
If you only use the App ID for authentication, you can follow the steps below for upgrading your project to use either an App ID or a token for authentication:
After successfully enabling a primary app certificate, use the primary app certificate to generate a token.
Use either an App ID or a token for authentication. For example, when existing users are using App ID for authentication, new users can use a token for authentication, and thus both new and old users can join the same channel. You can gradually phase out the use of App ID for authentication.
After all users switch to using a token for authentication, Agora recommends deleting No certificate.Once you delete No certificate, you can no longer use the App ID for authentication, and the project cannot enable No certificate again.