API Authentication Process

When is this Changing?

This took effect on March 31, 2016

How is Sears implementing enhanced API security?
The new Authentication model for APIs will include HmacSHA256 signing algorithm.

To illustrate the changes in an elaborative way, it is explained by taking any API for instance: – remittance service.

Previous Approach
Previously, this API is called in the following way by providing both email and password in query parameters:

https://seller.marketplace.sears.com/SellerPortal/api/oms/remittance/v3?email={}&password={}&fromdate={}&todate={}

Current Approach
Currently, based on the new keyed-hash message authentication code mechanism, sellers would need to perform the following steps for making any API call:

API calls will now include seller ID: https://seller.marketplace.sears.com/SellerPortal/api/oms/remittance/v3?sellerId={}&fromdate={}&todate={}’

Further, API header will have the following information:

The format of the authorization header would be : HMAC-SHA256<white space>emailaddress=<email address>,timestamp=<timestamp>,signature=<signature>

As an example, “authorization:HMAC-SHA256 emailaddress=test@searshc.com,timestamp=2016-02-11T20:23:05Z,signature=bf4ece266c47538d793b296fa772e9ea299611c6c6e48841f4e66a4f994bed26″

How to create a new signature?
The new signature algorithm needs two inputs:

  • String to Sign
  • Secret Key

To create “String to Sign”:

The format to generate this will be: Seller id:Emailaddress: CurrentTimestamp. For example, if the “String to Sign” string is: 1234:test@searshc.com:2016-02-11T20:23:05Z

  • Where Seller ID is seller’s account id in Seller Portal
  • Email address is their actual email address that sellers pass in their API calls
  • CurrentTimestamp is the current time stamp in UTC time zone with format “yyyy-MM-dd’T’HH:mm:ss’Z’”.

Please note that the time stamp will be valid only for 30 minutes at the server side which means a generated signature can only be used for 30 minutes after which the signature again needs to be created using the current time stamp. The timestamp passed in the request is validated against the configured expiry time.

To create Secret Key:

Every seller will be provided with a base64 encoded secret key. Sellers can log into Seller Portal to (re-)generate their key from their “Account Info” page (refer to screenshot below on how to access this page):

secret key

To create a new signature:

Sellers could use any programming language APIs to create this signature ( For reference, use this URL: http://www.freeformatter.com/hmac-generator.html – “Select a message digest algorithm” SHA256). Do note that sellers will have to pass the signature in Hexadecimal format in the API header.

Once the request reaches Seller Portal server, we will validate the signature provided by the seller using the inputs provided to authenticate the API calls.

Is there a flow diagram that helps explain the proposed changes?
Proposed changes in a snapshot:

API Flow