What is an API KEY ?

Each request that is sent to the Aanbieders.be API has to provide a valid API KEY as parameter together with the unix timestamp and the 'nonce' used to generate the API KEY . The API key is a keyed hash value using the HMAC method and is generated using the public key, the secret key, a 'nonce' (number used once) and a timestamp.

How to generate an API KEY

To generate a valid API KEY we need 4 parameters :

• public key: The public key and the secret key is distributed to you after succesfull registration.
• secret key: The public key and the secret key is distributed to you after succesfull registration.
• timestamp: The timestamp is the unix time stamp and is a way to track time as a running total of seconds. This count starts at the Unix Epoch on January 1st, 1970. It is the responsibility of the partner to create and provide a unix time stamp.
• nonce: The 'nonce' is a 'number used once', and does exactly what it says on the can. It's a number that can only be used once. With that restriction that you should make sure that the nonce is not already used in the same second

As hashing algorithm, we use sha1.

Example

$hashmethod = 'sha1';
$key = '02647bad02eeeeee7b8e61fe10e09441'; // this is a fake key
$secret = 'd8235039ca21a7d59f3uuuuuu21dfddf'; // this is a fake key
$nonce = '4e13833c752e82d49c71d365109bf119'; // this is a fake nonce
$timestamp = time();// standard php function returning a timestamp

$apikey = hash_hmac('sha1', $key, $secret.$timestamp.$nonce); // combine the secret key and the timestap into one string!

Please note that the secret key, the nonce and the timestamp always need to be combined into one string in that order!

The API key needs to be recalculated with each request since the timestamp and the nonce combination has to be unique and used only once. If you do, the server will deny the request and return a HTTP status code equal to : HTTP/1.1 400 Bad Request. This means that somebody else who want to replay the request will be denied by the server. It's not possible to either change the timestamp or the nonce used, since these values are also used in the API key. Changing them will invalidate the API key and the server will deny the request anyway.