Documentation
SDK Downloads
Sample Apps
FAQ
Security Keys¶
Introduction¶
This page describes how to use security keys with the Agora SDK.
App ID¶
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.
Channel Key¶
Agora recommends using a Channel Key for added security.
How to Get and Use an App ID¶
Get 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 the App ID under the created 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.
- Set the appId parameter as the App ID when calling the client.init() API.
- Set the channelKey parameter to NULL when calling the client.join() API.
Get a Channel Key¶
Step 1: Get an App ID¶
Step 2: Get an App Certificate¶
Each Agora account can create multiple projects, and each project has a unique App ID and App Certificate.
Login 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 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.
Note
- Contact support@agora.io to renew an App Certificate.
- Keep the App Certificate on the server, never on any client machine.
- It takes about an hour for the App Certificate to take effect after it is enabled.
- Once the App Certificate is enabled for a project, a Channel Key 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 Channel Key must be used to join a channel.
Step 3: Integrate the Schema¶
Use the generateMediaChannelKey method, and the 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/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:
| Field Name | C++ | Java | Python | Node.js | Go |
|---|---|---|---|---|---|
| App ID | appID | appID | appID | appID | appID |
| App Certificate | appCertificate | appCertificate | appCertificate | appCertificate | appCertificate |
| Channel | channelName | channel | channelName | channel | channelName |
| Timestamp [1] | unixTs | ts | unixTs | ts | unixTs |
| Random Number | randomInt | r | randomInt | r | randomInt |
| User ID | uid | uid | uid | uid | uid |
| Call Expiration Timestamp [2] | expiredTs | expiredTs | expiredTs | expiredTs | expiredTs |
| [1] | The timestamp, represented by the number of seconds elapsed since 1/1/1970. The user can use the Channel Key to access the Agora service within 5 minutes after the Channel Key is generated. If the user does not access the Agora service after 5 minutes, the Channel Key is no longer valid. |
| [2] | Set the value to 0 for no time duration 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 the Channel Key will be expired, but means the user will be kicked out of the channel. |
If you want 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 |
| DynamicKey | N/A | N/A |
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 join() API to join a channel, which requires the Channel Key as the first parameter.
- 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).
Note
- 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 renewChannelKey() when 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.