Authentication service

The authentication service contains two methods to support using Bearer authentication to access the web services - login and refresh.

The whoami method can be used to check that you are authenticated with the username you provided. The whoami method can be used when you provide either a Authorization: Basic or Authorization: Bearer header.

Please review API concepts for information about setting up a user.

The following methods are part of this service:

Who Am I

This method is named after the UNIX/LINUX command to tell you who you are! It was created initially for testing purposes when the API was in initial development. Since it proved useful it has been kept.

There is no payload (it is a GET operation) and no query string parameters. You need to provide an authentication header (Basic or Bearer). The return should give a 200 Ok response:

{
  "userName": "AzoteasKennyAzoteas170",
  "emailAddress": "kennyazoteas@themovingportal.dev",
  "organisationType": "Supplier"
}

The emailAddress property will be blank if using the Integration service account.

You can also use the HTTP header X-UserCode to specify the person you want to perform operation as.

Login

This method is used to get tokens for use in the Authorization: Bearer Http header. An example payload is

{
  "username": "xyzsuppliersmarysmith283",
  "password": "uh2P%28KSM@##12",
  "email": ""
}

A call to this method would return a 200 Ok response:

{
  "tokenType": "Bearer",
  "accessToken": "....ACCESSTOKEN.....",
  "expiresIn": 1800,
  "refreshToken": "....REFRESHTOKEN....."
}

The accessToken should then be used in the Http bearer authentication header. This lifetime of this token is specified by the expiresIn property in seconds (i.e. 1800 seconds = 30 minutes).

The refreshToken has a longer lifetime than the access token and will be valid for 14 days. Refresh tokens need to be stored safely like access tokens or application credentials.

Refresh

This method is used to create a new accessToken using a refresh token (rather than a username and password as used by the /auth/login method). An example payload is

{
  "refreshToken": "....REFRESHTOKEN....."
}

A call to this method would return a 200 Ok response with the same response as the /auth/login method.

{
  "tokenType": "Bearer",
  "accessToken": "....ACCESSTOKEN.....",
  "expiresIn": 1800,
  "refreshToken": "....REFRESHTOKEN....."
}

When a refresh token is used the user is revalidated to ensure that they haven't been changed or deactivated.