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

  1. Client requests token from Authorization Server

  2. Client includes token in API requests to Resource Server

Requesting a Token

  • Token requests are made to the 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

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

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

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

The response body will look similar to this:

{ "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTUxMiJ9.eyJvd25lcklkIjoiMSIsImFjdGluZ093bmVySWQiOiIxIiwidXNlcklkIjoiMTUzIiwicm9sZUlkIjoiMTIxIiwiaXNJbnRlcmFjdGl2ZSI6IkZhbHNlIiwidW5pcXVlX25hbWUiOiJhZG1pbiIsInN1YiI6ImFkbWluIiwiaXNzIjoiaHR0cDovL2F1dGhvcml6YXRpb25zZXJ2ZXIubG9naXNlbnNlLmNvbSIsImF1ZCI6IjA0NGI4YWQ2MDA2ODQ1YzI5NDQ2YjJmMThlNWI1OTA5IiwiZXhwIjoxNTMzOTExNjIwLCJuYmYiOjE1MzM4MjUyMjB9.WH2YffewqNq6bAZq9Gshuks4-RE_r85Qg545tvR-wSLqvDt5ftXw1irx-IFryRH1wWpn2KLWNhpXyl6WOsAaVw", "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJyZWZyZXNoVG9rZW5HdWlkIjoiODI3ZjlhNzYyNzgzNDIyOWI2Nzc3OTZhOTZlYTkzMGEiLCJvd25lcklkIjoiMSIsImFjdGluZ093bmVySWQiOiIxIiwidXNlcklkIjoiMTAwMDAwMDAiLCJhdWQiOiIwNDRiOGFkNjAwNjg0NWMyOTQ0NmIyZjE4ZTViNTkwOSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL25hbWUiOiJMb2dpc2Vuc2UgU3VwcG9ydCIsInN1YiI6IkxvZ2lzZW5zZSBTdXBwb3J0IiwianRpIjoiNmYwNzg5NDEtNGExMy00ZDllLWE3MGEtMTg5NWQ4NGM0ZTc3IiwiaWF0IjoxNjY3MzMyMTgxLCJuYmYiOjE2NjczMzIxODAsImV4cCI6MTY2NzMzMzk4MCwiaXNzIjoiaHR0cDovL2F1dGhvcml6YXRpb25zZXJ2ZXIubG9naXN", "token_type": "bearer", "expires_in": 1800, "audience": "044b8ad6006845c29446b2f18e5b5909", ".issued": "2022-11-01T19:49:41Z", ".expires": "2022-11-01T20:19:41Z", "actingOwnerId": 1 }

Token Response Property

Definition

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 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": "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": "2022-11-01T19:49:41Z"
Type: String
Indicates when the token was issued by the Authorization Server. ISO 8601 format.

.expires

".expires": "2022-11-01T20:19:41Z"
Type: String
Indicates when the token 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

API Request Headers

Definition

Accept

"Accept": "application/json"
Type: String
xhr.setRequestHeader('Accept', 'application/json')

Content-Type

"Content-Type": "application/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:

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

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

 

Copyright LogiSense 2020