Introduction

This page describes how to use channel keys with the Agora SDK.

App ID

After signing up at Console, 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

To get an App ID, do the following:

  1. Sign up for a developer account at Agora Console. See Sign up for an Agora account.

  2. Click in the left navigation menu to enter the Project Management page.

  3. Click Create.

  4. Enter your project name, choose the App ID authentication mechanism in the dialog box, and click Submit.

Use an App ID

Access the Agora services by using your unique App ID:

  1. Enter the App ID in the start window to enable voice or video communication in the demo.

  2. Add the App ID to the code when developing the application.

  3. Set the appId parameter as the App ID when calling the following APIs:

    Platform API
    Android/Windows create
    iOS/macOS sharedEngineWithappId
    Web client.init
  4. Set the channelKey parameter to NULL when calling the following APIs:

    Platform API
    Android/Windows joinChannel
    iOS/macOS joinChannelByKey
    Web client.join

Step 2: Get an App Certificate

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.

Step 3: Integrate the Schema

Use the 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:

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 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.

[2]: 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
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:

  1. The client application requests authentication from your organization’s business server.

  2. 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

  3. 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
  4. 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 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