Using all of API methods requires authentication. It is necessary to have a valid customer account on the Trans.eu Platform. The login and password will be used to obtain the token, which is mandatory to use the API methods.

Initial requirements

Authorization using JWT is possible only for requests sent using whitelisted URL. If no application URL was added to the whitelist please contact api@trans.eu.

Query parameters

  • Method: GET
  • Host: https://auth.platform.trans.eu
  • URL: /oauth2/auth?
  • Parameters: client_id=example_app_client_id
    • response_type=code
    • state=random_number
    • redirect_uri=https://example.com/applicationendpoint
  • HTTP/1.1

Important

Redirect uri :

  • must be exactly as whitelisted
  • https only

Request parameters (in query string)

Name Required Type Description
response_type yes string Must be set to code.
client_id yes string Client ID obtained during application registration.
redirect_uri yes string One of previously specified application redirect endpoints. Each URI must be previously added to white list.

The Trans Authorization Server will display page with details of requested scopes. User has to sign in using Tran.eu credentials.


Authorization response

When user grants application access to requested scopes, Trans Authorization Server will redirect user back to URI specified in redirect_uri parameter along with generated code. Example

  • HTTP/1.1 302 Found
  • Location: https://example.com/applicationpoint?code=SDF41D54F54D45DF4

Response parameters

Name Type Description
code string Authorization code generated by the Trans Authorization Server.
state string Value of the state parameter provided in authorization request.

Warning: For security reasons code lifetime is limited to 1 minute, after that period it becomes invalid. Also please note that not every error will cause a redirect. If the request fails due to a missing, invalid, or mismatching redirect URI or client id, the Trans Authorization Server inform user about this on its own page.


Access token request

After receiving valid code from the Trans Authorization Server, application can make request to the token endpoint and exchange code for access token. Example

  • Method: POST
  • Host: https://auth.system.trans.eu
  • URL: /oauth2/token
  • Parameters:
    • grant_type=authorization_code
    • code=a1c94032558c6d0ba98b998299a63135bce063b1
    • redirect_uri=https://example.com/applicationendpoint
    • client_id=example_app_client_id
    • client_secret=example_app_secret
  • Headers:
    • Content-Type: application/x-www-form-urlencoded
    • Accept: application/x-www-form-urlencoded

Request parameters

Name Required Type Description
grant_type yes string Must be set to authorization_code.
code yes string Valid authorization code received from the Trans Authorization Server.
redirect_uri yes string The same redirect_uri as provided when retrieving code.
client_id no string Application client_id obtained during registration. Only required when Authorization header is not sent.
client_secret no string Application client_secret obtained during registration. Only required when Authorization header is not sent.

Header parameters

Name Required Value
Authorization yes Base 64 encoded string that contains the client_id and client_secret keys. The field must have the format: Authorization: Basic .
Content-Type yes application/x-www-form-urlencoded

Response example

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

Response parameters

Name Type Description
code string Authorization code generated by the Trans Authorization Server.
state string Value of the state parameter provided in authorization request.

Warning: For security reasons code lifetime is limited to 1 minute, after that period it becomes invalid. Also please note that not every error will cause a redirect. If the request fails due to a missing, invalid, or mismatching redirect URI or client id, the Trans Authorization Server inform user about this on its own page. Access token request After receiving valid code from the Trans Authorization Server, application can make request to the token endpoint and exchange code for access token.

Response parameters

Name Description
access_token Access token to use by application for authorization.
expires_in Time in seconds until token expires.
token_type Type Bearer is returned as defined in rfc6749.
scope Space separated list of scopes that access token has access to.
refresh_token Single serving token that can be used to extend lifetime of access token.