Article

Easy Obtaining Token from RDP Gateway in Java

July 09,2019

Pimchaya Wongrukun

Background

Update: March 2021

Before you can retrieve data from Refinitiv Data Platform (RDP; Previous name is EDP) is e.g. Historical Pricing, News, and ESG, Environmental, Social and Governance or consume real-time streaming data from Refinitiv Real-Time - Optimized (formerly known as ERT in Cloud). The first step is to obtain an access token. The access token is required for RDP requests and login process in Real-Time - Optimized as shown in the figure below:

Apart from an access token in the token response, there are other fields i.e. refresh_token, expires_in, scope and token_type. For more details of token response, please refer to Authorization - All about tokens tutorial.

To facilitate the process obtaining an access token easily (step 1 and 2). I have created RDPToken class with a simple getToken() method to simply handle this step as shown below:

    	
            HttpGet httpreq = new HttpGet(url);
httpreq.addHeader("Authorization","Bearer "+  RDPToken.getToken(userName,clientId,false));
HttpResponse response = httpClient.execute(httpreq);

The source code is to create and send a data request to RDP. RDPToken.getToken() method is used to get and manage an access token which is required in Authorization header in the data request.

For more details of requesting data from RDP, please refer to Refinitiv Data Platform APIs Tutorials. You can refer to Refinitiv Real-Time - Optimized: Installation and Configuration Guide for the workflow to consume real-time data from the Cloud platform.

Required Info to Request Access Token

To request an access token, you need to have the following info which can be obtained from Request details of Refinitiv Data Platform.

Info	Definition
USERNAME	The resource owner username. RDP username is typically email. Real-Time - Optimized username is machine ID. The ID consists of capital alphabets, hyphens and numbers e.g. GE-A-01103867-5-XXXX
PASSWORD	The resource owner password.
CLIENT_ID	A unique ID defined for an application making the request. Users can generate/manage their application ID's from App key Generator (you need an RDP or Eikon login to access this page).

How it works

RDPToken is designed to easy getting the access token by just calling getToken() method. It is also designed to assist the application by returning the usable access token. If the access token is unusable e.g. it has been expired, the method will request a new access token. You can download RDPToken from Article.RDP.Java.RDPToken project on Github.

RDPToken class requires following libraries which you need to download:

Apache Http Components. It implements the client side of the most recent HTTP standards and recommendations for accessing resources via HTTP or HTTPS. The library is used to request the access token from the Token Service (RDP Gateway).
JSON in java. It implements JSON encoders/decoders in Java. It also includes the capability to convert between JSON and XML, HTTP headers, Cookies. The library is used to get the access token in the JSON response and convert the JSON to String.

Include the required libraries into the CLASSPATH. The example setting the CLASSPATH on Windows machine:

    	
            set CLASSPATH=C:\thirdPartyJars\httpcomponents-client-4.5.9\lib\commons-codec-1.11.jar;C:\thirdPartyJars\httpcomponents-client-4.5.9\lib\commons-logging-1.2.jar;C:\thirdPartyJars\httpcomponents-client-4.5.9\lib\httpclient-4.5.9.jar;C:\thirdPartyJars\httpcomponents-client-4.5.9\lib\httpcore-4.4.11.jar;C:\thirdPartyJars\JsonInJava\json-20180813.jar

Then, you can use getToken() method to get an access token. The method declaration is shown below:

    	
            public static String getToken(String userName, String clientId, boolean alwaysRequest)

The method has 3 parameters:

userName: The username set in the HTTP request.
clientId: A unique ID defined for an application set in the HTTP request.
alwaysRequest: Specify if the method will always request a new access token or not.
- If it is true, a new access token is always requested from the token service. This is used for Refinitiv Real-Time - Optimized which requires a new access token as a part of login process authentication.
- If it is false, the method will return usable access token. If the access token is not usable (it has been expired), the method will request a new access token from the token service. This is used for RDP which can request data with usable access token.

To obtain userName and clientId, please contact your Refinitiv representative.

The example source code to get an access token using getToken() method:

    	
            String accessToken =  RDPToken.getToken(userName,clientId,true);

The getToken() method performs following the workflow below:

The method gets the userName, clientId and alwaysRequest parameter.
The method checks if the token file (token.txt) is in the application run directory or not.
If the token file does not exist e.g. the first time the application calls the method or the file is deleted, the method will ask the client to enter the password. The password is read from the console with echoing disabled. Then, the method sets the parameters which includes username, password and clientId to request an access token. This type of request is called Password Grant. Please contact your Refinitiv representative to obtain username, password and clientId.
Next, requestToken() method is called, the method sends a request with the input parameters to request an access token. Then, the method will receive a JSON response. The response consists of an access token, a refresh token and other information e.g. expires_in, scope. The method writes the whole JSON response into the token file. This is to keep:

The access token for re-use if it has not been expired.
The refresh token which can be used to request a new access and a refresh token.
The expires_in (access token validity time in seconds) used to check if the access token has been expired or not.

5. The getToken() method returns the access token received from requestToken() method to the application.

6. If the token file exists, readTokenFile() method will get refresh token from the token file.

If alwaysRequest is true, the method will perform Requesting new access token with refresh token.
If alwaysRequest is false, the method will check if the access token in the file has been expired or not according to expires_in in the token file. If no, the method will return the access token. If yes, the method will perform Requesting new access token with refresh token.

Requesting new access token with refresh token

The method requests a new access token with the refresh token, username and clientId. This type of request is called Refresh Token grant. This avoids having to send password across the network repeatedly. If the method fails to get a new access token e.g. the refresh token has been expired, it will request a new access token with the password, username and clientId. Then, it will receive a JSON response containing a new access and a refresh token. Next, it updates the token file with the whole JSON response and returns the access token to the getToken() method. The getToken() method returns the access token to the application.

An example output when an application calls the getToken() method:

After you get the access token, you can start sending a data request with the access token to RDP or logging in with the access token to Refinitiv Real-Time - Optimized.

RDPToken class is open source available on Article.RDP.Java.RDPToken project. Therefore, you can modify the class to serve your requirements.

For more details of token requests and responses, you can refer to Authorization - All about tokens tutorial.

Troubleshooting

The application shows "Invalid username or password." with error code 400

    	
            The error code is 400
{
    "error_description": "Invalid username or password.",
    "error": "access_denied"
}

Resolution: Make sure that you use the correct username and password. You may contact Refinitiv Account team to confirm the correct username or reset password.

The application shows "clientId field is invalid." with error code 401

    	
            The error code is 401
{
    "error_description": "clientId field is invalid.",
    "error": "invalid_client"
}

Resolution: Make sure that you run the application with the correct clientId. You can check it from App key Generator

The application shows " java.net.UnknownHostException: api.refinitiv.com"

    	
            java.net.UnknownHostException: api.refinitiv.com
        at java.net.Inet6AddressImpl.lookupAllHostAddr(Native Method)
        at java.net.InetAddress$2.lookupAllHostAddr(Unknown Source)
        …

Resolution: The application cannot send an access token request to the server, api.refinitiv.com, because the server cannot be determined. This can be the network problem. Please contact the network team who can solve the problem.

Apart from the errors above, there are other errors which you can find them on Token Swagger on Refinitiv Data Platfrom API Playground.

Summary

RDPToken can be used to get an access token easily by calling getToken() method. Then, you can request any data with the access token from RDP or log in with the access token to Refinitiv Real-Time - Optimized before consuming real-time data. Moreover, the method to assure that you have access token to request. RDPToken is open source so you can modify it to serve your requirements as well.