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

Use an App ID only for authentication

Each project you create in Agora Console has a unique App ID.

Get an App ID

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

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

  3. Click Create.

  1. Enter your project name and select your authentication mechanism ("App ID") in the dialog box.

  1. Click Submit and you can find the App ID of your newly created project.

Apply your App ID

When initializing the client, set the appId parameter as the App ID that 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 more secure and 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

If you choose APP ID + APP certificate + Token (recommended) when you create a project in the Console, the App Certificate is enabled by default.

If you chooes App ID for authentication when creating the project and want to switch to the "App ID + App Certificate + Token" mechanism, you need to enable the App Certificate first.

Follow these steps to enable the App Certificate:

  1. Click the edit button of the targeted project.

  1. Click Enable in the "Basic Info" page.

  1. Read About App Certificate.

  1. We will send you an email. Follow the steps in the email to confirm about enabling the App Certificate.

  2. Go back to the Edit project page to check the enabled App Certificate.

Note: If you do not find the confirmation email in your inbox, check your spam or junk email folder.

Get a temporary token

When working on a test version of your application, you can generate a temporary token at the Agora Console to join a channel.

  1. On the Project Management page, click .

  1. On the Token page, enter the name of the channel that you want to join. You will get a temporary token.

Note:
  • Ensure that you have enabled the App Certificate of the project before generating a Temp Token. See Enable the App Certificate.
  • A temp token applies to scenarios with low security requirements. For the production environment, we recommend using a token generated at your server.
  • A temp token does not apply to the Agora RTM SDK.
  • Get a token

    When building the final production version of your application, you should generate a token on your server. See Generate a Token on Your Server.

    Apply your token or temporary token

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

    • Ensure that the channel ID and user name that you use to join a channel are the same as the channel ID and user name that 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)