Authentication

The X-Bol-Authorization header can be generated by following these steps:

public_key:hash

Step 1 – The API keys

First step in this process is gathering your API keys, which can be found in your seller dashboard. We will use fake public and private keys in the examples on this page.

Warning: Do not use the following keys in your own code, these are fake codes and only used in this example.

Public key:
oRNWbHFXtAECmhnZmEndcjLIaSKbRMVE

Private key:
MaQHPOnmYkPZNgeRziPnQyyOJYytUbcFBVJBvbMKoDdpPqaZbaOiLUTWzPAkpPsZFZbJHrcoltdgpZolyNcgvvBaKcmkqFjucFzXhDONTsPAtHHyccQlLUZpkOuywMiOycDWcCySFsgpDiyGnCWCZJkNTtVdPxbSUTWVIFQiUxaPDYDXRQAVVTbSVZArAZkaLDLOoOvPzxSdhnkkJWzlQDkqsXNKfAIgAldrmyfROSyCGMCfvzdQdUQEaYZTPEoA

Step 2 – Building your signature string

The signature string consists of several variables in a specific order. The format is outlined below.

http_verb +'\n\n'+ content_type +'\n'+ x_bol_date +'\n'+ 'x-bol-date:'+ x_bol_date +'\n'+ uri

note: ‘\n\’ indicates a new line. 

In this example, we will be retrieving a list of all open orders through the Order API.

Variable Value
http_verb GET (in this example, can also be PUT, POST or DELETE when using other endpoints)
content_type application/xml
x_bol_date Wed, 17 Feb 2016 00:00:00 GMT
uri /services/rest/orders/v2 –

Note: the uri starts after the root endpoint and parameters (like paging) are not used when generating the signature string.

Example

When retrieving all open orders, your signature string should look like this:

GET

application/xml
Wed, 17 Feb 2016 00:00:00 GMT
x-bol-date:Wed, 17 Feb 2016 00:00:00 GMT
/services/rest/orders/v2

Step 3 – Encrypt your Signature string using your private key with HMAC (SHA-256)

After building your signature string, it is first encrypted with HMAC (SHA-256) using your private key. After encrypting the example above it should like like:

ž¬ËZõÈÕàazÑÇ“EÛuy…/ׂ–‚s>/ÑÛ

Step 4 – Encrypt once more using Base 64

The HMAC encrypted signature string is then once more hashed using Base 64. It should now look like:

nqzLWvXI1eBhBXrRx5NF23V5hS8Q1xWCloJzPi/RAts=

Step 5 – Combine Public key and encrypted Signature

This is where your Public key comes in. Place the public key in front of your double hashed signature string seperated by a colon. Like this:

public_key:hash

It should now look like:

oRNWbHFXtAECmhnZmEndcjLIaSKbRMVE:nqzLWvXI1eBhBXrRx5NF23V5hS8Q1xWCloJzPi/RAts=

Finally, this is your X-Bol-Authorization header.

Example code

In Postman this open orders example would look like:


//Environment variables
var public_key = environment.public_key;
var private_key = environment.private_key;
var url = environment.url;

// The HTTP request
var http_uri = '/services/rest/orders/v2';
var http_method = request.method;
var http_content_type = request.headers["Content-Type"];

//X-Bol-Date
var bol_date = Date.create().utc(true).format('{Dow}, {dd} {Mon} {yyyy} {HH}:{mm}:{ss} GMT');

//X-Bol-Authorization
var bol_signature = http_method+'\n\n'+ http_content_type+'\n'+bol_date+'\n'+'x-bol-date:'+bol_date+'\n'+http_uri;
var bol_authorization = public_key+":"+CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(bol_signature, private_key));

//Setting environment variables
postman.setEnvironmentVariable('x_bol_date', bol_date);
postman.setEnvironmentVariable('x_bol_authorization', bol_authorization);

 

Wehave also created code examples in C# and Java to help creating your own authentication headers. Please click on the links below to get to the examples.