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:
Signature: { "AppKey": 12345, "IssuedAt": "yyyyMMddHHmmss", "Token": "hashed string" }
AppKey is the unique numeric identifier of the application accessing the API. IssuedAt is the UTC timestamp at which the request was initiated. Token is a hashed string built with the following data:
AppKey + HttpMethod + RequestUrl + UtcTimestamp
The concatenated values in Token are a base64 encoded HMAC-SHA256 hash, using AppSecret as the key. Please note that RequestUrl 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
Example
In order to create a new account, the app must initiate a POST request to:
https://api.dialogportal.com/v1/user
Let us assume the following details:
AppKey | 32767 |
---|---|
AppSecret | RCL1EDAYOVHANLL3A51G |
Request time | 8th of April 2014 at 04:59:51 UTC |
The application’s AppKey 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
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 Samples
The following code samples will return the encrypted token, using AppSecret as the encryption key
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)); } }
public static function encryptToken($secret,$token) { $token_raw = hash_hmac("sha256", $token, $secret, true); return base64_encode($token_raw); }