The Kudoz API are secured by default: An API Key and an API Secret pair is mandatory to get access and interact with the API. If you don’t already have an API key/secret pair (or if you have lost them) you can request new credentials now by contacting our support.

Please notice that clients may request as many API key/secret pairs as needed. This can help isolating and identifying different API consumer components on the client side. It also allows credential rotation and therefore reduces the business impact if an API key/secret pair gets compromised.

To be authenticated, each request to our servers must include an API key together with an authentication token (your API secret should never be included in your requests nor disclosed to any third party).

The authentication token is computed from the request parameters and the API secret using the HMAC-SHA256 (see Hashed Message Authentication Mode with SHA-256 hashing).

HMAC-SHA256

Before going into further details, you need to be able to compute a Base64 encoded HMAC-SHA256 token of an input string using your API secret. Luckily, HMAC-SHA256 hashing is built-in in most languages and frameworks. Below example implementations in different popular languages.

Ruby

require 'base64'
require 'openssl'

def hmac_sha256(secret, data)
  Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', secret, data))
end

PHP

<?php
function hmac_sha256($secret, $data) {
  return base64_encode(hash_hmac('sha256', utf8_encode($data), $secret, true));
}
?>

Java 8

import java.util.Base64;
import java.io.UnsupportedEncodingException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class HmacSha256 {
  public static String compute(String secret, String data)
      throws UnsupportedEncodingException, InvalidKeyException, NoSuchAlgorithmException {
    Mac algo = Mac.getInstance("HmacSHA256");
    algo.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
    return Base64.getEncoder()
      .encodeToString(algo.doFinal(data.getBytes("UTF-8")));
  }
}

Objective C

#import <CommonCrypto/CommonHMAC.h>

@interface HmacSha256:NSObject
+ (NSString*) hash:(NSString*)data withSecret:(NSString*)secret;
@end

@implementation HmacSha256
+ (NSString*) hash:(NSString*)data withSecret:(NSString*)secret
{
  const char *cData = [data cStringUsingEncoding:NSUTF8StringEncoding];
  const char *cSecret = [secret cStringUsingEncoding:NSUTF8StringEncoding];
  unsigned char cHMAC[CC_SHA256_DIGEST_LENGTH];
  CCHmac(kCCHmacAlgSHA256, cSecret, strlen(cSecret), cData, strlen(cData), cHMAC);
  NSData *dataHash = [[NSData alloc] initWithBytes:cHMAC length:sizeof(cHMAC)];
  return [dataHash base64EncodedStringWithOptions:0];
}
@end

Shell

echo -en ${DATA} | openssl dgst -sha256 -hmac ${SECRET} -binary | openssl enc -base64

Examples

Given the following secret :

tsDQyZzf90zBAk/gwtMR2jbvl05AX/uWYXKBzhzTB1cdfx07Z0UQN+J3CZoONZd/tYo3LxtPLR6+EibL

Here are some examples of HMAC-SHA256 input/output values to test your implementation against:

Input Expected output
"" zTVtRNgeW9ho/lQUGzoNP5OBn68AHr1+mSsutZ9U0aI=
"hello" SjXO87vEvJndWzd63D0flvFwp4m6XrhH8ORA8qg8irU=
"hello\nworld!" OSX7egKeb8W/Qumjeeua9UVLaf+ExwnsIoBQzJdX5fM=
"[*\\ hélłö întërnatïønal wòrld ! \\*]\n\t" yApjjJ889+6kzww3L1/MbSn2/PYCkqVnzADu2f6aarw=

Authorization header

Each request must include the correct HTTP Authorization header in order to be correctly authenticated by the Kudoz API server. The auhtorization header must be formatted as follows:

Authorization: TOKEN {Api Key}:{Random Unique UUID}:{Timestamp}:{Authentication Token}
  • API Key a valid API key.
  • Random Unique UUID a random UUID that must be unique to each request (at least within the last hour).
  • Timestamp current time expressed in POSIX time (number of seconds since 00:00:00 UTC on 1 January 1970). Must be in sync with current time with no more than 10 minutes time lag from actual current time or the authentication will fail.
  • Authentication token computed using the API Secret and the request information as described in the next section.

Authentication token

The authentication token is obtained by hashing the Random Unique UUID and the Timestamp (as described in the authorization header) using the API Secret and the HMAC-SHA256 algorithm.

In pseudocode, the token is computed as follows:

string_to_hash = random_unique_uuid + ":" + timestamp
authentication_token = hmac_sha256(api_secret, string_to_hash)

Example

Given the following input data:

  • API Key: 25fe5607-f78a-4353-bbe1-e26db08bf4ff
  • API Secret: YWk5vMx67QLiH2YH5H09ZnCtnIdt5sEy7DSWWLlP
  • Random Unique UUID: d0cf7497-8f19-4293-b5a4-bd3136ef8a04
  • Timestamp: 1460628958

The authorization token for this request is: H7TgGUXKnsaJm2/e56LbaBQsn+DxP7U6B1WQ0vQfocU=

Authorization header must be therefore as follows:

Authorization: TOKEN 25fe5607-f78a-4353-bbe1-e26db08bf4ff:d0cf7497-8f19-4293-b5a4-bd3136ef8a04:1460628958:H7TgGUXKnsaJm2/e56LbaBQsn+DxP7U6B1WQ0vQfocU=

For instance, here is how getting the data at http://api-staging.getkudoz.com/integration/v1/jobs/537196/stats using curl in your command line would look like:

curl -H "Authorization: TOKEN 25fe5607-f78a-4353-bbe1-e26db08bf4ff:d0cf7497-8f19-4293-b5a4-bd3136ef8a04:1460628958:H7TgGUXKnsaJm2/e56LbaBQsn+DxP7U6B1WQ0vQfocU="
     -H "Accept: application/json"
     http://api-staging.getkudoz.com/integration/v1/jobs/537196/stats