The RTM Token is used for authenticating app users when a user logs in to the RTM system.

RTM Tokens are generated on your server. When an app user joins a channel or logs in to the RTM system, the app client interacts with the app server in the following way:

  1. The app client sends a request for RTM token to the app server.
  2. The app server generates an RTM token.
  3. The app server passes the RTM token back to the app client.
  4. The app client then passes the RTM token to the Agora server by calling renewToken provided by the RTM SDK.

This article introduces how to generate an RTM token on your server using the code provided by Agora.

Prerequisites

Before proceeding, ensure that your Agora project has enabled the App Certificate on Console.

Implementation

Agora provides an open-source AgoraDynamicKey repository on GitHub, which enables you to generate RTM tokens on your server with programming languages such as C++, Java, Python, PHP, Ruby, Node.js, and Go. Take C++ as an example, the following picture shows the code structure:

Under the cpp directory:

  • ./sample/RtmTokenBuilderSample.cpp contains the sample code for generating an RTM token.
  • ./src/RtmTokenBuilder.h contains the API used for generating an RTM token.

Generate an RTM token with the sample code

Under the sample directory of each programming language, you can find the sample code for generating an RTM token. Take C++ as an example:

int main(int argc, char const *argv[]) {

  // Fill in your App ID
  std::string appID  = "970CA35de60c44645bbae8a215061b33";
  // Fill in your App Certificate
  std::string appCertificate = "5CFd2fd1755d40ecb72977518be15d3b";
  // Fill in your user ID
  std::string user= "test_user_id";
  // Expiration time of the RTM Token. The parameter is invalid. You do not have to specify this parameter. Each RTM Token is valid for 24 hours.
  uint32_t expirationTimeInSeconds = 3600;
  uint32_t currentTimeStamp = time(NULL);
  uint32_t privilegeExpiredTs = currentTimeStamp + expirationTimeInSeconds;

  std::string result =
    RtmTokenBuilder::buildToken(appID, appCertificate, user,
        RtmUserRole::Rtm_User, privilegeExpiredTs);
  std::cout << "Rtm Token:" << result << std::endl;
  return 0;

Refer to the following steps to generate an RTM token with the sample code above.

Before proceeding, ensure that you have installed openssl.

  1. Download or clone the AgoraDynamicKey repository.

  2. Open the AgoraDynamicKey/cpp/sample/RtmTokenBuilderSample.cpp file, replace the value of appID, appCertificate, and user with your own.

  3. Open your Terminal, navigate to the same directory that holds RtmTokenBuilderSample.cpp, and run the following command. After that, an executable file RtmTokenBuilderSample appears in the folder:

      g++ -std=c++0x -O0 -I../../ -L. RtmTokenBuilderSample.cpp -lz -lcrypto -o RtmTokenBuilderSample
  4. Run the following command. You RTM token is generated and printed in your Terminal window.

      ./RtmTokenBuilderSample

Steps for generating an RTM token with the sample code of different programming languages are as follows:

Java Before proceeding, ensure that you have installed a Java IDE.
  1. Download or clone the AgoraDynamicKey repository.
  2. Open the AgoraDynamicKey/java file in your IDE.
  3. Open AgoraDynamicKey/java/src/io/agora/sample/RtmTokenBuilderSample.java file, replace the value of appID, appCertificate, and uid with your own.
  4. Run the sample project. Your RTM token is generated and printed in your IDE.
Python Before proceeding, ensure that you have Python 2 as the development environment. Use the following command to check your current Python version:
python -V
  1. Download or clone the AgoraDynamicKey repository.
  2. Open the AgoraDynamicKey/python/sample/RtmTokenBuilderSample.py file, replace the value of appID, appCertificate, and uid with your own.
  3. Open Terminal, navigate to the same directory that holds RtmTokenBuilderSample.py, and run the following command. The RTM token is generated and printed in your Terminal window.
    python RtmTokenBuilderSample.py
Python3 Before proceeding, ensure that you have Python 3 as the development environment. Use the following command to check your current Python version:
python -V
  1. Download or clone the AgoraDynamicKey repository.
  2. Open the AgoraDynamicKey/python/sample/RtmTokenBuilderSample.py file, replace the value of appID, appCertificate, and uid with your own.
  3. Open Terminal, navigate to the same directory that holds RtmTokenBuilderSample.py, and run the following command. The RTM token is generated and printed in your Terminal window.
    python RtmTokenBuilderSample.py
PHP Before proceeding, ensure that you have installed the latest version of PHP.
  1. Download or clone the AgoraDynamicKey repository.
  2. Open the AgoraDynamicKey/sample/RtmTokenBuilderSample.php file, replace the value of appID, appCertificate, and uid with your own.
  3. Open Terminal, navigate to the same directory that holds RtmTokenBuilderSample.php, and run the following command. The RTM token is generated and printed in your Terminal window.
    php RtmTokenBuilderSample.php
Node.js Before proceeding, ensure that you have installed the LTS version of Node.js.
  1. Run the following command to install the Node.js dependencies:
    npm install
  2. Download or clone the AgoraDynamicKey repository.
  3. Open the AgoraDynamicKey/nodejs/sample/RtmTokenBuilderSample.js file, replace the value of appID, appCertificate, and uid with your own.
  4. Open Terminal, navigate to the same directory that holds RtmTokenBuilderSample.js, and run the following command. The RTM token is generated and printed in your Terminal window.
    node RtmTokenBuilderSample.js
Go Before proceeding, ensure that you have installed the latest version of Golang.
  1. Download or clone the AgoraDynamicKey repository.
  2. Open the AgoraDynamicKey/go/sample/RtmTokenBuilder/sample.go file, replace the value of appID, appCertificate, and uid with your own.
  3. Open Terminal, navigate to the same directory that holds sample.go, and run the following command. After that, an executable file RtmTokenBuilder appears in the folder
    go build
  4. Run the following command. The RTM token is generated and printed in your Terminal window.
    ./RtmTokenBuilder
Ruby Before proceeding, ensure that you have installed Ruby v1.9 or later. Run the following command to check your current Ruby version:
ruby -version
  1. Download or clone the AgoraDynamicKey repository.
  2. Open the AgoraDynamicKey/ruby/sample/rtm_token_builder_sample.rb file, replace the value of appID, appCertificate, and userAccount with your own.
  3. Open Terminal, navigate to the same directory that holds rtm_token_builder_sample.rb, and run the following command. The RTM token is generated and printed in your Terminal window.
    ruby rtm_token_builder_sample.rb

API reference

This section introduces the method to generate an RTM token. Take C++ as an example:

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 Agora project.
appCertificate The App Certificate of your Agora project.
userAccount The user ID of the RTM system. See the userId parameter of the login method.
role The user role. Agora supports only one user role. Set the value as the default value Rtm_User.
privilegeExpiredTs The Unix timestamp (s) when the token expires, represented by the sum of the current timestamp and the valid time of the token. This parameter is currently invalid. You can ignore this parameter. An RTM token is valid for 24 hours.

Considerations

User ID

The user ID that you use to generate the RTM token must be the same with the one you use to log in to the RTM system.

App Certificate and RTM token

To use the RTM token for authentication, you need to enable the App Certificate for your project on Console. Once a project has enabled the App Certificate, you must use RTM tokens to authenticate its users.

RTM Token expiration

An RTM token is valid for 24 hours.

When the RTM SDK is in the CONNECTION_STATE_CONNECTED state, the user remains online even if the RTM token expires. If a user logs in with an expired RTM token, the RTM SDK returns the LOGIN_ERR_TOKEN_EXPIRED error.

The RTM SDK triggers the onTokenExpired callback (TokenExpired for the Web platform and rtmKitTokenDidExpire for the OC platform) only when an RTM token expires and the RTM SDK is in the CONNECTION_STATE_RECONNECTING state. Upon receiving this callback, you need to generate a new RTM token on your server, and call renewToken to pass the new RTM token to the SDK.