Tokens & Authentication

EngageIP 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
Token Request Headers
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 Parameters
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:

The response body will look similar to this:

Token Response Body
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
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 XHR code snippet:

The Response

The Response Body
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
Token Refresh Request Parameters
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