Authentication process

TraderEvolution BO REST API supports the token authentication method. In this framework, the server issues a token to the client upon receiving credentials from the client. Subsequently, the client utilizes this token for all his requests.

The general workflow is as follows:

1. The client obtains a session token by sending a POST request to the /auth/token endpoint. Fill in the request with authorization data.

2. If the credentials are valid, an access token is issued and returned in the response. A refresh token is returned together with an access token. Keep it secure. It will help to renew the access after the token expiration without re-entering the login/password in the plain text.

3. Copy the Access token and authorize using it, please note that you should add "Bearer" to the beginning when inserting your token. Example:

The client uses the token in all subsequent requests by including it in the Authorization header as Authorization: Bearer <access_token>.

(Optional) You can use a refresh token to prevent an access token expiration. The client should send a GET request to the /auth/token/refresh , that contains a refresh token in its body. The refresh rate of an access token depends on its lifetime, which can be set in the settings.

Access token

POST /auth/token

A token is required to perform API calls. The request body includes authorization data, based on which an access token will be issued.

Body

Name	Type	Description
login	string	Login of the user
password	string	Password of the user

Request example

{
  "login": "your login",
  "password": "your password"
}

CURL

curl -X POST "https://sandbox.traderevolution.com:8443/proftrading/rest/auth/token" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"login\": \"your login\", \"password\": \"your password\"}"

Response

200 (OK)

{
  "accessToken": "eyItMTMyNTE0MDUxMSI6LTEzMjUxNDA1MTEsIi0xMDY2NTA2MjYiOi0xMDY2NTA2MjYsIjE5ODMyNTM1NzUiOjE….SMfKVL5SILQtCQX3tpPcrU",
  "accessTokenLifeTime": 43200,
  "refreshToken": "eyItMTA1N…A.dNGWp6Fy39msyhM1GtYIVFwmzuyBnSrfIyU5_jSmrVw",
  "refreshTokenLifeTime": 43500
}

An access token could be used to send a request to the server. It has a lifetime and could be expired. After the expiration, you will not be able to use it anymore.

You can test the Access token method of BO REST API here:

https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Authentication/getTokenUsingPOST

A refresh token allows you to prevent the access token's expiration. To refresh the token you need to use the method described below.

Refresh token

GET/auth/token/refresh

This endpoint is used for obtaining a new Refresh&Access token pair. The access token has its lifetime, which is configured in server settings and can be found in response to this request or access token request. If the Access token's lifetime has expired, you will need to generate a new one (using your Refresh token). Access and Refresh token lifetime can be configured in BackOffice-> Configuration->Settings-> Connectors settings or using the PATCH /connectors/settings method.

Please note that a Refresh token is used for updating your Access token, so it should be placed in the request header.

Header

Name	Type	Description
token	string	A refresh token that is used to update your access token

CURL

curl -X GET "https://sandbox.traderevolution.com:8443/proftrading/rest/auth/token/refresh" -H  "accept: application/json" -H  "token: eyItMTE5ND….ZKqxsjaOhk6u2XEL9VdTO6LL-NX7ykscN7VDFHA" -H  "Authorization: Bearer eyItNDUwMzYyODE2IjotNDUwMzYyO…GmruJKoez-fwXGEX59w82uRdsXwEAAA.kTluUzhRXySugFVMIXYwbJu2YjoOuqLaLjOY-20_ddE"

Response

200 (OK)

{
  "accessToken": "eyItMTMyNTE0MDUxMSI6LTEzMjUxNDA1MTEsIi0xMDY2NTA2MjYiOi0xMDY2NTA2MjYsIjE5ODMyNTM1NzUiOjE….SMfKVL5SILQtCQX3tpPcrU",
  "accessTokenLifeTime": 43200,
  "refreshToken": "eyItMTA1N…A.dNGWp6Fy39msyhM1GtYIVFwmzuyBnSrfIyU5_jSmrVw",
  "refreshTokenLifeTime": 43500
}

As a result, a new pair of tokens will be received in the response.

You can test the Refresh token method of BO REST API here:

https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Authentication/refreshTokenUsingGET

OTT verification

POST /external/token/verify

This endpoint is used for verifying a one-time token (OTT) generated by the server for external links authentication. The token has a short lifetime (configured in server settings) and can be used only once.

If the token is valid, the response will contain the user login associated with the token. If the token is invalid (expired or already used), the response will indicate that the token is not valid.

Please note that the token must be passed in the request body.

Body

Name	Type	Description
token	string	Token that must be verified.

Request

{
  "token": "eyJhbGciOiJ...InR5cCI6IkpXVCJ9"
}

CURL

curl -X POST "https://sandbox.traderevolution.com:8443/proftrading/rest/external/token/verify" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"token\":\"eyJhbGciOiJ...InR5cCI6IkpXVCJ9\"}"

Response

Valid token

{
  "isValid": true,
  "login": "[email protected]"
}

Invalid token

As a result, a new pair of tokens will be received in the response.

Note that standard errors are returned if the token is invalid.