Set up Authentication

To enhance communication security, Agora supports two authentication mechanisms to verify users before they access Agora services: by App ID or by token.

Use an App ID for authentication

Before accessing Agora services, you need to initialize the service by providing an App ID.

After signing up for a developer account, you can access Agora Console, where you can create multiple projects. Each project has an App ID, which is the unique identifier of the project. If others steal your App ID, they can use it in their own projects. Therefore, using an App ID for authentication is less secure. Agora recommends using an App ID for authentication only in a test environment or if your project has low security requirements.

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.

5. When the project is created successfully, you can see the newly created project in the project list. Click to view and copy the App ID.

   

Use a token for authentication

Token is a dynamic key generated by App ID, App Certificate, user ID, channel name, token expiration timestamp, and other information. For scenarios requiring high security, such as the production environment, Agora recommends using a token for authentication.

Scope of application

The following table lists Agora products which support token-based authentication:

• If you are using an earlier version of one of these products, you can upgrade your product version or use Channel Keys for authentication.
• If you upgrade your product from a version that supports channel keys to a version that supports tokens, please refer to the Token Migration Guide.

1. Get an App ID

See Get an App ID.

2. Enable the App Certificate

An App Certificate is a string generated from Agora Console that enables token authentication. For different security requirements, Agora provides two types of app certificates:

• 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, but not 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.

  

3. Generate a token

Tokens are generated on your app server. Agora provides an open-source AgoraDynamicKey repository in GitHub, which enables you to generate tokens on your server with programming languages such as C++, Java, Python, PHP, Ruby, Node.js, and Go. For detailed descriptions on the repository and how to generate a token with the sample code, see Generate a Token.

This section takes the C++ API as an example to describe the parameters for generating a token:

static std::string buildTokenWithUid(
    const std::string& appId,
    const std::string& appCertificate,
    const std::string& channelName,
    uint32_t uid,
    UserRole role,
    uint32_t privilegeExpiredTs = 0);

4. Use the token

After generating a token, see the following steps to use the token:

1. When an app client calls an Agora API for certain functions, such as joining a channel, the client needs to apply for a token from the app server.
2. After the app server generates a token, pass the token to the app client.
3. The app client joins a channel with the generated token, channel name and user ID. Note that the channel name and user ID should be the same with those used to generate the token.
4. After the Agora server receives the token and other information, it authenticates the user's identity and decides if the user has permission to join the channel. If the authentication is passed, the user can successfully join the channel and use Agora services.

Upgrade authentication mechanism

To meet the requirements for higher security, Agora is phasing out authenticating with an App ID. For projects that currently use App ID to authenticate users, Agora recommends the following steps to upgrade all your projects to token-based authentication:

1. Enable the App Certificate in Console. Once the App Certificate is enabled, the project supports authenticating users with either an App ID or a token. This enables the app to ungrade to token-based authentication without any impact on current users.

2. Refer to Generate a Token to deploy a token server.

3. Modify the authentication logic of the app client. Ensure that you fill the token parameter in joinChannel or login with the token generated from your server.

4. You app client is now ready for a gray release.

5. When all app clients have upgraded to token-based authentication, delete No Certificate in Agora Console. This prevents users from joining a channel with only an App ID.

   Once No Certificate is deleted, app clients that does not use token-based authentication can no longer join a channel.

Considerations

• Tokens expire. The SDK provides the onTokenPrivilegeWillExpire and onRequestToken callbacks to notify the app when the token will expire or has expired. You need to generate a new token on the server, and then call renewToken to pass the new Token to the SDK or joinChannel to re-join the channel.
• After enabling a primary certificate, you can enable a secondary certificate. If the primary certificate is exposed to security risks, you can swap the secondary certificate for the primary certificate and delete the original primary certificate. For details, see Manage your App Certificates

APIs in different programming languages

The APIs mentioned in this article are in C++. Use this table to look up the API names and their functions in other programming languages: