> For the complete documentation index, see [llms.txt](https://guide.traderevolution.com/traderevolution-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.traderevolution.com/traderevolution-api/traderevolution-apis/backoffice-api/authentication-process.md).

# 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 <mark style="color:red;">`/auth/token`</mark> 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:

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FNYE0ALUwbYfkHeoMhYJp%2Fimage.png?alt=media&amp;token=d00fed20-7102-4a25-befc-df154a66ba7d" alt=""><figcaption></figcaption></figure>

The client uses the token in all subsequent requests by including it in the Authorization header as <mark style="color:red;">`Authorization: Bearer <access_token>`</mark>.

(Optional) You can use a refresh token to prevent an access token expiration. The client should send a GET request to the <mark style="color:red;">`/auth/token/refresh`</mark> , 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

<mark style="color:green;">`POST`</mark> `/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**

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

**CURL**

{% code overflow="wrap" %}

```json
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\"}"
```

{% endcode %}

**Response**

{% tabs %}
{% tab title="200 (OK)" %}

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

{% endtab %}
{% endtabs %}

&#x20;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.&#x20;

{% hint style="success" %}
You can test the Access token method of BO REST API here:

<https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Authentication/getTokenUsingPOST>
{% endhint %}

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

## Refresh token

<mark style="color:blue;">`GET`</mark>`/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 <mark style="color:yellow;">`PATCH`</mark> `/connectors/settings` method.&#x20;

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

**Header**

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

**CURL**

{% code overflow="wrap" %}

```json
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"
```

{% endcode %}

**Response**

{% tabs %}
{% tab title="200 (OK)" %}

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

{% endtab %}
{% endtabs %}

As a result, a new pair of tokens will be received in the response.&#x20;

{% hint style="success" %}
You can test the Refresh token method of BO REST API here:

<https://sandbox.traderevolution.com:8443/proftrading/rest/swagger-ui.html#/Authentication/refreshTokenUsingGET>
{% endhint %}

## OTT verification

<mark style="color:green;">`POST`</mark> `/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.

{% hint style="warning" %}
Please note that the token must be passed in the request body.
{% endhint %}

**Body**

| Name    | Type   | Description                  |
| ------- | ------ | ---------------------------- |
| `token` | string | Token that must be verified. |

**Request**

{% code overflow="wrap" %}

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

{% endcode %}

**CURL**

{% code overflow="wrap" %}

```json
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\"}"
```

{% endcode %}

**Response**

{% tabs %}
{% tab title="Valid token" %}

```json
{
  "isValid": true,
  "login": "user@example.com"
}
```

{% endtab %}

{% tab title="Invalid token" %}

```json
{
  "isValid": false
}
```

{% endtab %}
{% endtabs %}

As a result, a new pair of tokens will be received in the response.&#x20;

{% hint style="warning" %}
Note that standard errors are returned if the token is invalid.
{% endhint %}