We understand that security is a vital consideration when you integrate real-time communications into your application. To help you build an application that meets your security requirements, the Agora SDK provides two security mechanisms:

  • For low security requirements, use an App ID for authentication.
  • For high security requirements, use a dynamic key for authentication (recommended).

This page introduces Agora's two authentication mechanisms in details.

Scope of application

We have two types of dynamic keys: Channel Key and Token. Different versions of our SDK use different dynamic keys for authentication. This page mainly deals with the Token. So before you start, see the following table to check which type of dynamic key that your SDK version supports:

Agora SDK Versions supporting Token Versions supporting Channel Key How to check SDK version
Native SDK 2.1.0 or later Earlier than 2.1.0 getSdkVersion
Web SDK 2.4.0 or later Earlier than 2.4.0 AgoraRtc.VERSION
Gaming SDK 2.2.0 or later Earlier than 2.2.0 getSdkVersion

Prerequisites

Ensure that you have signed up for a developer account at the Agora Dashboard and follow the on-screen instructions to create your first project.

Use an App ID only for authentication

Each project you create at the Agora Dashboard has a unique App ID.

Get an App ID

To get an App ID, follow these steps:

  1. Click in the left navigation menu to go to the Project Management page.
  2. Find the App ID that corresponds to your project.

Apply your App ID

When initializing the client, set the appId parameter as the App ID you get to authenticate your application.

When joining a channel, set the token parameter as NULL.

Use a token for authentication

The Token is a securer and more sophisticated authentication mechanism than the App ID. You need to use an App ID and an App Certificate to generate a token for authentication.

Enable the App Certificate

For your first Agora project, take the following steps to enable the App Certificate:

  1. Find your project on the Project Management page at the Agora Dashboard and click the Edit button.

  2. On the Edit Project page, click Enable to switch on the App Certificate and click Save to confirm your setting.

  3. Agora sends your account a confirmation Email. Follow the instruction to enable the App Certificate.

Your App Certificate appears enabled on the Project Management page.

Get a temporary token

When working on a test version of your application, you can generate a temporary token at the Agora Dashboard. Use either of the following ways to generate a temporary token:

  • On the Project Details page, click Generate a Temp Token, enter a channel name, and you will get a temporary token on the Token page.
  • When creating a project, choose APP ID + APP certificate + Token (recommended) to have the Dashboard enable the App Certificate for you, and click Generate a Temp Token to get your temporary token.

Get a token

When building the final production version of your application, you should generate a token on your server.

1. Deploy a token generator on your server

First, use one of the Agora sample codes (C++, Go, Java, Node.js, Python, PHP, and Perl) to deploy a token generator on your server.

Or you can write your own code in a programming language that is not mentioned above to deploy a token generator.

If you implement a token generator in a different language, you can file propose a pull request on GitHub. We will merge any implementation that proves valid.

2. Generate a token

The process of generating a token is as follows:

  1. The client sends a request for a token to your server.
  2. The server uses the token generator you deploy to create a token and sends it back to the client.

The application client needs to send the following parameters to the server to generate a token:

Name Description
appID The App ID of the user’s project in the Agora Dashboard.
appCertificate The App Certificate of the user’s project in the Agora Dashboard.
channelName Name of the channel that the user wants to join.
uid ID of the user who wants to join a channel.
expireTimestamp [1] The privilege expiration time. The default value is 0 and by default the token never expires. A user can join a channel indefinitely within the designated expiration time and will be removed from the channel after the expiration time.

[1] expireTimestamp is represented by the number of seconds elapsed since 1/1/1970. If, for example, you want to access the Agora Service within 10 minutes after the token is generated, set expireTimestamp as the current timestamp + 600 (seconds). The expiration time for each token is independent, and you can set it through the setPrivilege method.

For the methods and parameters involved, see Generate a Token on Your Server.

Apply your token or temporary token

When calling the join method to join a channel, you pass your token (or temporary token).

  • Ensure that the channel ID and user name you use to join a channel are the same as the channel ID and user name you use to create a token (or a temporary token).
  • After a token (or a temporary token) is generated, the client should use the token to join a channel within 24 hours. Otherwise, you need to generate a new token (or temporary token).
  • A token (or a temporary token) expires after a certain period of time. When the SDK notifies the client that the token is about to expire or has expired by the onTokenPrivilegeWillExpire or onTokenExpired callbacks, you need to generate a new token and call the renewToken method.
  • The token encoding uses the standard HMAC/SHA1 approach and the libraries are available on common server-side development platforms, such as Node.js, Java, PHP, Python, and C++. For more information, see Authentication code.

References

The following table lists the API methods that require a token as a parameter:

Platform Join a Channel Renew the Token
Android Join a Channel (joinChannel) Renew the Token (renewToken)
iOS/macOS Join a Channel (joinChannelByToken) Renew the Token (renewToken)
Windows Join a Channel (joinChannel) Renew the Token (renewtoken)
Web Join an AgoraRTC Channel (join) Renew the Token (renewToken)