Agora Keys User Guide

Introduction

This document describes the concepts of and how to use different keys with Agora SDKs.

App ID

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

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.

  1. Sign up for a new account at https://dashboard.agora.io/.

  2. Click Add New Project on the Projects page of the dashboard.

  3. Fill in the Project Name and click Submit.

    ../../_images/create_project.png
  4. 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:

  1. Enter the App ID in the starting window to enable audio or video communication in the demo.
  2. Add the App ID to your code when developing the application.
  3. Set the parameter appId as the App ID when calling the following API:
Platform API
Android/Windows create
iOS/Mac sharedEngineWithappId
Web init
  1. 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.

  1. Log in to https://dashboard.agora.io.

  2. Click Add New Project on the Projects page of the dashboard.

  3. Fill in the Project Name and click Submit. Find the App ID under the project you’ve created.

    ../../_images/create_project.png
  4. Enable the App Certificate for the project.

  1. Click Edit on the top right of the project.

  2. Click Enable to the right of App Certificate. Read the description About App Certificate carefully before you confirm the operation.

    ../../_images/enable_app_cert.png
  3. Click the ‘eye’ icon to view the App Certificate. You can re-click this icon to hide the App Certificate.

    ../../_images/view_app_certificate.png

Note

  • If you want to renew an App Certificate, contact support@agora.io.
  • 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.

Note

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 [1]
Channel Key generateMediaChannelKey App Certificate, App ID, Channel Name, Current Timestamp, Client User ID, Random Numbers, Lifespan Timestamp

Footnotes

[1]The required fields are not the same in different programming languages, see Field Mapping for details.

Field Mapping

Field 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 [2] unixTs ts unixTs ts unixTs
Random Number randomInt r randomInt r randomInt
User ID uid uid uid uid uid
Call Expiration Timestamp [3] expiredTs expiredTs expiredTs expiredTs expiredTs

Footnotes

[2]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.
[3]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.

DynamicKey Version

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
DynamicKey N/A N/A

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:

  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.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.
  1. 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()
  1. 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.

Note

  • 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):

Input:

appId             = "C5D15F8FD394285DA5227B533302A518" //App ID
appCertificate    = "fe1a0437bf217bdd34cd65053fb0fe1d" //App Certificate
expiredTime       = "2592000" // Authorized Timestamp
account           = "test@agora.io" //The Used ID defined by the client.

Connect all fields in the sequence shown:

Field Type Length Description
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).
Sign String 32

Hex code for the signature. A string calculated by the MD5 algorithm based on inputs including the App Certificate and the following fields:

  • account: The User ID defined by the client.
  • appId: 32-character App ID string.
  • appCertificate: 32-character App Certificate string.
  • expiredTime: The UTC timestamp indicates that from the specific moment the user cannot access the Agora Signaling System any more.

Output:

token       = "1:appId:expiredTime:md5(account + appId + appCertificate + expiredTime)"
            = "1:C5D15F8FD394285DA5227B533302A518:2592000:md5(test@agora.ioC5D15F8FD394285DA5227B533302A518fe1a0437bf217bdd34cd65053fb0fe1d2592000)"
            = "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:

  1. The client application requests authentication from the business server of your organization.
  2. 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.
  1. The client application calls the login method, and it is required to set the parameter token as the Signaling Key generated above.
  2. 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.