InEight Integrations
Using Postman with InEight APIM
This document contains confidential and proprietary information of InEight Inc.
Disclosure is prohibited. All rights are reserved. © InEight 2022.
Changelog
This changelog contains only significant or other notable changes to the document revision. Editorial or
minor changes that do not affect the context of the document are not included in the changelog.
Rev
Date
Description
1.0
05-MAR-2019
Initial Release
28-AUG-2019
Moved to new template
2.0
29-JUL-2022
Added NOTE in Create an Environment in Postman when using OAuth 2.0.
Published revision.
InEight Integrations - Using Postman with InEight APIM
iii
Contents
Overview ........................................................................................................................................... 4
Prerequisites .............................................................................................................................................. 4
Environment Variables .............................................................................................................................. 4
Getting Started .................................................................................................................................. 6
About Authentication Methods ................................................................................................................ 6
Create an Environment in Postman .......................................................................................................... 6
Instructions – Using ProjectCodes_Get as Sample ............................................................................... 9
Appendix A: Prerequisite Script ........................................................................................................ 13
Appendix B: Environment Variable Mapping to APIM Headers .......................................................... 14
Overview
4
Overview
This document describes how to use the Postman developer tool to test and create proof-of-concept code for
InEight cloud platform APIs.
Prerequisites
• Postman – Download the applicable version for your development environment from
https://www.getpostman.com/.
• InEight Environment – You will need to have an existing environment for InEight that is suitable for
testing and will not interfere with live production data. Creation of this environment will provide some
of the information used for Environment Variables later in this document.
• APIM Subscription – Refer to the Getting Started with InEight Integrations – Developer Guide for
instructions to create an account in APIM and generate an APIM Subscription Key.
Environment Variables
You can copy the following table and fill in the Value column for later reference.
Variable Name
Value
How to Obtain
Example
TenantId
The Id for your Azure Active
Directory Tenant Subscription that
will authenticate your ClientId
5ag46018-bd64-4747-8a43-
4c0ecZ187b68
SSOClientId
Client Id within customer Azure AD
used to verify identity.
This is in the setting
“In8.Platform.SSOClientId” in the
InEight Tenant Catalog
c5e5eb3-7c68-4505-bca9-7bc46e9440a6
ClientId
Client Id provided for Azure AD when
creating the InEight environment.
This is in the ServiceClientId in the
InEight Tenant Catalog
1
67a8fa13-c7c5-4a7e-8b29-3cef970dae3a
ClientSecret
Client Secret provided for InEight
environment.
This is in the ServiceClientSecret in
the InEight Tenant Catalog.
NOTE: To request information from
the Tenant Catalog, a request must
be made via a ticket in InEight’s
Service Now.
LBYgYv404e8=
InEight Integrations - Using Postman with InEight APIM
5
Variable Name
Value
How to Obtain
Example
TenantPrefix
The URL prefix for the environment
domain For example, if your
environment URL is https://sample-
domain.hds.ineight.com, then the
InEight InEight Tenant Prefix is
“sample-domain”.
This is the “TenantKey” in the InEight
Tenant Catalog
1
sample-domain
SubscriptionKey
This is found in in your APIM Profile.
0bf82de6384043d0b0ebd9b1fb528ffd
Getting Started
6
Getting Started
About Authentication Methods
All API requests into InEight APIM are authenticated in two ways:
• The first layer of authentication for Integration APIs is validation that the caller has a valid Subscription
Key to APIM. This is handled by passing a subscription key as a header in the API request, which is
described in more detail throughout this document.
• The second layer of authentication is that the caller has a valid account, typically an email account in the
InEight application environment.
It is technically possible to use Postman in the InEight application through three general methods of
authentication as mentioned below. However, only options 2 or 3 can currently be used with Postman due to
incompatibility between OAuth2.0 and Postman.
1. Interactive/Manual User Id Entry – InEight uses Azure AD OAuth 2.0 to authenticate manually entered
credentials. Because Postman is not currently aware of the Azure AD specifics for OAuth 2.0 at this time,
this method is not supported.
2. Service Account with Client Id/Client Secret – This document provides examples for testing APIs using
this method. The ClientID and Client-Secret are available through InEight’s professional Services.
3. Registered Application with Client Id/Client Secret – Although supported, this document does not
provide examples.
Create an Environment in Postman
The Environment is used to create variables used to set required values for headers in API Requests. Sample
scripts are provided in the instructions for using the variables to set header values via script.
1. In Postman, click the Settings icon.
2. Change the setting Automatically persist variable values to OFF. Persisting the values will cause them to
be stored on remote servers belonging to Postman. For testing InEight APIs, this means that sensitive
data such as client ids and client secrets could be stored in locations not managed by InEight or a
customer. Close this form after making the change.
InEight Integrations - Using Postman with InEight APIM
7
3. Use the New menu to start a new environment.
4. Name the new environment, and then enter variables in the Manage Environments form. The following
variable names should be entered:
• TenantId
• SSOClientId
• ClientId
• ClientSecret
• TenantPrefix
• SubscriptionKey
• AccessToken
• ExpiresOn
Getting Started
8
5. Enter initial values for the variables. Refer to the Prerequisites table above for values to use. After all the
information is entered, click the Add button.
NOTE:
NOTE:
6. Close the Manage Environments dialog box. This completes the addition of an environment that
contains repeatable variables, which can be used in any new Postman Request.
InEight Integrations - Using Postman with InEight APIM
9
Instructions – Using ProjectCodes_Get as Sample
1. Create a new Request in Postman
2. Fill out all information for the new Request item. Be sure to select the Collection you created when
installing Postman to save the Request to.
3. Verify the correct method is selected for the new request. For our sample, the GET method is used.
Instructions – Using ProjectCodes_Get as Sample
10
4. Copy the URL to use for the request from APIM.
NOTE:
5. Paste the URL to the request in Postman. If any parameter information within square brackets was
pasted, delete it from the URL string before continuing.
Examples:
6. Add required Header Keys and set the values for headers using variables. Each variable name should be
contained within two curly braces, for exapmle, {{variable}}.
• Authorization = Bearer {{AccessToken}}
• X-IN8-TENANT-PREFIX = {{TenantPrefix}}
• Content-Type = application/json – This should be selectable from a list in the Value field. This
Header is not required for Get Requests, so is not shown in the example below.
• Ocp-Apim-Subscription-Key = {{SubscriptionKey}}
7. Select the environment that you want to use. After selected, variables change from red text to orange.
InEight Integrations - Using Postman with InEight APIM
11
8. Select the Pre-req option on the request, and then paste the sample script from Appendix A.
9. Click the Send button to test the API. The desired result is a response with 200 OK, or if using a POST
message and you have not provided JSON content for the body, the message Payload was missing or
invalid and was not parsed indicates initial success.
To see more details about what happened when a request was sent, such as when troubleshooting an error, the
Postman Console tool can provide helpful information. The console is accessed from the View menu at the top
left.
Instructions – Using ProjectCodes_Get as Sample
12
After it opens, send the request again and details will be captured in a separate console window. The image
below shows an example for a permission error caused by the Authorization Header containing a value of Bearer
{{Token}} instead of Bearer {{AccessToken}}.
InEight Integrations - Using Postman with InEight APIM
13
Appendix A: Prerequisite Script
For obtaining Bearer Token using Service Account Client Id/Secret.
The following script determines if the current token has expired, and if it has, it will get another one based on
the variables set in the Postman Environment.
var expiration = new Date(+(pm.environment.get('ExpiresOn')||''));
var now = new Date();
var isExpired = now >= expiration;
if (isExpired)
{
pm.sendRequest({
url:
'https://login.microsoftonline.com/'+pm.environment.get('TenantId')+'/oauth2/token'
,
method: 'POST',
header: 'Content-Type:application/x-www-form-urlencoded',
body: {
mode: 'raw',
raw:
'grant_type=client_credentials&client_id='+pm.environment.get('ClientId')+'&client_
secret='+encodeURIComponent(pm.environment.get('ClientSecret'))+'&resource='+pm.env
ironment.get('SSOClientId')
}
}, function (err, response) {
var result = response.json();
console.log(result);
if (result.expires_on)
{
var expires_on = new Date(+(result.expires_on+'000'));
console.log(expires_on);
pm.environment.set('AccessToken',result.access_token);
pm.environment.set('ExpiresOn',result.expires_on+'000');
}
});
}
Appendix B: Environment Variable Mapping to APIM Headers
14
Appendix B: Environment Variable Mapping to APIM Headers
When creating API requests used with APIM in your own environment, use the following table to understand
how the Environment Variables used in this document map to the required message headers for APIM
messages.
APIM Message Header
Postman Environment Variable
X-IN8-TENANT-PREFIX
TenantPrefix
Ocp-Apim-Subscription-Key
SubscriptionKey
Content-Type
Not set as an Environment Variable.
Always set to “application/json”
Authorization
Not set as an Environment Variable.
Same as {{AccessToken}} created by Postman script provided in this document. This
needs to be obtained based on ClientID, SSOClientId, and ClientSecret for each API
request sent to APIM.