How to call an ION API
Intermediate | 45 Minutes
API Gateway Enterprise Integration
Overview
This tutorial will help you learn how to call an ION API within the OS portal using Authorized API Calls and Postman—a popular tool for testing APIs. It will also offer guidance on integrating this process into your own client application, ensuring a smooth and efficient implementation.
📋 Requirements
|
Tutorial
This tutorial will guide you through calling an ION API within the Infor OS portal using several OAuth scenarios, including Postman, a widely used tool for API testing. We'll also give you some tips on how to implement this from your own client application.
How you call an ION API depends on the type of client application you are using. If an application is already authenticated with Infor OS, you will receive an Infor OS token, which can be used to call an ION API. This is an OAuth2 SAML Bearer Grant, the first scenario in the slide below. To be logged in to the Infor OS portal means you are already authenticated, so the same token that was issued to you via login for single sign-on can be reused if you are making an ION API call from the Infor OS portal itself or within any of the other SSO-authenticated applications.
OAuth2 SAML Bearer Grant
We'll call a simple API that will return the details of the currently logged-in user.
1
Log in to the OS portal and select the API Gateway tab.
2
On the navigation menu in the upper left corner, select Available APIs.
Here, you will see a list of various APIs and associated documentation registered by the API Gateway.
3
Search and select the IFS Service API
4
Click on the Documentation tab
5
Scroll to the IFSUser section, click on the GET /usermgt/v2/users/me API.
6
Currently the details are empty, click the Try it out button.
7
Next step Click the Execute button.
You should see the field replaced by your personal details in the 200 success code.
8
You will also see there is a Bearer Token issued for this request.
This is the OAuth2 SAML Bearer Token type. The client application we used here is the documentation page of the registered API itself.
The next OAuth scenario involves calling from a mobile or web application. In this case, the application is not yet authenticated within the Gateway. The user must authorize the mobile application to call the ION API on their behalf. This type of interaction uses the OAuth2 Authorization Code Grant.
NOTE: To demonstrate, we’ll use the Postman client instead of a mobile API Call from an authorized Mobile or web app application.
OAuth2 Authorization Code Grant
On the navigation menu, select Authorized Apps, then select the + button to create a new authorized app.
In the Name field, enter Postman Web App Demo. For the Type, choose Web Application, and in the Description field, enter Postman Web App. Enter the Postman redirect URL. In this example, we will use https://oauth.pstmn.io/v1/browser-callback. The Authorized JavaScript Origins field will be the same callback URL.
NOTE: In this tutorial, we signed in and configured Postman through the browser. https://web.postman.co/
Click Save.
The Gateway will generate your Client ID and Client Secret. Click the Download Credentials button to download the credentials file.
Open and view the credentials file, which will look like this. The file holds the details to call the API and Postman.
Log in to Postman and create a new request collection using the Authorization Methods template. Click the + sign in the top left corner and select the View more templates link, or you can click the + sign in the tab section.
NOTE: Again, in this tutorial, we signed in and configured Postman through the browser. https://web.postman.co/
Click the Authorization methods button.
Click the Use Template button.
On the Authorization methods collection, click on the ellipsis (⋮) and select Add request.
On the New Request collection, click on the ellipsis (⋮) and select Rename. Give the collection a new name.
We will name it Authorization Code Grant.
Within the Params tab, enter the IFS Service /usermgt/V2/users/me ION API URL in the GET parameters field.
In this example, we will enter:
Select the Authorization tab, and in the Auth Type field, choose OAuth 2.0.
To acquire a new access token, scroll down to the Configure New Token section and enter the following Postman mapping information from the downloaded Postman Web App Demo.ionapi credentials file you saved in the previous steps.
Enter the relevant credentials into the required input parameters. In the Token Name field, enter Auth Code Token and set Grant type to Authorization Code. The Callback URL is the embedded Postman link (https://oauth.pstmn.io/v1/browser-callback). The Auth URL is a concatenation of values pu + oa. Similarly, the Access Token URL is a concatenation of values pu + ot. The Client ID is value ci and the Client Secret is cs.
Scroll to the bottom of the page and click the Get New Access Token button.
This will take you to a login screen.
NOTE: Remember this is an activity in which the user must be present. The sign on must be performed, and the user is required to authorize the application I.E Postman, to call the API.
Once signed in, you can see Infor OS is prompting a Request For Approval regarding Postman using our credentials. Click the Allow button.
You will get the following message. You can click the Proceed button or wait a few seconds. The Manage Access Token screen will then appear.
This will provide a new token within the Postman application. On the Manage Access Tokens screen, click the Use Token button.
NOTE: When you click the Use Token button, a message will appear in the lower right hand corner saying that the Token was added.
We can test this by calling the same GET API using the /ifsservice/usermgt/v2/users/me URL. Click the Send button.
You can see that the call was successful—Error Code 200 and returned data.
Now, let's look into the Resource Owner Grant type. In this case, the calling application is not a mobile or web application but either a service system or backend application. Since it is an app calling an API, there is no user interaction present, which requires the OAuth2 Resource Owner Grant for a silent API call from a service/system client.
OAuth2 Resource Owner Grant
Go back to the OS portal. We'll create another authorized app. On the navigation menu, select Authorized Apps, then select the + button to create a new authorized app.
In the Name field, enter Postman_Resource_Demo. For the Type, choose Backend Service, and in the Description field, enter Postman as a calling system. Click Save.
Click the Download Credentials button.
On the Download Credentials screen, select Create Service Account and add an account in the Full Name field. Then click Download.
The credentials will look something like the following:
Now, create another Postman request. On the Authorization methods collection, click on the ellipsis (⋮) and select Add request.
On the New Request collection, click on the ellipsis (⋮) and select Rename. Give the collection a new name.
We will name it Resource Owner Grant.
Within the Params tab, enter the IFS Service /usermgt/V2/users/me ION API URL in the GET parameters field.
For example:
Select the Authorization tab, and in the Auth Type field, choose OAuth 2.0.
To acquire a new access token, scroll down to the Configure New Token section and enter the following Postman mapping information from the downloaded Postman_Resource_Demo.ionapi credentials file you saved in the previous steps.
Enter the relevant credentials into the required input parameters. In the Token Name field, enter Resource Owner Token and set the Grant type to Password Credentials. The Access Token URL is a concatenation of values pu + ot. The Client ID is ci and the Client Secret is cs. The Username is the service account key saak and the Password is the service account secret key sask.
Now we can request our token. Scroll to the bottom of the page and click the Get New Access Token button.
You will get the following message. You can click the Proceed button or wait a few seconds. The Manage Access Token screen will then appear.
This will provide a new token within the Postman application. On the Manage Access Tokens screen, click the Use Token button.
NOTE: When you click the Use Token button, a message will appear in the lower right hand corner saying that the Token was added.
Call the GET API by clicking the Send button.
You can see that the call was successful—Error Code 200 and returned data.
We have demonstrated how to call an ION API in three distinct ways:
- Using the OAuth2 SAML Bearer Grant, executed from the documentation page of the OS portal.
- Using the Postman OAuth2 Authorization Code Grant, where the user logs in using their username and password to authenticate and allows Postman to call the API on their behalf.
- If the calling system is a service or has no user interaction, use the OAuth2 Resource Owner Grant with details supplied when getting the token.
Lastly, if the API allows itself to be called Anonymously, no credentials are passed, and the gateway can successfully pass the request through. This fourth scenario is strictly discouraged unless the API provides non-sensitive information and is open to everyone.
If you are building your client application and want to call an ION API, you can refer to our GitHub, where we have published source code for getting tokens for various types of OAuth2 grants. Your app can be a Java or .NET application—we have supplied code for both.
Watch the following video to view all the steps that were covered
Resources
Help Documents and User Guides
On this page
- How to call an ION API