1. Trans.eu Api
  2. General information
  3. Authorization process

Authorization process

Resources exposed by the Trans.eu API are pro­tect­ed, which means that every request must be autho­rized and addi­tion­al­ly there are API rate lim­its to ensure plat­form sta­bil­i­ty.
Autho­riza­tion for the Trans.eu API is imple­ment­ed using the OAuth 2.0 Autho­riza­tion Frame­work (RFC 6749) with the Autho­riza­tion Code grant type and requires:

The autho­riza­tion flow is two-step one-time process and one repeat­able step:

Authorization Diagram

Step 1 — Authentication Request

A. Authentication Request

The Client ini­ti­ates the Autho­riza­tion Code flow by send­ing an authen­ti­ca­tion request to the Trans.eu Autho­riza­tion Serv­er.

Authentication Request
GET /oauth2/auth HTTP/1.1
Host: auth.platform.trans.eu
Request Parameters
Para­me­ter nameManda­to­ryDescrip­tion
client_idrequiredThe Client Iden­ti­fi­er issued dur­ing client appli­ca­tion reg­is­tra­tion.
response_typerequiredMUST be set to code.
staterec­om­mend­edAn opaque val­ue used by the Client to main­tain state between the request and the call­back.
It SHOULD be a cryp­to­graph­i­cal­ly ran­dom string with a min­i­mum length of 8 char­ac­ters.
redirect_urirequiredThe redi­rec­tion end­point to which the Autho­riza­tion Serv­er sends the autho­riza­tion code.
The val­ue MUST exact­ly match one of the redi­rect URIs reg­is­tered for the Client.
Example Request
GET /oauth2/auth?client_id=example_app_client_id&response_type=code&state=random_number&redirect_uri=https://example.com/applicationendpoint HTTP/1.1
Host: auth.platform.trans.eu

B. User login

After send­ing the request the User pro­vides their user­name and pass­word on the Trans.eu Plat­form login page.

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.

C. Authorization Response

If the User suc­cess­ful­ly authen­ti­cates and grants access, the Autho­riza­tion Serv­er redi­rects the user-agent to the Client’s redi­rec­tion end­point with an autho­riza­tion code.

Authorization Successful Response

The Autho­riza­tion Serv­er issues an autho­riza­tion code and returns it to the Client by adding the fol­low­ing para­me­ters to the redi­rec­tion URI.

Response Parameters
Para­me­ter nameManda­to­ryDescrip­tion
coderequiredThe autho­riza­tion code gen­er­at­ed by the Autho­riza­tion Serv­er.
The code is a short-lived, sin­gle-use val­ue that MUST be exchanged for an access token.
For secu­ri­ty rea­sons code life­time is lim­it­ed to 1 minute, after that peri­od it becomes invalid.
staterequired if present in the requestThe exact val­ue received from the Client in the autho­riza­tion request.
The Client SHOULD val­i­date this val­ue to mit­i­gate cross-site request forgery (CSRF) attacks.
Example Successful Response
HTTP/1.1 302 Found
Location: https://example.com/applicationendpoint?code=authorization_code_value&state=random_number

Authorization Error Response

If the autho­riza­tion request is invalid, the User denies access, or an error occurs, the Autho­riza­tion Serv­er redi­rects the user-agent to the Client’s redi­rec­tion end­point with an error response.
Warn­ing: 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.eu Autho­riza­tion Serv­er will noti­fy the user on its web­site.

Error Parameters
Para­me­ter nameManda­to­ryDescrip­tion
errorrequiredA sin­gle ASCII error code as defined in OAuth 2.0 (e.g. access_denied, invalid_request, unauthorized_client).
error_descriptionoption­alHuman-read­able text pro­vid­ing addi­tion­al infor­ma­tion about the error.
staterequired if present in the requestThe exact val­ue received from the autho­riza­tion request.
Example Error Response
HTTP/1.1 302 Found
Location: https://example.com/applicationendpoint?error=access_denied&error_description=The+resource+owner+denied+the+request&state=random_number

Step 2 — Token Request

The Client exchanges the received autho­riza­tion code for an access token by mak­ing a token request using Client Cre­den­tials. Espe­cial­ly Client Secret key MUST be stored secure­ly and MUST NOT be exposed in client-side appli­ca­tions.

The Autho­riza­tion Serv­er responds with an access token, which MUST be includ­ed in any API requests using the Bear­er Token scheme in the Autho­riza­tion HTTP head­er:

Authorization: Bearer <access_token>

Token Request

The Token Request head­er MUST include the API key assigned dur­ing client appli­ca­tion reg­is­tra­tion.

Token Request
POST /ext/auth-api/accounts/token HTTP/1.1
Host: api.platform.trans.eu
Content-Type: application/x-www-form-urlencoded
Api-key: {unique_app_api-key}
Request Header & Parameters
Header/Parameter nameManda­to­ryDescrip­tion
Con­tent-Type (head­er)requiredMUST be set to application/x-www-form-urlencoded.
Api-key (head­er)requiredA unique appli­ca­tion API key assigned dur­ing client appli­ca­tion reg­is­tra­tion.
grant_typerequiredMUST be set to authorization_code.
coderequiredThe autho­riza­tion code received from the Autho­riza­tion Response.
The code is sin­gle-use and short-lived.
redirect_urirequiredThe redi­rect URI used in the autho­riza­tion request.
The val­ue MUST exact­ly match the reg­is­tered redi­rect URI from Step 1.
client_idrequired The Client Iden­ti­fi­er issued dur­ing client appli­ca­tion reg­is­tra­tion.
client_secretrequiredThe Client Secret issued dur­ing client appli­ca­tion reg­is­tra­tion.
Example Request
POST /ext/auth-api/accounts/token HTTP/1.1
Host: api.platform.trans.eu
Content-Type: application/x-www-form-urlencoded
Api-key: {unique_app_api-key}

