Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated URL to new domain, and added Postman usage details

...

For an application to be allowed to make calls to the API, it must send a signature with every request. The signature is a JSON string passed in the HTTP Header. It has the following format:

Code Block
languagec#
linenumberstrue
Signature: {
	"AppKey": 12345, 
	"IssuedAt": "yyyyMMddHHmmss", 
	"Token": "hashed string"
}

AppKey is  is the unique numeric identifier of the application accessing the API. IssuedAt is  is the UTC timestamp at which the request was initiated. Token is  is a hashed string built with the following data:

...

The concatenated values in Token are  are a base64 encoded HMAC-SHA256 hash, using AppSecret as  as the key. Please note that RequestUrl is  is the complete URL.

If authentication fails, a HTTP status code 401 is returned along with information about the error: see Standard status codes - Bad signature

...

In order to create a new account, the app must initiate a POST request to:

https://api.dialogportalrubiq.comnet/v1/userentity

Let us assume the following details:

AppKey32767
AppSecretRCL1EDAYOVHANLL3A51G
Request time 8th of April 2014 at 04:59:51 UTC

The application’s AppKey is  is 32767, and it initiates the request on the 8th of April 2014 at 04:59:51 UTC, so the raw token is:

  32767POSThttps://api.dialogportal.com/v1/user20140408045941

...

rubiq.net/entity20140408045941

When encrypted using AppSecret RCL1EDAYOVHANLL3A51G, the encrypted token is:

eTqyykFcR5kN2kvb9RZiRXwV87xrowNREeNf6GGsIEA=

The complete signature will then look like this:

Code Block
Signature: {
	"AppKey": 32767,
	"IssuedAt": "20140408045941",
	"Token": "eTqyykFcR5kN2kvb9RZiRXwV87xrowNREeNf6GGsIEA="
}

Making requests with Postman

Use the following "Pre-request Script" in Postman to generate the signature and add it as a request header:

Code Block
languagejs
titlePostman Pre-request Script
const AppKey = 32767;
const AppSecret = 'RCL1EDAYOVHANLL3A51G';
const IssuedAt = new Date().toISOString().replace(/(\d+)-(\d+)-(\d+)T(\d+):(\d+):(\d+):?.*/, '$1$2$3$4$5$6');
const message = `${AppKey}${pm.request.method}${pm.request.url}${IssuedAt}`;
const Token = CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(message, AppSecret));
const signature = { AppKey, IssuedAt, Token };
pm.request.headers.add({
    key: "Signature",
    value: JSON.stringify(signature)
})

Code Samples

The following code samples will return the encrypted token, using the AppSecret as the encryption key:

Code Block
languagec#
themeEclipse
languagetitlec#C#
linenumberstrue
public static string EncryptToken(string secret, string token) {  
	byte[] bytesSecret = Encoding.UTF8.GetBytes(secret);  
	using (var hmacsha256 = new HMACSHA256(bytesSecret)) {  
		byte[] tokenBytes = Encoding.UTF8.GetBytes(token);  
		return Convert.ToBase64String(hmacsha256.ComputeHash(tokenBytes));  
	}
}

When encrypted using AppSecret RCL1EDAYOVHANLL3A51G, the encrypted token is:

S/3bH3CD44NVM15UpuYds3iJEUp+xicCUZigXpghzaQ=

The complete signature will then look like this:


Signature: { "AppKey": 32767, "IssuedAt": "20140408045941", "Token": "S/3bH3CD44NVM15UpuYds3iJEUp+xicCUZigXpghzaQ=" }
Code Block
Code Block
languagephp
themeEclipse
titlePHP
linenumberstrue
public static function encryptToken($secret,$token)
{
	$token_raw = hash_hmac("sha256", $token, $secret, true);
	return base64_encode($token_raw);
}


Code Block
languagec#
themeEclipse
titleswift
linenumberstrue
func encryptToken(_ token: String, _ secret: String) -> String {
	let bytesSecret = secret.utf8.map({$0})
    let tokenBytes = token.utf8.map({$0})
    let encryptedBytes = try! HMAC(key: bytesSecret, variant: .sha256).authenticate(tokenBytes)
    return encryptedBytes.toBase64()!
}

The library used for generating the encrypted token in the last example is CryptoSwift https://github.com/krzyzanowskim/CryptoSwift.