Authorization process

TraderEvolution uses the Authorization code flow of OAuth 2.0. It is implemented following RFC 6749#section-4.1. After performing the authorization, an access token must be sent with each request in the Authorization header.

Three authorization types are available:

• password - authorization by login and password. The token can be received by the following request in this case:

POST https:/sandbox-api.traderevolution.com/traderevolution/v1/authorize?login=demo&password=demo#&2faCode=false

• token - external authorization. The flow where a user is not required to enter his TE credentials but the TE server checks the token with 3rd party service. This works as follows, the user enters login/password for authorization in the Broker’s system, which issues an access token to him. When he tries to connect to the TE system, it will validate the token in order for a successful connection to be established.

• OAuth 2.0 - the most commonly used authorization type, it will be described below in more details.

The exact way how the authorization will work (type) is configured in Zookeeper, all three available values are listed above:

/configuration/tradeservice/security/auth/type

The following application parameters are provided to the integrable front-end for OAuth 2.0 Authorization code flow:

Application parameter	Description
client id	Unique client identifier issued by TraderEvolution. The publictest will be used for testing purposes.
client secret	Client secret issued by TraderEvolution. Please contact support for this one.
authorization URI	Authorization endpoint URI. The following will be used for testing purposes: https://sandbox-api.traderevolution.com/traderevolution/v1/oauth/authorize
token URI	Token endpoint URI. The following will be used for testing purposes: https://sandbox-api.traderevolution.com/traderevolution/v1/oauth/token

Authorization request

GET/oauth/authorize

The following query parameters must be sent in the request:

OAuth2 parameter	Description
response_type	Response type. Value must be set to code
client_id	Client identifier (string) issued by TraderEvolution. The publictest will be used for testing purposes.
redirect_uri	Redirection Endpoint

TraderEvolution provides the page with an authorization form and prompts the user to enter his credentials.

If all authorization request parameters are valid and access is granted, TraderEvolution issues an authorization code and redirects the request to the specified URI with the following parameters:

OAuth2 parameter	Description
code	Authorization code. It expires shortly after release to prevent the risk of leakage.

Access token request

POST /oauth/token

An external frontend should make an Access Token Request by sending the following parameters using the application/x-www-form-urlencoded format to the TraderEvolution server's token endpoint to exchange the code for an access token:

OAuth2 parameter	Description
grant_type	Grant type. The value must be set to authorization_code
client_id	Client identifier string
client_secret	Client secret string
code	Received authorization code
redirect_uri	Redirection endpoint

The authorization header should be in the following format: Authorization: Basic encodedString, where the encodedString is a result of Base64 encoding of the client’s clientID:clientSecret.

Upon successful validation of the authorization code, an access token and a refresh token are issued. The response contains the following parameters:

OAuth2 parameter	Description
access_token	Access token that must be used in every request to the API
refresh_token	Token used to obtain new access tokens
token_type	Token type. Will be set to Bearer
expires_in	Lifetime of the access token in seconds

To refresh an access token, the external frontend should make a Refresh Request to the token endpoint using the application/x-www-form-urlencoded format with the following parameters:

OAuth2 parameter	Description
grant_type	Grant type. This value must be set to refresh_token
refresh_token	Refresh token issued by TraderEvolution
client_secret	Client secret value

If all parameters are valid, the TraderEvolution server issues a new access token and a new refresh token and responds to the request as described above.

Termination of the connection

An external front-end should make the POST/logout request to terminate the connection.

Token-based authentication (POST /auth)

When the token authorization type is configured, the Broker’s system must authenticate the user in TraderEvolution by sending the previously issued access token.

The request must be sent to POST/auth

The access token must be passed in the Authorization header.

If authentication is successful, the response will contain:

{
  "s": "ok"
}

If authentication fails, the response will contain:

{
  "s": "error",
  "errmsg": "Error description"
}

External authentication (3rd party)

The GET /users/me call must be added on the broker's side in order to have the ability to validate the token with an external system. The Authorization header must be available. It will be used for specifying the access token. The bearer scheme will be used.

This call will execute two goals: validate the token and receive the user details by the specified token. The received user information will be used for the user creation.

Please note that automatic users creation may be disabled on the TE side. This logic is defined by the Create a user if absent flag in the BackOffice:

• If the flag is true, the TE server will create a user with the parameters received in /users/me.

• If the flag is false, the TE server will return an error message, and the user will not be authenticated.

