Authenticating requests

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

Example

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

https://api.dialogportal.com/v1/user

If we assume that the application’s AppKey is 32768, and that it initiates the request on the 8th of February 2013 at 07:18:00 UTC, the token is:

32768POSThttps://api.dialogportal.com/v1/user20130208071800

The following C# method 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)); 
	}
}

The signature will then look like this:

Signature: { 
	"AppKey": 32768, 
	"IssuedAt": "20130208071800", 
	"Token": "wytqCR4v1jmZxo22CeC0Qlp9sGi/MJ47G/Yitjg2X8U="
}