Authenticating APIs

Edit online

Sterling Intelligent Promising supports OAuth2 authentication method. To access APIs, you must generate an access token, which will be used to invoke APIs.

About this task

To access APIs offered in Sterling Intelligent Promising, users must obtain an access token and use it to make an API request. Each tenant associate to an environment whether its Developer toolkit, pre-production, or non-production requires its own access token.

Each access token that is provided is valid for the next 12 hours. After this time, you must generate a new access token. To encourage the efficient use of an access token, the system allows up to 1000 access token generated per hour. Beyond this limit, a user is expected to receive a rate-limit reached error.

As a best practice, the connecting application is encouraged to store the access token in a local cache so that it can be reused until expiry. On expiry of the token, the application client may request a new token and follow the same caching procedure.

A well managed token system is critical to ensure zero disruption to your service. It is recommended that you have a centralized token management service, which performs a routine token renewal so that the consuming application can share the token information for accessing APIs. Prior to the token expiry, the system must make ahead a token request within 30 minutes from expiry to ensure that downstream clients have sufficient time to switch to the new token.

For more information about best practices, see API best practices.

Procedure

The following procedure provides an example of how to obtain an authentication token by using an API client.

Make an OAuth HTTP POST request to obtain an access token.
1. Open an API client such as POSTMAN.
2. Set the Request type to POST.
3. Set the URL to https://api.watsoncommerce.ibm.com/inventory/{tenantid}/v1/oauth2/token and replace tenantid with your tenant ID.
4. Add the following parameters.
  - HTTP Header:
```
"Content-Type" : "application/x-www-form-urlencoded"
"Authorization" : "Basic <base64_encoded_clientID:clientSecret>"
```
    Note: The standard way to transfer HTTP header data is base64 encoding. To retrieve the base64 encoded value, complete the following steps:
    
    Concatenate clientId, for example ABC and clientSecret, for example 123 with a colon (:).
    ABC:123
    
    Use your preferred base64 encode utility to encode the string ABC:123.
  - Body:
```
grant_type=client_credentials
```
  The POST response generates an access token as shown in the following example:
```
{
"token_type": "bearer",
"access_token": "trYl8rEz0A11E32kVdWemRD9ilYQbOLP",
"expires_in": 43200
}
```
  Use the value of the access_token attribute during an API request. The expires_in attribute defines the expiry time in seconds in which the token is valid.
  
  Note: All tokens provided by IBM® Sterling Intelligent Promising is valid for 12 hours.

By using the access token, you can make an API call along with the header and input body.

For example, for Inventory Visibility Availability API:

https://api.watsoncommerce.ibm.com/inventory/<tenantid>/v1/availability/node

Header:

"Content-Type" : "application/json"
"Authorization" : "Bearer [access_token]"

Body:

{
  "demandType": "OPEN_ORDER",
  "lines": [
    {
      "deliveryMethod": "SHP",
      "itemId": "sample0123",
      "lineId": "line_sample01234",
      "productClass": "NEW",
      "shipNodes": "["eastnode01"]",
      "unitOfMeasure": "EACH"
    }
  ],
  "segment": "ONLINE",
  "segmentType": "Channel"
}

What to do next

For more information about authenticating APIs, see the OAuth authentication documentation.