title: Use Security Keys description: platform: All Platforms updatedAt: Thu Aug 15 2019 06:15:08 GMT+0800 (CST)
Use Security Keys
We understand that security is a vital consideration when you integrate real-time communications into your application. To help you build an application that meets your security requirements, the Agora SDK provides two security mechanisms:
- For low-security requirements, use an App ID for authentication.
- For high-security requirements, use a dynamic key for authentication (recommended).
This page introduces Agora's two authentication mechanisms in details.
Scope of application
We have two types of dynamic keys: Channel Key and Token. Different versions of our SDK use different dynamic keys for authentication. This page mainly deals with the Token. So before you start, see the following table to check which type of dynamic key that your SDK version supports:
|Agora SDK||Versions supporting Token||Versions supporting Channel Key||How to check SDK version|
|Native SDK||2.1.0 or later||Earlier than 2.1.0||
|Web SDK||2.4.0 or later||Earlier than 2.4.0||
|Gaming SDK||2.2.0 or later||Earlier than 2.2.0||
Use an App ID only for authentication
Each project you create in Agora Dashboard has a unique App ID.
Get an App ID
Click Get Started under Projects.
Input your project name in the pop-up window and click Create. Follow the on-screen instructions to get to know the basic steps to start a video call. Once the project is created, you can find it under Projects.
- On the Project Management panel, find the App ID of your project.
Apply your App ID
When initializing the client, set the
appId parameter as the App ID that you get to authenticate your application.
When joining a channel, set the
tokenparameter as NULL.
Use a token for authentication
The Token is a more secure and sophisticated authentication mechanism than the App ID. You need to use an App ID and an App Certificate to generate a token for authentication.
Enable the App Certificate
If you choose APP ID + APP certificate + Token (recommended) when you create a project in the Dashboard, the App Certificate is enabled by default.
If you did not choose APP ID + APP certificate + Token (recommended), follow the steps to enable the certificate.
Find your project on the Project Management page at the Agora Dashboard and click the Edit button.
On the Edit Project page, click Enable to enable the App Certificate and click Save to confirm your setting.
We send you a confirmation Email. Follow the instruction to enable the App Certificate.
Go back to the Project Management page to check that the App Certificate is enabled.
Note: If you do not find the confirmation email in your inbox, check your spam or junk email folder.
Get a temporary token
When working on a test version of your application, you can generate a temporary token at the Agora Dashboard to join a channel.
On the Project Details page, click Generate a Temp Token, enter a channel name, and you will get a temporary token on the Token page.
- Ensure that you have enabled the App Certificate of the project before clicking Generate a Temp Token. See Enable the App Certificate.
- A temp token applies to scenarios with low security requirements. For the production environment, we recommend using a token generated at your server.
Get a token
When building the final production version of your application, you should generate a token on your server. See Generate a Token on Your Server.
Apply your token or temporary token
When calling the
join method to join a channel, you pass in your token (or temporary token).
- Ensure that the channel ID and user name that you use to join a channel are the same as the channel ID and user name that you use to create a token (or a temporary token).
- After a token (or a temporary token) is generated, the client should use the token to join a channel within 24 hours. Otherwise, you need to generate a new token (or temporary token).
- A token (or a temporary token) expires after a certain period of time. When the SDK notifies the client that the token is about to expire or has expired by the
onTokenExpiredcallbacks, you need to generate a new token and call the
- The token encoding uses the standard HMAC/SHA1 approach and the libraries are available on common server-side development platforms, such as Node.js, Java, PHP, Python, and C++. For more information, see Authentication code.
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)|