This page describes how to use channel keys with the Agora SDK.
After signing up at Dashboard, multiple projects can be created. Each project will be assigned 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 a Channel Key
Step 1: 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.
Click the Edit button behind the new project, or the Project Management button in the left navigation menu to go to the Project Management page.
On the Project Management panel, find the App ID of your project.
Use an App ID
Access the Agora services by using your unique App ID:
Enter the App ID in the start window to enable voice or video communication in the demo.
Add the App ID to the code when developing the application.
appIdparameter as the App ID when calling the following APIs:
Platform API Android/Windows create iOS/macOS sharedEngineWithappId Web client.init
channelKeyparameter to NULL when calling the following APIs:
Platform API Android/Windows joinChannel iOS/macOS joinChannelByKey Web client.join
Step 2: Get an 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 switch on the App Certificate and click Save to confirm your setting.
Agora sends your account a confirmation Email. Follow the instruction to enable the App Certificate.
Go back to the Project Management page, your can see App Certificate appears enabled.
Note: Check the Spam Email or Junk Email, if there's no confirmation Email in your inbox.
Step 3: Integrate the Schema
generateMediaChannelKey method and sample code provided by Agora to acquire the Channel Key. Agora provides server-side sample code in programming languages, such as Java, C++, Python, and Node.js.
Go to https://github.com/AgoraIO/Tools/tree/master/DynamicKey/AgoraDynamicKey to download the corresponding code and integrate it directly into your application.
Enter the following parameters into your application. The field names vary according to different programming languages:
|Call Expiration Timestamp ||expiredTs||expiredTs||expiredTs||expiredTs||expiredTs|
: The timestamp, represented by the number of seconds elapsed since 1/1/1970. The user can use the Dynamic Key to access the Agora service within 5 minutes after the Dynamic Key is generated. If the user does not access the Agora service after 5 minutes, the Dynamic Key is no longer valid.
: Set the value to 0 for no time limit. Indicates the exact time when a user can no longer use the Agora service (for example, when a user is forced to leave an ongoing call). When the value is set for Call Expiration Timestamp, it does not mean that the Dynamic Key will be expired, but means that the user will be kicked out of the channel.
To verify the user ID (uid), check the following requirements:
|DynamicKey Version||User ID||SDK Version|
|DynamicKey4||uid of the specific user||1.3 or later|
|DynamicKey3||uid of the specific user||1.2.3 or later|
Step 4: Use a Channel Key
Before a user joins a channel (start a call or receive an invitation), the following sequence occurs：
The client application requests authentication from your organization’s business server.
The server, upon receiving the request, uses the algorithm provided by Agora to generate a Channel Key and then passes the Channel Key back to the client application.
The Channel Key is based on the App Certificate, App ID, Channel Name, Current Timestamp, Client User ID, and Lifespan Timestamp
The client application calls the following API to join a channel, which requires the Channel Key as the first parameter.
Platform API Android/Windows joinChannel iOS/macOS joinChannelByKey Web join
The Agora server receives the Channel Key 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 Channel Key, it replaces the original App ID when someone joins a channel.
- The Channel Key expires after a certain period of time. Your application must call
renewChannelKeywhen a timeout occurs. The onError or didOccurError callback returns ERR_CHANNEL_KEY_EXPIRED (109).
- The Channel Key encoding uses the industry-standard HMAC/SHA1 approach and the libraries are available on most server-side development platforms, such as Node.js, PHP, Python, and Ruby. For more information, see: http://en.wikipedia.org/wiki/Hash-based_message_authentication_code