The UserDetailsResponse model is expected in the successful response. The Broker’s system must provide the following information. All fields are required:

• firstName - user’s first name.

• lastName - user’s last name.

• email - user's email address.

• login - user’s login that is used for accessing the Personal area.

Expected success response model example:

{
 "s": "ok",
 "d": {
 "firstName": "Max",
 "lastName": "Dixon",
 "email": "[email protected]",
 "login": "mdixon"
 }
}

• s - ok status for the success response.

• d - base object with the required information.

If the provided access token is not valid, the Broker’s system must respond with the ErrorResponse model. The error reason is expected in the errmsg parameter. Along with that, the “error” must be specified in the s parameter!

Expected ErrorResponse example:

{
 "s": "error",
 "errmsg": "Invalid token"
}

Check whether the user is still logged in

The GET /login/info call must be added on the broker's side. It will be used to check whether the user is still logged in the Broker’s system. The access token must be sent in the Authorization header using the bearer scheme.

The request must be sent after establishing the connection with the periodicity that is specified in the External resources/Custom 3rd party/Check token validity setting.

The Broker’s system must respond with one of two options:

• 204 (No content) - means that the user is still logged in.

• 401 (Unauthorized) - means that the user left the Personal area, and the connection must be terminated on the TE Server side.

Connecting to websocket

During the websocket opening, you must provide an access token sent in the authorization header in the following format: Bearer <access_token>

Please note that the access token can be provided in the request query as well. Format: wss://example.com/socket/path?access_token=$

For example:

wss://sandbox-api.traderevolution.com/traderevolution/v1/stream/quotes?access_token=eyJraWQiOiI3NDhlZjYwZS1mYTNlLTRmYjAt...ANvtqQ92fTM_1EIGdm2fr4

In order to subscribe to some data (receive updates), you should open the appropriate connection. The according connections are listed in each article about subscription to market or trading data. For example, if you want to receive market data, you should open a connection to wss://sandbox-api.traderevolution.com/traderevolution/v1/stream/quotes. Please note that stated URLs are default, but they can be customized according to the customer's requirements.

Authorization via Postman

With a request open in Postman, use the Authorization tab to select an auth type, then complete the relevant details for your chosen type. TraderEvolution uses OAuth 2.0.

With OAuth 2.0, you first retrieve an access token for the API, then use that token to authenticate future requests. To use OAuth 2.0:

1. In the Authorization tab for a request, select OAuth 2.0 from the Type dropdown list. Specify that you want to pass the auth details in the request headers. TraderEvolution uses a Bearer token type, so you need to specify it in the Header Prefix field.

1. To request an access token, fill out the fields in the Configure New Token section, Postman will prompt you to supply specific details depending on the OAuth 2.0 grant type. TraderEvolution uses an Authorization code grant type. The authorization code grant type requires the user to authenticate with the authentication server — an authorization code is then sent back to the client app, extracted, and exchanged with the TraderEvolution server for an access token to authenticate later requests.

Settings of the Configuration Options tab:

• Token Name - the name you want to use for the token.

• Grant Type - select the Authorization code grant type.

• Callback URL - the client application callback URL to redirect to after auth. This must be registered with the TraderEvolution.

• Auth URL - the endpoint for the authorization server, to retrieve the auth code - http://<serverAddress>/traderevolution/v1/oauth/authorize

• Access Token URL - TraderEvolution's authentication server, to exchange an authorization code for an access token - http://<serverAddress>/traderevolution/v1/oauth/token

• Client ID - the ID for your client application registered with TraderEvolution.

• Client Secret - the client secret given to you by TraderEvolution.

• Scope - leave empty.

• State - leave empty.

• Client Authentication - select Send as Basic Auth header.

When your config is complete, select the Get New Access Token option.

1. When clicking Get New Access Token you will be prompted to supply your credentials to retrieve an access token to use in later requests.

1. After clicking the Login button you will be informed about successful authentication. You can wait until the pop-up is closed automatically or click the Proceed button.

1. The Manage Access Tokens pop-up will be opened.

Here you will see all issued tokens and details on each token.

1. To use it, copy the access token or click the Use Token button.

a. In case of copying token you will need to paste it to the Access Token input manually.

b. In case of clicking the Use Token button - it will be pasted automatically.

1. Enter the request URL and perform the request by clicking the Send button.

1. You can monitor all sent requests in the Console tab.