Table of Contents

HMS APIs utilize HMAC-SHA1 security, which requires use of the security credentials provided by HMS at the time a contract is established. This page explains the nature and use of the security credentials. If you have not already contacted HMS and received these credentials, please check the home page for instructions.

Definition

Credentials provided by HMS consist of a Key and a Secret, both of which are required to create authenticated API calls to HMS. You should have been provided with these credentials after establishing a contract with HMS.

Components

  • Key = Identifies the Credentials being used. Provided with every API call.
  • Secret = Used to generate the encoded Signature used to validate every API call.
  • Signature = Encoded string used to validate API calls.

Examples

  • Key = fCTYXpuGkVcnDf6JLSSbtA==
  • Secret = jFhVj/tC5L/FonLpKYXVxQ==
  • Signature = 8qrFmQbQgILzdDeQfbJTxHXeZvE=

Use

The use of HMS Security Credentials with HMS API calls has the structure and uses the process documented below.

Security Structure for API Calls

The security portion of an API call is structured as follows:

  • A Timestamp value is a required value to be passed where Timestamp is the Unix epoch time in milliseconds at the time the request is submitted.
  • The Key is passed as a parameter in any API calls as key=Key.
  • The Secret is used to generate a Signature.

Signature Generation

The Signature is a base64 encoded string which is created using the HMAC-SHA1 signature algorithm, with the following inputs:

  • Secret - Provided in the HMS security credentials
  • String - Consisting of the portion of the URL following the Root to the end of the URL, including the Timestamp and Key as follows:

String = /Version/Requesttimestamp=Timestamp&key=Key

Example

For example, given:

  • Root = https://api.hmsonline.com
  • Version = v1
  • Request = search/masterfile?
  • Timestamp = 1369844777731
  • Key = fCTYXpuGkVcnDf6JLSSbtA==
  • Secret = jFhVj/tC5L/FonLpKYXVxQ==

Then

  • String = /v1/search/masterfile?timestamp=1369844777731&key=fCTYXpuGkVcnDf6JLSSbtA==

Generating the Signature with Secret and String as inputs yields:

  • Signature = 8qrFmQbQgILzdDeQfbJTxHXeZvE=

The Signature then gets appended to the original URL as follows:

Root/Version/RequestTimestamp&Key&signature=Signature

The full URL for the API call in our example should then appear as something like:

https://api.hmsonline.com/v1/search/masterfile?timestamp=1369844777731&key=fCTYXpuGkVcnDf6JLSSbtA==&signature=8qrFmQbQgILzdDeQfbJTxHXeZvE=

The Body is not required for this particular API call.

Notes:

  • All security values shown here and throughout this documentation are for illustration purposes only and will not work as shown. You must get and properly use security credentials from HMS in order to use the HMS APIs.
  • A new Signature must be generated for each API call in any of the HMS services.