Knowledge Base

Authorizing a Request

Article ID: 389
Last updated: 14 Oct, 2020

KBPublisher API requires that you authenticate every request by signing it. To sign a request, you calculate a digital signature using a cryptographic hash function. The hash function returns a hash value that you include in the request as your signature.

After receiving your request, API recalculates the signature using the same hash function and input that you used to sign the request. If the resulting signature matches the signature in the request, API processes the request. Otherwise, the request is rejected.

For additional security, you should transmit your requests using Secure Sockets Layer (SSL) by using HTTPS. SSL encrypts the transmission, protecting your request or the response from being viewed in transit.

Arguments to Authorize Request

For any given KBPublisher API request, you must include 3 arguments, it will allow you to authorize the request. 
How each value was generated is described below:

accessKey
The accessKey parameter identifies who is making the request. 
You can obtain this value from account page in your KBPublisher installation, My Account -> Profile -> API Settings -> Public API Key.

timestamp
The timestamp parameter indicates when the request was created. This value should be the number of seconds since the Unix epoch at the point the request is generated, and should be easily generated in most programming languages. API will reject requests which were created too far in the past, so it is important to keep the clock of the computer generating requests in sync with NTP.

signature
The signature parameter contains a value which is generated by running all of the other request parameters and secret value through a signing algorithm. The purpose of the signature is so that KBPublisher can verify that the request has not been modified in transit, verify the application sending the request, and verify that the application has authorization to interact with API.

Generating a Signature

To produce a signature, start by determining the HTTP method and URL of the request.

  • The request method will almost always be GET or POST for KBPublisher API requests.
    HTTP Method - GET
  • The base URL is the URL to which the request is directed, minus protocol ("http://" or "https://") and any query string.
    URL - domain.com/kb_directory/api.php 

Next, gather all of the GET parameters included in the request. These values need to be encoded into a single string which will be used later on. The process to build the string is very specific.

  • Sort the list of parameters alphabetically by key
  • Concatenate params to string like this: key=value&key2=value2... and so on 
  • URL encode string of parameters

Finally, the signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm and appended to request. Implementations of HMAC-SHA1 available for every popular language. For example, PHP has the hash_hmac function.

  • $signature = rawurlencode(base64_encode(hash_hmac("sha1", $string_to_sign, $secret_api_key, true)));
     

Here is an example how to sign request in PHP

// define api keys
$public_api_key = '1bcf89471d8df298cb6546b1f1da6c8c';
$secret_api_key = '718143f5faw978d6acf5b83c105c27c4';

// collect parameters 
$params = array();
$params[call] = 'articles';
$params['accessKey'] = $public_api_key;  // public API key here 
$params['timestamp'] = time();
$params['version'] = 1; // optional
$params['format'] = 'json'; // optional

// params to string
ksort($params);
$string_params = http_build_query($params, false, '&');

// collect to string 
$string_to_sign = "GET\n";
$string_to_sign .= "domain.com/kbp_dir/api.php\n"; // api url without protocol
$string_to_sign .= "/\n";
$string_to_sign .= $string_params;

// create signature
$signature = rawurlencode(base64_encode(hash_hmac("sha1", $string_to_sign, $secret_api_key, true)));

// add signature to request string 
$string_params .= '&signature=' . $signature;

// ctreate request
$request = 'https://domain.com/kb_dir/api.php?' . $string_params;

Request for the above example will be:

http://domain.com/kbp_dir/api.php?accessKey=1bcf89471d8df298cb6546b1f1da6c8c&
call=articles&format=json&timestamp=1385669114&
version=1&signature=LYfL2odFOS4hyJkI5uAZJGD%2BdEM%3D
Article ID: 389
Last updated: 14 Oct, 2020
Revision: 9
Access: Public
Views: 4588
Comments: 0