Page Comparison

LogiSense APIs use JSON 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

1. Client requests token from Authentication Server

2. 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

The resulting XHR code snippetsnippet (Note: use the proper version v6, v7 etc in your request path for the version of the API being used):

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);

...

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

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

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 " + yourBase64tokenv6/Account", true);
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

...

setRequestHeader("Accept", "application/json")
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer " + yourBase64token);
xhr.send();

The Response

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