To ensure communication security, when users log in to the RTM system, Agora needs to check their authentication information. Agora provides three authentication mechanisms. According to your scenarios, you can choose one of the following mechanisms:

Authentication mechanisms Scenarios
Use an App ID for authentication Scenarios with low security requirements
Use an RTM token for authentication Scenarios with high security requirements
Use either an App ID or an RTM token for authentication Scenarios in which you need to upgrade your projects to use token authentication
To raise the security level, Agora is phasing out the support for the App ID authentication mechanism. Agora recommends upgrading all your projects to use RTM tokens for authentication.

Use an App ID for authentication

After signing up for a developer account in Agora Console, you can create multiple projects. Each project has an App ID, which is the unique identity 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 raise the security level, Agora is phasing out the support for the App ID authentication mechanism. Agora recommends upgrading all your projects to use RTM tokens for authentication. To avoid the impact on your projects, you can upgrade your project to use either an App ID or an RTM token for authentication.

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.

  6. You need to enter the App ID when initializing the client.

  7. If you need to use an RTM token for authentication, click Edit and enter the Edit Project page to enable an app certificate.

    No certificate means that your project uses only the App ID for authentication. No certificate appears only if you choose the APP ID authentication mechanism when creating a project.

Use an RTM token for authentication

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

Generate an RTM token

You need to generate an RTM token on your server. Follow the steps below to get the App ID, enable App Certificate, and call an API to generate an RTM token.

1. Get an App ID

See Get an App ID.

2. Enable an App Certificate

An App Certificate is a string generated from Agora Console, and it enables token authentication. For different security requirements, Agora provides two types of app certificates. The differences are as follows:

  • Primary certificate: You can use a primary certificate to generate RTM tokens. You cannot delete a primary certificate.
  • Secondary certificate: You can use a secondary certificate to generate RTM tokens. After enabling a secondary certificate, you can swap it for a primary certificate, or delete it.
  • The App Certificate takes about an hour to take effect after it is enabled.
  • You need to store the App Certificate on your server, do not store in any client.
  • You do not have to set Signaling token debugging switch because it does not affect RTM projects.
  • 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, and use either an App ID or the token generated by the primary certificate for authentication.

    3. Generate an RTM token

    Agora provides an open source Agora Dynamic Key repository on GitHub. The ./<language>/src folder of each language holds source codes for generating different types of dynamic keys and tokens. You can use RtmTokenBuilder to generate an RTM Token. The ./<language>/sample folder of each language holds token generator examples that Agora creates for demonstration purposes. RtmTokenBuilderSample is a demo for generating an RTM token.

    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.

    RtmTokenBuilder parameter description (C++)

    static std::string buildToken(const std::string& appId,
                                    const std::string& appCertificate,
                                    const std::string& userAccount,
                                    RtmUserRole userRole,
                                    uint32_t privilegeExpiredTs = 0);
    Parameter Description
    appId The App ID of your project.
    appCertificate The App Certificate of your project.
    userAccount The user ID of the RTM system.
    userRole The user role. Agora supports only one user role. Set the value as the default value Rtm_User.
    privilegeExpiredTs This parameter is currently invalid. You can ignore this parameter.
    An RTM token is valid for 24 hours.

    4. Switch and delete the primary certificate

    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.

    To switch and delete the primary app certificate, do the following:

    1. On the Edit Project page, find Secondary certificate, and click Enable. After successfully enabling a secondary certificate, users can use either the primary certificate or the secondary certificate to generate RTM tokens for authentication.
    2. Click Set as primary to switch the secondary certificate and the primary certificate.
    3. Click Delete to delete the original primary certificate. You cannot restore the deleted certificate, and all RTM tokens generated by the original primary certificate become invalid. You need to use the new primary certificate to generate RTM tokens for authentication.
    4. After deletion, the status of the secondary certificate becomes Disabled. A new secondary certificate is generated when you click Enable next time.

    Use the RTM token

    After generating an RTM token, see the following steps to use the RTM token:

    1. The client sends a request to get an RTM token from the server whenever a token is required.
    2. The server receives the request, generates an RTM token, and sends the token to the client.
    3. RTM tokens have expiration time. Once the token expires, it becomes invalid, and you need to call renewToken to update the RTM token and use the new token to log in to the RTM system.

    Use either an App ID or an RTM token for authentication

    To raise the security level, Agora is phasing out the support for the App ID authentication mechanism. Agora recommends upgrading all your projects to use RTM tokens for authentication.

    If you only use the App ID for authentication, you can follow the steps below for upgrading your project to use either an App ID or a token for authentication:

    1. Enable a primary app certificate.

    2. After successfully enabling a primary app certificate, use the primary app certificate to generate an RTM token.

    3. Use either an App ID or an RTM token for authentication. For example, when existing users are using App ID for authentication, new users can use an RTM token for authentication, and thus both new and old users can log in to the RTM system. You can gradually phase out the use of App ID for authentication.

    4. After all users switch to using an RTM token for authentication, Agora recommends deleting No certificate.

      Once you delete No certificate, you can no longer use the App ID for authentication, and the project cannot enable No certificate again.