Authorize using JWT access token

Using all of API meth­ods requires authen­ti­ca­tion. It is nec­es­sary to have a valid cus­tomer account on the Plat­form. The login and pass­word will be used to obtain the token, which is manda­to­ry to use the API meth­ods.

Initial requirements

Autho­riza­tion using JWT is pos­si­ble only for requests sent using whitelist­ed URL. If no appli­ca­tion URL was added to the whitelist please con­tact

Url parameters and connection settings

  • Method: GET
  • Host:
  • URL: /oauth2/auth
  • Para­me­ters: client_id=example_app_client_id
    • response_type=code
    • state=random_number
    • redirect_uri=
  • HTTP/1.1
Redi­rect uri:
  • must be exact­ly as whitelist­ed
  • https only
  • Diagram

    Request parameters (in query string)

    response_typeyesstringMust be set to code
    client_idyesstringClient ID obtained dur­ing appli­ca­tion reg­is­tra­tion
    stateyesIntRan­dom num­ber (at least 8 char­ac­ters long)
    redirect_uriyesstringOne of pre­vi­ous­ly spec­i­fied appli­ca­tion redi­rect end­points. Each URI must be pre­vi­ous­ly added to white list

    The Trans Autho­riza­tion Serv­er will dis­play page with details of request­ed scopes. User has to sign in using cre­den­tials.

    Authorization response

    When user grants appli­ca­tion access to request­ed scopes, Trans Autho­riza­tion Serv­er will redi­rect user back to URI spec­i­fied in redirect_uri para­me­ter along with gen­er­at­ed code. Exam­ple

    • HTTP/1.1 302 Found
    • Loca­tion:

    Response parameters

    codestringAutho­riza­tion code gen­er­at­ed by the Trans Autho­riza­tion Serv­er.
    statestringVal­ue of the state para­me­ter pro­vid­ed in autho­riza­tion request.

    Warn­ing: For secu­ri­ty rea­sons code life­time is lim­it­ed to 1 minute, after that peri­od it becomes invalid. Also please note that not every error will cause a redi­rect. If the request fails due to a miss­ing, invalid, or mis­match­ing redi­rect URI or client id, the Trans Autho­riza­tion Serv­er inform user about this on its own page.

    Access token request

    After receiv­ing valid code from the Trans Autho­riza­tion Serv­er, appli­ca­tion can make request to the token end­point and exchange code for access token. Exam­ple

    • Method: POST
    • Host:
    • URL: /ex­t/auth-api/ac­counts/­to­ken
    • Para­me­ters:
      • grant_type=authorization_code
      • code=a1c94032558c6d0ba98b998299a63135bce063b1
      • redirect_uri=
      • client_id=example_app_client_id
      • client_secret=example_app_secret
    • Head­ers:
      • Con­tent-Type: appli­ca­tion/x‑www-form-urlen­cod­ed
      • Api-key: {unique_ap­p_api-key}

    Request parameters

    grant_typeyesstringMust be set to authorization_code.
    codeyesstringValid autho­riza­tion code received from the Trans Autho­riza­tion Serv­er.
    redirect_uriyesstringThe same redirect_uri as pro­vid­ed when retriev­ing code.
    client_idyesstringAppli­ca­tion client_id obtained dur­ing reg­is­tra­tion. Only required when Autho­riza­tion head­er is not sent.
    client_secretyesstringAppli­ca­tion client_secret obtained dur­ing reg­is­tra­tion. Only required when Autho­riza­tion head­er is not sent.

    Header parameters

    Api-keyyesApi-key obtained dur­ing reg­is­tra­tion


    HTTP/1.1 200 OK
    Content-Type: application/json
      "access_token": "59d9aa9b15cd59a61fc52014792efb6caa82373b",
      "expires_in": 21599,
      "token_type": "Bearer",
      "scope": "offers.loads.manage",
      "refresh_token": "d52d1d998d6533a3be8e7f26f904be513287938b"

    Response parameters

    access_tokenAccess token to use by appli­ca­tion for autho­riza­tion.
    expires_inTime in sec­onds until token expires.
    token_typeType Bear­er is returned as defined in rfc6749.
    scopeSpace sep­a­rat­ed list of scopes that access token has access to.
    refresh_tokenSin­gle serv­ing token that can be used to extend life­time of access token.