API Authentication

Calls to the API are managed using HTTP authentication (Only "Basic" is currently supported). Every request must include the Authorisation HTTP header containing username and password. The username is your Account Id and your password is a per-request, calculated signature hash.

Account Id and Secret Key

Your Account ID is given to you by Recipero Support when you have a license agreement in place with us. At the same time you will be given a secret key known only to you and us. This key is used to generate your signature hash.

How to generate your signature hash.

Once you have constructed your request you should append the POST body to the end of your secret key and compute a hexadecimal SHA1 hash of the result.

Example

Secret Key: 234623ger787qws3423 
Request Body: {"category":1}

1. The signature hash generation begins with the request body being appended to the secret key:-

234623ger787qws3423{"category":1}

2. An SHA1 hash is then calculated using the resulting string:

6b1fc03270e578a9765c364bd622e6dd293d4e8b

4. The Authorization header is then generated by combining the Account ID with the Signature Hash:

123:6b1fc03270e578a9765c364bd622e6dd293d4e8b

6. This itself is then Base64 encoded. This will be handled automatically if you are using a curl client library within PHP, C# etc.

MTIzOjZiMWZjMDMyNzBlNTc4YTk3NjVjMzY0YmQ2MjJlNmRkMjkzZDRlOGI=

A complete authorisation header with the encoded credentials should look like this:

Authorization: Basic MTIzOjZiMWZjMDMyNzBlNTc4YTk3NjVjMzY0YmQ2MjJlNmRkMjkzZDRlOGI=

Since we know your secret key too, we calculate what it should be given the content you have sent us and if we agree then we can be sure that the sender of the message was aware of the secret key AND that the contents of the message have not been altered in transit. These are both important security considerations. Of course the whole transaction is encrypted using SSL anyway so content is not readily readable in transit but we must err on the side of security.

PHP Example

Below is a simplified example using PHP to generate the signature hash. Similar steps can be taken in other programming languages.

// Replace with your Account ID
$accountId = 123;

// Replace with your secret key
$secretKey = '234623ger787qws3423';

// Set up the request body
$requestData = ['category' => 1];
$requestBody = json_encode($requestData);

// This is your signature hash, which can be used as the Basic Auth Password with 
// your chosen HTTP Client. 
// Expected value for this example would be: 
$signatureHash = sha1($secretKey . $requestBody);