Goods & Services API documentation

Goods & Services API documentation
2. Authentication


Authentication

A HMAC authentication (Hash-based message authentication code) system is used to connect to our Goods & Services API. We use an API key, API secret and nonce system, with a sha256 encryption algorithm.

The authentication mechanism is based on custom HTTP headers passed for each request submitted to the API:

  • X-TransferTo-apikey
  • X-TransferTo-nonce
  • X-TransferTo-hmac

An API secret and an API key specific to your account are used to generate these headers.

For each call to the API, you will need to generate a nonce. A nonce is a numerical value that is unique to each call.
An HMAC authentication (Hash-based message authentication code) system is used, with sha256 encryption, to generate the X-TransferTo-hmac header.

X-TransferTo-hmac header value is a base64 encoded HMAC of your API key concatenated to the nonce, encrypted with your API secret as a secret, using the sha256 encryption algorithm.

ENCODE_TO_BASE64( HMAC_SHA256( api_key.nonce , api_secret ) )

Here are a few basic examples:

1. Sample PERL client to generate HTTP headers

sub _gen_http_headers
{
    my $api_key = 'XXXXXXXXXX';
    my $api_secret = 'YYYYYYYYYY';

    use Digest::SHA qw(hmac_sha256_base64);
    use Time::HiRes qw(gettimeofday);
    my $nonce = gettimeofday(); # nonce has to be unique for each request
    my $hmac = hmac_sha256_base64($api_key, $nonce, $api_secret );

    #Digest::SHA does not pad base64 output
    while (length($hmac) % 4) {
        $hmac .= '=';
    }

    my $client = REST::Client->new(  );

    $client->addHeader('X-TransferTo-apikey', $api_key );
    $client->addHeader('X-TransferTo-nonce', $nonce );
    $client->addHeader('X-TransferTo-hmac', $hmac );

    return $client;
}

2. Sample PHP client to generate HTTP headers

<?php
$api_key = 'XXXXXXXXXXXX';
$api_secret = 'YYYYYYYYYYYY';
$nonce = gettimeofday(true); # nonce has to be unique for each request
$host = 'https://gs-api.dtone.com/v1.1/';

$hmac = base64_encode(hash_hmac('sha256', $api_key.$nonce, $api_secret, true ));
echo "hmac : $hmac".PHP_EOL;

// set up the curl resource
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/ping");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "X-TransferTo-apikey: $api_key",
    "X-TransferTo-nonce: $nonce",
    "X-TransferTo-hmac: $hmac",
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// execute the request
$output = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// close curl resource to free up system resources
curl_close($ch);