Background

Before you can retrieve data from Elektron Data Platform (EDP) e.g. Historical Pricing, News, and ESG, Environmental, Social and Governance or consume real-time streaming data from Elektron Real-Time in Cloud (ERT in Cloud). The first step is to obtain an access token. The access token is required for EDP requests and login process in ERT in Cloud 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 EDPToken class with a simple getToken() method to simply handle this step as shown below:

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

The source code is to create and send a data request to EDP.  EDPToken.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 EDP, please refer to Elektron Data Platform APIs Tutorials . You can refer to ERT in Cloud - Installation and Configuration Guide for the workflow to consume real-time data from ERT in Cloud.

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 Elektron Data Platform.

Info Definition
USERNAME

The resource owner username.

  • EDP username is typically email.
  • ERT in Cloud username is machine ID. The ID consists of capital alphabets, hyphens and numbers e.g. GE-A-01103867-5-1234
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 EDP or Eikon login to access this page).     

How it works

EDPToken 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 EDPToken from Article.EDP.Java.EDPToken project on Github.

EDPToken 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 (EDP 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:

  1. userName: The username set in the HTTP request.                                                                         
  2. clientId: A unique ID defined for an application set in the HTTP request.
  3. 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 ERT in Cloud 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 EDP which can request data with usable access token.

To obtain userName and clientId, please refer to Required Info to Request Access Token.

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

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

The getToken() method performs following the workflow below:

  1. The method gets the userNameclientId and alwaysRequest parameter. 
  2. The method checks if the token file (token.txt) is in the application run directory or not.
  3. 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 refer to Required Info to Request Access Token to obtain username, password and clientId.
  4. 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.
  1. The getToken() method returns the access token received from requestToken() method to the application.
  2. If the token file exists, readTokenFile() method will get refresh token from the token file.

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 EDP or logging in with the access token to ERT in Cloud.

EDPToken class is open source available on Article.EDP.Java.EDPToken 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 Elektron Data Platfrom API Playground.

    Summary

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

    References