Skip to main content

JSON Web Token

tip

This authorization method is designed to authorize requests sent directly from the user to the system. To authorize users accessing the system through third-party applications, use OAuth 2.0 protocol.

The JSON Web Token-based (JWT) authorization option uses two interrelated types of tokens:

  • Access token which is a short-term token used primarily for request authorization. The role of this token is to confirm rights to access the system resources the user requests
  • Refresh token which is a long-term token used access token creation. The role of this token is to authenticate a user when creating an access token
caution

Tokens give the same access to the system as the login and password of a trading account. Keep them confidential.

Steps in authorizing requests using this method can be described as follows:

  1. Gaining access to authorization mechanisms: The user registers a developer account on the https://alor.dev portal
  2. Authenticating as a Broker client: On the API Access Tokens page, the user binds his trading account to the created developer account, proving his ownership of this trading account
  3. Requesting Refresh token: The user clicks the `Refresh Token' button on the same page, sending the authorization server a request to create a long-term refresh token
  4. Receiving Refresh token: The authorization server creates a new refresh token upon the user's request, using the data of the bound trading account. The created token returns to the user as a new record on the same page
  5. Requesting Access token: The user submits a request to the authorization server to create a short-term access token by executing a POST /authorize request specifying the refresh token as the value of the token parameter
  6. Receiving Access token: The authorization server creates a short-term access token using the received refresh token and the details of the trading account for which it was issued. The created token returns to the user as the content of a JSON object in response body of the submitted request
  7. Authorization of requests: The user applies the received access token by passing it as the value of the Authorization header field (for HTTP API) or the token parameter in the request body (for WebSocket API) to authorize submitted requests
note

Both types of tokens have a validity limit: for Access token this period equals 30 minutes when for Refresh token it is 1 year.

There are no technical limitations in the trading system on the frequency of token updates or the number of simultaneously active tokens. Still, when planning the procedure of automatic token update, check the fair-use recommendations and exclude any actions that can affect the stability of the system.