API Authentication

Note: If the images on this page do not immediately load, refresh the page.

A new standard authentication mechanism using OAuth 2.0 JWT is supported by the Unified Commerce Order Management APIs. These APIs may also require additional header parameters that were not included in the Classic OMS APIs, such as the x-vol-tenant and x-vol-site values described in the following walkthrough.

The new OAuth 2.0 access token can be generated either with Postman’s tools while defining a collection or API call, or performed as its own standalone call. In each case, two prerequisites are required to generate this token:

  • Application (Client) ID
  • Client Secret

Both of these are assigned to an implementation by Kibo and accessible in the Dev Center:

Postman will allow you to input under the Authorization tab of either an API call or at the collection configuration level. In this tab, enter OAuth 2.0 as the Type and Request Headers as the destination for auth data, then click Get New Access Token. This will open a module with fields for auth parameters.

Obtaining the Access Token Via Postman Tools

There are two available Access Token URLs where access tokens can be generated, depending on the environment:

  • Beta Environment:
  • Production Sandboxes/Tenants:

In the module shown below, provide one of these URLs followed by the prerequisite Application (Client) ID and Client Secret, then click Request Token. The token will then be generated.

Obtaining the Access Token Via API Call

Instead of using the Authorization tab and subsequent tool to generate a new token, a separate API call can be used instead. Make a POST call to that Access Token URL endpoint, with the Content-Type set as application/json and the prerequisites in the request body as shown below.

The response will return the new Access Token.

Authenticating API Requests

The access token is always required in the header when submitting an API call, but the other required keys are not universal across all APIs. Some APIs may require only the additional x-vol-tenant key, while others will also require a x-vol-site key. The tenant and site IDs are assigned per implementation by Kibo. This example shows what the header would look like for an API call requires the tenant key but not the site key. The access token would be provided in the {{x-vol-app-claim}} variable of Authorization.