Authentication ​

Our API uses Hash-based Message Authentication Code (HMAC), a mechanism for calculating a message authentication code involving a hash function in combination with a secret key. It is this code that will form the Signature in the Request Header.

API Key & Secret ​

You are able to create your API Key/Secret pairs from the Hub if you have the IT-Admin role. The API Key will be used to identify your API User and the Secret is used to build up the HMAC Signed Request. You are able to have multiple API Key/Secret pairs active at any one time. Please consider rotating keys at least annually.

Managing credentials ​

Users assigned the IT Admin role are able to manage the API v2 access credentials.

• Create new API Key/Secret.
• Activate/deactivate API Keys.
• Enable/disable the API User.

Go to API Admin in sandbox or production.

IP Whitelisting ​

As an additional layer of security, you will need to whitelist your IP address before being able to make requests to our API. You can manage your IP White list within the API management pages.

Signature ​

As mentioned above, each request is signed with a signature. This is made up of a combination of (where provided) the API Key, HTTP Method, Endpoint, Client Request ID, Brand Identifier, and UTC Timestamp (in milliseconds), all of which are concatenated with hyphens and then passed to a HMAC Hash function (using SHA256) along with your API Secret. You can see a working example of this in use in the Postman collection in the 'Digital Gift Cards/Issue Digital Code' request under the 'Pre-request Scripts' tab.

The string to be built up that is then passed to the HMAC Hash function will look something like this...

e65c55889cca73b82871c616c874ca3a0aa6cf955b5970b0353e9d3e58dcc690-POST-digital-issue-abcd1234-debenhams-1537947765417

...where the component parts are (as described above):

API Key-HTTP Method-Endpoint-Client Request ID-Brand Identifier-UTC Timestamp (in milliseconds)

Signature builder ​

Each endpoint can have a slightly different set of fields required to generate the signature string, based on what parameters the call requires. To help clearly identify the correct fields we have provided a Signature Builder Tool within the hub.

If you're getting an authentication failure you can use the signature builder to compare your generated hash with ours and spot any problems.

Example raw signature string and final Signature for (Digital Issue) ​

Concatenate all of the above (where provided) separated by hyphens into a string:

e65c55889cca73b82871c616c874ca3a0aa6cf955b5970b0353e9d3e58dcc690-POST-digital-issue-abcd1234-halfords-1540279391599

- Raw Signature

45e87c2a158677007ddd604fb16ce5b89fec431e5370e455f1ddc0f78b5358ae

- Secret

Use your Secret and the SHA256 HMAC Hash function to generate the Signature:

19694a0866b20938698e490d4ecd6f429e8e781d912451362e7a1ec174c6f59e

- Hashed Signature

Common authentication mistakes ​

• While testing, it can be tempting to use a hardcoded timestamp - don't do this as we validate that the timestamp is from the last few minutes.
• Ordering of the signature string - as we are performing a hash on the string, the order of the fields is critical.

Request Header ​

The request headers will look like this.

Content-Type: "application/json"
Accept: "application/json"
API-Key: YOUR_API_KEY
Signature: SIGNATURE_OF_REQUEST
Timestamp: CURRENT_UTC_TIMESTAMP_IN_MILLISECONDS

Content-Type: "application/json"
Accept: "application/json"
API-Key: YOUR_API_KEY
Signature: SIGNATURE_OF_REQUEST
Timestamp: CURRENT_UTC_TIMESTAMP_IN_MILLISECONDS

Example implementations ​

We have created some simple implementations in several popular programming languages to help you get up and running more quickly:

• C# .NET
• Go
• Java
• Node.JS
• PHP
• Python
• Ruby

You can download a zip file of these implementations here