Page Comparison

LogiSense APIs use JSON Web Tokens (JWT) for authentication. This article will explain how to obtain, 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

...

Authorization Server
Client includes token in API requests to Resource Server

Requesting a Token

Token requests are made to the Authentication Authorization 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 (Note: use the proper version v6, v7 etc in your request path for the version of the API being used):

Code Block

xhr.open("POST", "https://35.169.33.81/AuthorizationServer/api/v6/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);

...

Code Block

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTUxMiJ9.eyJvd25lcklkIjoiMSIsImFjdGluZ093bmVySWQiOiIxIiwidXNlcklkIjoiMTUzIiwicm9sZUlkIjoiMTIxIiwiaXNJbnRlcmFjdGl2ZSI6IkZhbHNlIiwidW5pcXVlX25hbWUiOiJhZG1pbiIsInN1YiI6ImFkbWluIiwiaXNzIjoiaHR0cDovL2F1dGhvcml6YXRpb25zZXJ2ZXIubG9naXNlbnNlLmNvbSIsImF1ZCI6IjA0NGI4YWQ2MDA2ODQ1YzI5NDQ2YjJmMThlNWI1OTA5IiwiZXhwIjoxNTMzOTExNjIwLCJuYmYiOjE1MzM4MjUyMjB9.WH2YffewqNq6bAZq9Gshuks4-RE_r85Qg545tvR-wSLqvDt5ftXw1irx-IFryRH1wWpn2KLWNhpXyl6WOsAaVw",
    "refresh_token_type": "bearereyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJyZWZyZXNoVG9rZW5HdWlkIjoiODI3ZjlhNzYyNzgzNDIyOWI2Nzc3OTZhOTZlYTkzMGEiLCJvd25lcklkIjoiMSIsImFjdGluZ093bmVySWQiOiIxIiwidXNlcklkIjoiMTAwMDAwMDAiLCJhdWQiOiIwNDRiOGFkNjAwNjg0NWMyOTQ0NmIyZjE4ZTViNTkwOSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL25hbWUiOiJMb2dpc2Vuc2UgU3VwcG9ydCIsInN1YiI6IkxvZ2lzZW5zZSBTdXBwb3J0IiwianRpIjoiNmYwNzg5NDEtNGExMy00ZDllLWE3MGEtMTg5NWQ4NGM0ZTc3IiwiaWF0IjoxNjY3MzMyMTgxLCJuYmYiOjE2NjczMzIxODAsImV4cCI6MTY2NzMzMzk4MCwiaXNzIjoiaHR0cDovL2F1dGhvcml6YXRpb25zZXJ2ZXIubG9naXN",
    "expirestoken_intype": 86399"bearer",
    "refreshexpires_tokenin": "587deb8616844c58b9991c61eebb2dfd"1800,
    "audience": "044b8ad6006845c29446b2f18e5b5909",
    ".issued": "Thu, 09 Aug 2018 14:33:40 GMT2022-11-01T19:49:41Z",
    ".expires": "Fri, 10 Aug 2018 14:33:40 GMT": "2022-11-01T20:19:41Z",
    "actingOwnerId": 1
}

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
refresh_token	"refresh_token": "A 512 character base64 string" Type: String This is the token you will include

in your API requests

in a request to refresh your access
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

1800"
Type: String
The time, in seconds, for which the token is valid

.

(maximum value 1800 - 30 minutes)
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

2022-11-01T19:49:41Z" Type: String Indicates when the token was issued by the Authorization Server. ISO 8601 format.
.expires	".expires": "

Fri, 10 Aug 2018 14:33:40 GMT

2022-11-01T20:19:41Z"
Type: String
Indicates when the token

expires

expires. ISO 8601 format.

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

json" 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:

Code Block

xhr.open("GET", "https://35.169.33.81/ResourceServer/api/v1v6/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

": "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": A JWE or JWS in 'Compact Serialization Format' Type: String This value was received when requesting the original token and then subsequent refresh_token requests.
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.

Versions Compared

Old Version 1

New Version Current

Key