This page describes the token (Agora’s authentication mechanism). Before you start, check if your SDK version supports the token:

Agora SDK Version that Supports the Token
Native 2.1.0 and later
Web 2.4.0 and later
Gaming 2.2.0 and later

To get the SDK version information, call the following API methods:

  • Native SDK: getSdkVersion
  • Web SDK: AgoraRTC.VERSION
  • Gaming SDK: getSdkVersion

Agora’s Authentication Mechanisms

The joinChannel method requires a security key as an essential parameter. The Agora SDK provides two different security key mechanisms based on your security requirements:

  1. For low-security requirements, such as for testing: App ID.
  2. For high-security requirements, such as for production: App ID + App Certificate + Token. Note that an App Certificate is enabled solely for the purposes of generating a Channel Key and cannot be used alone.
../_images/key_relation_web.jpg

App ID

After signing up at Dashboard, you can create multiple projects and each project will have 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.

Getting an App ID

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

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

    ../_images/appid_1.jpg
  3. Fill in the Project Name and click Submit. You have created your first project at Agora.

  4. Find the App ID under the created project.

    ../_images/appid_2.jpg

Using an App ID

You can access the Agora services with the unique App ID:

  1. Enter the App ID in the start window to enable communications.

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

  3. Set the appId parameter as the App ID when initializing the client.

  4. Set the token parameter as NULL when joining the channel.

Token

The following is the process for generating a token:

  1. Deploy a token generator on your server.

  2. The client sends a request for a token to the server.

  3. The server uses the token generator to create a token and sends the token back to the client.

  4. The client passes in the token when joining a channel.

  5. When the token is about to expire or has expired, repeat Steps 2 to 4.

  6. The application client calls renewToken to use the new token.

Deploying a Token Generator

Before using a token, you need to deploy a token generator on your server to generate a token.

Agora provides the server-side sample code.

You can deploy the corresponding sample code on your server, or write your own code in a different programming language.

If you have implemented Agora’s algorithm in other languages, you can file a pull request at GitHub. Agora will merge any valid implementations and test cases.

Generating a Token

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, see Getting an App ID.
appCertificate The App Certificate of the user’s project in the Agora Dashboard, see Getting an App Certificate.
channelName Name of the channel that the user wants to join
uid ID of the user who wants to join a channel
role

Role of the user who wants to join a channel. Choose one of the following roles:

  • Attendee: User in the communication mode.
  • Publisher: Host in the live-broadcast mode.
  • Subscriber: Audience in the live-broadcast mode.
privilege Privileges to services corresponding to the specified roles. See Role-privilege Model.
expireTimestamp [1] The token expiration time. The default value is 0 where 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 valid time for each token is independent, and you can set it through the setPrivilege method.

Getting an App Certificate

Each Agora account can create multiple projects, and each project has a unique App ID and App Certificate.

To get an App Certificate:

  1. Login 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 created project.

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

      ../_images/enable_app_cert.png
    • 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
  • Contact support@agora.io to renew an App Certificate.

  • Keep the App Certificate on the server, never on any client machine.

  • The App Certificate takes about an hour to take effect after it is enabled.

  • Once the App Certificate is enabled for a project, a Token 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 Token or a Channel Key must be used to join a channel.

Role-privilege Model

The design of a token is based on the authentication of different user roles, each of which is associated with a set of privileges.

  • You must define the user role and expiration time when creating a token.

  • When you join a channel with a token, the SDK sends the token to the Agora servers for authenticating the assigned privileges.

  • During a call or live broadcast, you can update the token for the clients in the channel to modify their privileges.

Role Description Privileges
Attendee Participants in a voice or video call
  • Join a channel.
  • Publish a voice stream.
  • Publish a video stream.
  • Publish a data stream.
Publisher Users (hosts) who publish video or/and voice streams in a live broadcast.
  • Join a channel.
  • Publish a voice stream.
  • Publish a video stream.
  • Publish a data stream.
  • Publish a voice stream on the CDN.
  • Publish a video stream on the CDN.
Subscriber Users (audience) who need to subscribe to the voice and video streams in a live broadcast.
  • Join a channel.

Using a Token

Before a user joins a channel from the client:

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

  2. The server, upon receiving the request, generates a token using the token generator and sends the token back to the client.

  3. To join a channel, the client calls the join method, which requires the token as the first parameter.

  4. The Agora server receives the token 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 token, the token replaces the original App ID when a user joins a channel.

  • The token expires after a certain period of time. The application must call renewToken when notified by the onTokenPrivilegeWillExpire callback that the token is about to expire or has expired.

  • The token encoding uses the industry-standard HMAC/SHA1 approach and the libraries are available on most server-side development platforms, such as Node.js, Java, PHP, Python, and C++. For more information, see http://en.wikipedia.org/wiki/Hash-based_message_authentication_code.

References

If your SDK version is earlier than v2.1.0 and you wish to migrate to the latest version, see Token Migration Guide.

Learn how to generate a token on the server on the Generating a Token page.

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)