Authorization flow

Resources avail­able in API are secured, which means that each request must be autho­rized and include access_token in request head­er.

To obtain autho­riza­tion token, end user must grant appli­ca­tion per­mis­sion to use his data.

In order to make this process as easy as pos­si­ble, API sup­ports OAuth 2.0 pro­to­col.

Exist­ing imple­men­ta­tion sup­ports autho­riza­tion code and resource own­er pass­word cre­den­tials grant types. Client cre­den­tials are avail­able only for reg­is­tered appli­ca­tions.

Entry requirements

Each API autho­riza­tion request must con­sists of:

  1. Active user account cre­den­tials (Tran­sId and pass­word)
  2. Valid client cre­den­tials (client_id and client_secret)
  3. Reg­is­tered redirect_uri
  4. Api-key in request head­er

To obtain client cre­den­tials and Api-key, please fill out the appli­ca­tion reg­is­tra­tion form avail­able here.

User account can be cre­at­ed using com­pa­ny reg­is­tra­tion form.

Example of authorization flow

Descrip­tion of a sam­ple autho­riza­tion flow with required and received data:

  1. Redi­rec­tion to autho­riza­tion serv­er for user to post cre­den­tials direct­ly to authen­ti­ca­tion form.
    1. Required para­me­ters: response_type, client_id, redirect_uri
    2. Response: code
  2. Return to the address giv­en as redirect_uri with addi­tion­al code para­me­ter
  3. Code has to be sent back to autho­riza­tion serv­er from the same as redirect_uri loca­tion and using the same client_id
    1. Required para­me­ters: code, client_id, client_secret
    2. Response: access_token, refresh_token
  4. Retriev­ing access_token (valid for 6 hours) and refresh_token
  5. Request head­er con­sists of valid access_token
  6. Before access_token expires, it is pos­si­ble to retrieve new pair of tokens with­out user involve­ment, using refresh_token.
For the autho­riza­tion process it is required for users to pro­vide cre­den­tials by them­selves. It is also very impor­tant to give the pos­si­bil­i­ty to autho­rize each indi­vid­ual user sep­a­rate­ly.