Tokens & Authentication

LogiSense APIs use JSON Web Tokens (JWT) for authentication. This article will explain how to obtain, use, and refresh a JWT. For more information about JWT read this.

Typical Workflow

Client requests token from Authentication Server
Client includes token in API requests to Resource Server

Requesting a Token

Token requests are made to the Authentication Server
Use the POST verb
Include request headers for Accept and Content-Type
Body includes username, password, grant_type, and client_id

Token Request Header	Definition
Accept	"Accept": "application/json" Type: String xhr.setRequestHeader('Accept', 'application/json')
Content-Type	"Content-Type": "application/x-www-form-urlencoded" Type: String xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');

Token Request Parameter	Definition
username	"username": "myUsername" Type: String username= + myUsername + &password= + myPassword + &grant_type=password&client_id= + userClientId
password	"password": "myPassword" Type: String username= + myUsername + &password= + myPassword + &grant_type=password&client_id= + userClientId
grant_type	"grant_type": "password" Type: String username= + myUsername + &password= + myPassword + &grant_type=password&client_id= + userClientId
client_id	"client_id": "userClientId" Type: String username= + myUsername + &password= + myPassword + &grant_type=password&client_id= + userClientId

The resulting XHR code snippet:

xhr.open("POST", "https://35.169.33.81/AuthorizationServer/Access/Login", true);
xhr.setRequestHeader("Accept", "application/json")
xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
xhr.send("username=" + userName + "&password=" + userPassword + "&grant_type=password&client_id=" + userClientId);

The response body will look similar to this:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTUxMiJ9.eyJvd25lcklkIjoiMSIsImFjdGluZ093bmVySWQiOiIxIiwidXNlcklkIjoiMTUzIiwicm9sZUlkIjoiMTIxIiwiaXNJbnRlcmFjdGl2ZSI6IkZhbHNlIiwidW5pcXVlX25hbWUiOiJhZG1pbiIsInN1YiI6ImFkbWluIiwiaXNzIjoiaHR0cDovL2F1dGhvcml6YXRpb25zZXJ2ZXIubG9naXNlbnNlLmNvbSIsImF1ZCI6IjA0NGI4YWQ2MDA2ODQ1YzI5NDQ2YjJmMThlNWI1OTA5IiwiZXhwIjoxNTMzOTExNjIwLCJuYmYiOjE1MzM4MjUyMjB9.WH2YffewqNq6bAZq9Gshuks4-RE_r85Qg545tvR-wSLqvDt5ftXw1irx-IFryRH1wWpn2KLWNhpXyl6WOsAaVw",
    "token_type": "bearer",
    "expires_in": 86399,
    "refresh_token": "587deb8616844c58b9991c61eebb2dfd",
    "audience": "044b8ad6006845c29446b2f18e5b5909",
    ".issued": "Thu, 09 Aug 2018 14:33:40 GMT",
    ".expires": "Fri, 10 Aug 2018 14:33:40 GMT"
}

Token Response Property	Definition
access_token	"access_token": "A 512 character base64 string" Type: String This is the token you will include in your API requests
token_type	"token_type": "bearer" Type: String When making API requests the Authorization header value will include 'Bearer' + the access token
expires_in	"expires_in": "86399" Type: String The time, in seconds, for which the token is valid.
refresh_token	"refresh_token": "587deb8616844c58b9991c61eebb2dfd" Type: String This value will be included when you want to refresh your token
audience	"audience": "044b8ad6006845c29446b2f18e5b5909" Type: String The intended recipient of the token.
.issued	".issued": "Thu, 09 Aug 2018 14:33:40 GMT" Type: String Indicates when the token was issued by the Authorization Server.
.expires	".expires": "Fri, 10 Aug 2018 14:33:40 GMT" Type: String Indicates when the token expires.

Using the Token

Let's use our newly acquired token to get all the accounts. We note the following differences between a token request and an API request:

API requests are made to the API/Resource Server
Use the appropriate verb
We still include request headers for Accept and Content-Type
We need to include the token in the Authorization request header

API Request Headers	Definition
Accept	"Accept": "application/json" Type: String xhr.setRequestHeader('Accept', 'application/json')
Content-Type	"Content-Type": "application/x-www-form-urlencoded" Type: String xhr.setRequestHeader('Content-Type', 'application/json');
Authorization	"Authorization": "Bearer + yourBase64token" Type: String xhr.setRequestHeader('Authorization', 'Bearer ' + yourBase64token);

The resulting JavaScript XHR code snippet:

xhr.open("GET", "https://35.169.33.81/ResourceServer/api/v1/Account", true);
xhr.setRequestHeader("Accept", "application/json")
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer " + yourBase64token);
xhr.send();

The Response

Response Body Property	Definition
trackingId	"trackingId": "06404d2e-5334-4283-9c79-057087f26822" Type: String Audit tracking number for the request
totalCount	"totalCount": 8 Type: Number The number of items returned
items	"items": array Type: Array The resultant list of objects

Token Management

As noted when we received the access token, tokens do expire. Let's compare and contrast requesting and refreshing a token:

Do not send username or password in the refresh request
Include the refresh token received when the original token was issued
Token refresh requests are also made to the Authentication Server
They also use the POST verb
They also include request headers for Accept and Content-Type
The body still includes the client_id
A new value of refresh_token for grant_type
We need to include owner and user

Refresh Request Parameter	Definition
refresh_token	"refresh_token": "7ec8836df8f0422090d74c0c24d7f5cd" Type: String This value was received when requesting the original token.
grant_type	"grant_type": "refresh_token" Type: String Use the value 'refresh_token' for refresh requests
client_id	"client_id": "044b8ad6006845c29446b2f18e5b5909" Type: String This will be the same as the initial token request.
ownerID	"ownerID": 1 Type: Number Refresh token is used to switch tenants (if the user is permissioned for access) so we include the owner ID.
actingOwnerID	"actingOwnerID": 1 Type: Number Some tenants inherit configuration items from an acting owner so we specify that here.
actingUserID	"actingUserID": 153 Type: Number The ID of the user representing the owner's administrator