> 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/client-api/authorization-process.md).

# Authorization process

TraderEvolution uses the Authorization code flow of OAuth 2.0. It is implemented following [RFC 6749#section-4.1.](https://datatracker.ietf.org/doc/html/rfc6749.html#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: 

<mark style="color:green;">`POST`</mark>` ``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.&#x20;
* `OAuth 2.0` - the most commonly used authorization type, it will be described below in more details.&#x20;

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

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

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

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FS9v5przyJgGDHeikF6gA%2Fimage.png?alt=media&amp;token=67127dc2-324f-4aaf-a2e3-66b584da1b82" alt=""><figcaption></figcaption></figure>

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

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

The access token must be passed in the *Authorization* header.

If authentication is successful, the response will contain:

```json
{
  "s": "ok"
}
```

If authentication fails, the response will contain:

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

### External authentication (3rd party)

The <mark style="color:blue;">`GET /users/me`</mark> 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.

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FDxxDL9QTy5QInHl0LLFv%2Fimage.png?alt=media&amp;token=0c08858a-5bb7-4a9d-8e37-dfd720d45435" alt=""><figcaption></figcaption></figure>

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

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:

```json
{
 "s": "ok",
 "d": {
 "firstName": "Max",
 "lastName": "Dixon",
 "email": "m.dixon@gmail.com",
 "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:

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

### Check whether the user is still logged in

The <mark style="color:blue;">`GET /login/info`</mark> call must be added on the broker's side. It will be used to check whether the user is still logged
&#x20;in the Broker’s system. The access token must be sent in the Authorization header using the
&#x20;*bearer* scheme.

The request must be sent after establishing the connection with the periodicity that is specified
&#x20;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**.

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FECpgqrwGKbbprtQSKWnn%2Fimage.png?alt=media&amp;token=c067fd76-8025-49a3-b12f-a5c514113771" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2F9O3aV1cjaUdHyByNqgBW%2Fimage.png?alt=media&amp;token=d81b0360-44ea-4844-9540-b293e3986e05" alt=""><figcaption></figcaption></figure>

2. 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:

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FSNpc85ejOw20tmOK8lmF%2Fimage.png?alt=media&amp;token=050e2a29-4167-4918-8c7a-9ca1ccedbcbe" alt="" width="375"><figcaption></figcaption></figure>

* 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.

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FZ4BO30uR7CQbzBLckJY0%2Fimage.png?alt=media&amp;token=c9522074-168c-4630-8475-a272707c3a1e" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FODTk0L2ms4fRmsa7odMq%2Fimage.png?alt=media&amp;token=04d1d9f1-9201-4e5a-877f-bb798495da52" alt="" width="375"><figcaption></figcaption></figure>

4. 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.

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2Fhu7VlKuxj3G9soFDJzhR%2Fimage.png?alt=media&amp;token=89bc60ca-deb8-4145-acfa-b90c59869704" alt="" width="349"><figcaption></figcaption></figure>

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

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FWhgTge34YhdmG93emI43%2Fimage.png?alt=media&amp;token=48d72ff7-6a4d-40f9-a27d-4d45d591b853" alt="" width="563"><figcaption></figcaption></figure>

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

6. 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.

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FaVCoCHuKmROTJhtJMHBM%2Fimage.png?alt=media&amp;token=0c3cc9f1-f1e5-44f5-93da-1ac8c419aee3" alt=""><figcaption></figcaption></figure>

7. Enter the request URL and perform the request by clicking the *Send* button.

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FuZ06pgvDoV7iLOcMpNwE%2Fimage.png?alt=media&amp;token=7f317a7d-151e-4c5a-b9ed-b292b4d86cc4" alt=""><figcaption></figcaption></figure>

8. You can monitor all sent requests in the *Console* tab.

<figure><img src="https://1955310097-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F81MNSudMQ3iPZNkGlNpl%2Fuploads%2FTW8VRaNDlUBXdLuWzRN6%2Fimage.png?alt=media&amp;token=70fca56e-12b1-419f-adcd-07c42a27bb99" alt=""><figcaption></figcaption></figure>