Agora Keys User Guide¶
This document describes the concepts of and how to use different keys with Agora SDKs.
Each Agora account can create multiple projects, and each project has a unique App ID. In our network, the App ID sets you apart from others. There is no overlap, even when channels have the same name. However an App ID is a static key, and if someone else illicitly obtains your static App ID, then they can use it for their own Agora Native SDK client applications. If they find out the channel names of your organization, they can even interfere with your communication sessions.
Thus, App ID is used for test/lab or non-recording and low security purposes.
Dynamic Key is a more secure user authentication schema for the Agora Native SDK. Dynamic Key is a general name compared with App ID, and it has different names for different services:
- Channel Key for joining a channel;
- Signaling Key for logging onto the Agora Signaling System;
Obtaining and Using an App ID¶
Obtaining an App ID¶
Each Agora account can create multiple projects, and each project has a unique App ID.
Sign up for a new account at https://dashboard.agora.io/.
Click Add New Project on the Projects page of the dashboard.
Fill in the Project Name and click Submit.
Find your App ID under the project that you have created.
Using an App ID¶
Access the Agora services by using your unique App ID:
- Enter the App ID in the starting window to enable audio or video communication in the demo.
- Add the App ID to your code when developing the application.
- Set the parameter appId as the App ID when calling the following API:
Platform API Android/Windows create iOS/Mac sharedEngineWithappId Web init
- Set the channelKey parameter to NULL when calling the following API:
Platform API Android/Windows joinChannel iOS/Mac joinChannelByKey Web join
Obtaining and Using a Dynamic Key¶
Follow this section to use the specific Dynamic Key according to your actual needs:
Obtaining an App ID and an App Certificate¶
Each Agora account can create multiple projects, and each project has a unique App ID and App Certificate.
Log in to https://dashboard.agora.io.
Click Add New Project on the Projects page of the dashboard.
Fill in the Project Name and click Submit. Find the App ID under the project you’ve created.
Enable the App Certificate for the project.
- If you want to renew an App Certificate, contact firstname.lastname@example.org.
- Keep your App Certificate on the server and never on any client machine.
- It takes around one hour for the App Certificate to take effect after it is enabled.
- Once the App Certificate is enabled for a project, you must use a Dynamic Key. For example, before enabling the App Certificate, you can use App ID to join channel, but once App Certificate is enabled, you must use a Channel Key to join channel.
Implementing the Dynamic Key Schema¶
Integrate the Dynamic Key scheme into your organization’s signaling service. Agora.io provides sample server-side code covering the following languages: Java, C++, Python, node.js, and so on, which you can use to integrate this code directly into your application. For the sample code, refer to https://github.com/AgoraIO/AgoraDynamicKey.
This section is only applicable to Channel Key. For Signaling Key, see Implementing the Signaling Key Schema for details, which will be updated the same as the other Dynamic Keys in the future releases.
|Dynamic Key||Method||Required Fields |
|Channel Key||generateMediaChannelKey||App Certificate, App ID, Channel Name, Current Timestamp, Client User ID, Random Numbers, Lifespan Timestamp|
|||The required fields are not the same in different programming languages, see Field Mapping for details.|
|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, this Dynamic Key is no longer valid.|
|||Set the value to 0 for no limitation to the time of termination. Indicates the exact time when a party can no longer use the Agora service (for example, when someone is forced to leave an ongoing call). When the value is set for Call Expiration Timestamp, it does not mean Dynamic Key will be expired, but only means the user will be kicked out from the channel.|
If you want to verify the User ID (UID), check the following compatibilities:
|DynamicKey Version||User ID (UID)||SDK Version|
|DynamicKey5||UID of the specific user||1.3 or later|
|DynamicKey4||UID of the specific user||1.3 or later|
|DynamicKey3||UID of the specific user||1.2.3 or later|
If you do not want to verify the User ID (UID), there is no compatibility issue, but we recommend that you upgrade to DynamicKey5.
Using a Channel Key¶
Before a user joins a channel(that is, has started a call or received a meeting 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.io to generate a Channel Key and then passes the Channel Key back down to the client application.
The Channel Key is based on the App Certificate, App ID, Channel Name, Current Timestamp, Client User ID, Lifespan Timestamp, and so on.
- 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/Mac joinChannelByKey() Web join()
- The Agora server receives the Channel Key and confirms that the call comes from a legal user, and then allows it to access the Agora SD-RTN.
- When you deploy the Channel Key, it replaces the original App ID when someone joins a channel.
- Channel Key expires after a certain amount of time. Your application must call renewChannelKey() when a time-out occurs. The onError or didOccurError callback returns ERR_CHANNEL_KEY_EXPIRED (109).
- The Channel Key encoding uses the industry-standard HMAC/SHA1 approach and libraries are available on most common server-side development platforms, such as node.js, PHP, Python, Ruby and others. For more information, refer to: http://en.wikipedia.org/wiki/Hash-based_message_authentication_code
Using a Signaling Key¶
Implementing the Signaling Key Schema¶
Use the following algorithm to generate a token(Signaling Key):
appId = "C5D15F8FD394285DA5227B533302A518" //App ID appCertificate = "fe1a0437bf217bdd34cd65053fb0fe1d" //App Certificate expiredTime = "2592000" // Authorized Timestamp account = "email@example.com" //The Used ID defined by the client.
Connect all fields in the sequence shown:
|Version||String||Signaling Key version number, fixed as 1.|
|App ID||String||32||App ID provided by Agora, which you can obtain at https://dashboard.agora.io.|
|Authorized Timestamp||Number||10||The UTC timestamp represented by the number of seconds elapsed since 1-1-1970. Indicates the exact time when a party can no longer use the Agora service (for example, when someone is forced to leave an ongoing call).|
Hex code for the signature. A string calculated by the MD5 algorithm based on inputs including the App Certificate and the following fields:
token = "1:appId:expiredTime:md5(account + appId + appCertificate + expiredTime)" = "1:C5D15F8FD394285DA5227B533302A518:2592000:md5(firstname.lastname@example.orgC5D15F8FD394285DA5227B533302A518fe1a0437bf217bdd34cd65053fb0fe1d2592000)" = "1:C5D15F8FD394285DA5227B533302A518:2592000:5c0ee12fdf2020d0d0fdad04d6395473"
The generated token is the Signaling Key for you to log onto the Agora signaling system according to Using the Signaling Key .
Using the Signaling Key¶
Before a user requests to log into the Agora signaling system:
- The client application requests authentication from the business server of your organization.
- The server, upon receiving the request, uses the algorithm provided by Agora.io to generate a Signaling Key and then passes the Signaling Key back down to the client application.
The Signaling Key is based on the App Certificate, App ID, User ID defined by the client and Authorized Timestamp.
- The client application calls the login method, and it is required to set the parameter token as the Signaling Key generated above.
- The Agora server receives the Signaling Key and confirms that the call comes from a legal user, and then allows it to access the Agora Signaling System.