How To: Use Postman to Test the Workflow REST API using OAuth

[#1]

How To: Use Postman to Test the Workflow REST API using OAuth

KB002838

PRODUCT

K2 Five

TAGS

Third-Party Integration

Use this article to learn how to use Postman to test the Workflow REST API using an OAuth token.

The screenshots and instructions for third-party software are accurate at the time of publication. Third-party vendors may have changed or updated aspects of their systems (such as user interfaces, functionality, and security). As a result, this content may be outdated.

K2 Cloud uses Open ID Connect (OIDC) to authenticate and authorize users. If you were using OAuth in K2 Cloud, or need to use OAuth in a new application that uses the K2 APIs, you’ll need to configure Postman and/or your code to use new client IDs and redirect URIs/Auth URLs. See the article How to retrieve client IDs and Redirect URIs for use in OAuth against K2 APIs for more detail.

Step 1: Add the K2 API Delegated Permission to your Azure AAD App

Follow the steps in Configure AAD and K2 Services for Inbound OAuth to add the K2 API permission to your Azure AD App. This is necessary for K2 to authorize the OAuth request from your AAD identity.

Step 2: Enable the Workflow REST API and get the Swagger link

In this step, you enable the Workflow REST API and get the URL to the Swagger (OpenAPI) file for the service.

1. Open K2 Management.
2. Navigate to Integration > APIs > Workflow REST. Note that you can also call the SmartObject OData API with an inbound OAuth token.
3. Enable the Workflow API and click the open link of the Swagger URL.

4. When the new browser window opens, copy the link at the top of the window.

Step 3: Import Swagger into Postman

In this step, you import the Swagger file into Postman.

1. Open Postman.
2. Click Import in the upper left.
3. On the Import dialog, click Import From Link and paste in the Swagger file link as shown here:

4. Click Import.

5. Navigate to Workflows > Get Workflows.

Parameters are automatically added to the request. Keep in mind that not all parameters are required. For more information see the Swagger definition. For this Get Workflows method, use the value Startable for the type.

Step 4: Acquire an OAuth Token and Test the API

In this step, you configure Postman to retrieve an OAuth token to access the K2 Workflow REST API.

1. Click Authorization and then Get New Access Token.

2. On the Get New Access Token dialog, fill in the values for your environment:

Field	Example Value
Callback URL (the reply_uri)	https://www.getpostman.com/oauth2/callback
Auth URL	https://login.windows.net/{Azure Tenant}/oauth2/authorize?resource=https://api.k2.com/
Access Token URL	https://login.windows.net/{Azure Tenant}/oauth2/token
Client ID	Your app’s Client ID (Application ID), such as 433d08a8-e5c8-4784-aeb0-b0ac24af6c1c
Client Secret	Your app’s secret, such as k77OemePvRUURLaXBCTRUaieDNXgaaLoiohW/Md0X5M=

In the Auth URL field, it is necessary to add ?resource=https://api.k2.com/ to the end of the string in order for Azure to send K2 the correct token values. This value does not have to be https://api.k2.com but it must match the audience value of the Bearer Token OAuth resource. You can see this in K2 Management > Authentication > OAuth > OAuth Resources.

An easy way to find the auth URLs and Tenant ID of your Azure tenant is to use the following OpenID URL, replacing [Azure Tenant] with your full tenant name such as k2example.onmicrosoft.com: https://login.microsoftonline.com/[Azure Tenant]/.well-known/openid-configuration

3. Click Request Token and log in using your AAD identity.
4. Scroll down to the bottom of the Manage Access Tokens dialog and click Use Token.

To see encoded information about your access token, go to jwt.ms, paste your token value, and decode it.

5. Click Send and note the JSON payload in the Body of the response.

See Also

Use these links for learning more about OAuth in the K2 platform and code for calling K2 services. 

• Configure AAD and K2 Services for Inbound OAuth
• Outbound Authorization and OAuth in K2
• K2 Five Developer Reference: K2 Five Workflow REST API code samples
• K2 Cloud Developer Reference: K2 Cloud Workflow REST API code samples