grant_type=authorization_code&
code=a1c94032558c6d0ba98b998299a63135bce063b1&
redirect_uri=https%3A%2F%2Fexample.com%2Fapplicationendpoint&
client_id=example_app_client_id&
client_secret=example_app_secret

Token Successful Response

If the request is valid, the Autho­riza­tion Serv­er returns an access token and the asso­ci­at­ed refresh token.

Successful Response Parameters
Para­me­ter nameManda­to­ryDescrip­tion
access_tokenrequiredThe access token issued by the Autho­riza­tion Serv­er.
token_typerequiredMUST be set to Bearer.
expires_inrequired The life­time of the access token in sec­onds.
scoperequiredSpace sep­a­rat­ed list of scopes the access token has access to.
refresh_tokenrequired A token used to obtain a new access token when the cur­rent one expires.
Example Successful Response
HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "access_token": "59d9aa9b15cd59a61fc52014792efb6caa82373b", 
  "token_type": "Bearer", 
  "expires_in": 21599, 
  "scope": "offers.loads.manage", 
  "refresh_token": "d52d1d998d6533a3be8e7f26f904be513287938b" 
}

Token Error Response

If the token request is invalid or can­not be ful­filled, the serv­er returns an error response.

Error Parameters
Para­me­ter nameManda­to­ryDescrip­tion
errorrequiredOne of: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type.
error_descriptionoption­al Human-read­able text describ­ing the error.

Repeatable Step — Refresh Token

When the access token expires, the Client obtains a new access token by send­ing a refresh token request to the Token End­point.

The Client SHOULD always store and use the lat­est refresh token returned by the serv­er.

Refresh Token Request

Refresh Token Request
POST /ext/auth-api/accounts/token HTTP/1.1
Host: api.platform.trans.eu
Content-Type: application/x-www-form-urlencoded
Api-key: {unique_app_api-key}
Request Header & Parameters
Header/Parameter nameManda­to­ryDescrip­tion
Con­tent-Type (head­er)requiredMUST be set to application/x-www-form-urlencoded.
Api-key (head­er)requiredA unique appli­ca­tion API key assigned dur­ing client appli­ca­tion reg­is­tra­tion.
grant_typerequiredMUST be set to refresh_token.
refresh_tokenrequiredThe refresh token pre­vi­ous­ly issued to the Client by the Autho­riza­tion Serv­er.
client_idrequired The Client Iden­ti­fi­er issued dur­ing client appli­ca­tion reg­is­tra­tion.
client_secretrequiredThe Client Secret issued dur­ing client appli­ca­tion reg­is­tra­tion.
Example Request
POST /ext/auth-api/accounts/token HTTP/1.1
Host: api.platform.trans.eu
Content-Type: application/x-www-form-urlencoded
Api-key: {unique_app_api-key}

grant_type=refresh_token&
refresh_token=refresh_token_value&
client_id=example_app_client_id&
client_secret=example_app_secret

Refresh Token Successful Response

If the request is valid, the Autho­riza­tion Serv­er returns a new access token and a new refresh token.

Successful Response Parameters
Para­me­ter nameManda­to­ryDescrip­tion
access_tokenrequiredThe access token issued by the Autho­riza­tion Serv­er.
token_typerequiredMUST be set to Bearer.
expires_inrequired The life­time of the access token in sec­onds.
scopeoption­alSpace sep­a­rat­ed list of scopes the access token has access to.  Includ­ed if it dif­fers from the scope pre­vi­ous­ly grant­ed.
refresh_tokenrequired A token used to obtain a new access token when the cur­rent one expires.
Example Successful Response
HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "access_token": "59d9aa9b15cd59a61fc52014792efb6caa82373b", 
  "token_type": "Bearer", 
  "expires_in": 21599, 
  "refresh_token": "d52d1d998d6533a3be8e7f26f904be513287938b" 
}

Refresh Token Error Response

If the refresh token request is invalid or can­not be ful­filled, the serv­er returns an error response.

Error Parameters
Para­me­ter nameManda­to­ryDescrip­tion
errorrequiredOne of: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type.
error_descriptionoption­al Human-read­able text describ­ing the error.
Example Error Response
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "invalid_grant",
  "error_description": "The refresh token is invalid, expired, revoked, or was issued to a different client."
}

API rate limits

To ensure plat­form sta­bil­i­ty and fair usage, API rate lim­its are applied:

- Token end­points: max­i­mum 5 requests per sec­ond (5 RPS)
- All oth­er API end­points: max­i­mum 15 requests per sec­ond (15 RPS)

Requests exceed­ing the rate lim­it may result in an HTTP 429 Too Many Requests response.