Authorization Code Grant (external users)

Important note: To utilize this authentication flow your application must have authorization_code grant type admitted.

For more general information please refer to authorization overview.

Authorization request

Example

GET /oauth2/authorize?client_id=example_app_client_id
  &response_type=code
  &redirect_uri=https%3a%2f%2fexample.com%2fapplicationendpoint
  &scope=offers.loads.manage HTTP/1.1
Host: auth.system.trans.eu

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.
state	no	string	Random generated string, that will be included in request response to prove response origin. Helps preventing CSRF attacks.
scope	no	string	Space separated list of scopes that application would like to access.
source	no	string	Choose service to verify credentials against. For details please refer to authorization overview.

The Trans Authorization Server will display page with details of requested scopes. If the user is not signed in, he first has to sign in using his Trans or Transplace 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

POST /oauth2/token
Host: auth.system.trans.eu
Content-Type: application/x-www-form-urlencoded

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

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 <base64 encoded client_id:client_secret>.
Content-Type	yes	application/x-www-form-urlencoded

Access token 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	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.