Introduction
HMAC (hash-based message authentication code) is used to verify that a request is coming from an expected source and that the request has not been tampered with in transit. This is achieved by including both a public (key-identifier) and private key (key-secret) in each message, the latter of which is only known to the server and client. Using these values, the client will generate a unique HMAC (a hashed code) representing its request to the server. The client sends that HMAC to the server, along with a timestamp and all the arguments and values it was going to send anyway. The server (CrowdTwist) gets the request and re-generates its own unique HMAC based on the submitted values using the same methods the client used. The server (CrowdTwist) will then compare the two HMACs, if they are equal, then the server trusts the client, and processes the request.
1) HMAC does not require an API key in the request URL, but does use a key in the header. The key is the CrowdTwist public HMAC key.
2) All calls to api[client_id].crowdtwist.com are supported via HMAC, but calls to pos[client_id].crowdtwist.com are not supported.
3) HMAC is not supported on the Legacy Auth Sign-In and Sign-Out endpoints.
Creating a Request
Once HMAC has been enabled, all incoming API calls will require HMAC request headers, which will be detailed below.
- X-CT-Authorization: This header must follow the convention “CTApiV2Auth [public key]:[signature]”, where [public key] is the HMAC public key and [signature] is the HMAC hash that requires several steps to generate.
- Content-Type: This header must be “application/json” for POST and PUT requests.
- X-CT-Timestamp:This header must be a UNIX timestamp and must be within 15 minutes of the current time. This timestamp is included to prevent replay attacks.
X-CT-Authorization: CTApiV2Auth publickey:signatureX-CT-Timestamp: 1505325876486
X-CT-Authorization: CTApiV2Auth publickey:signatureX-CT-Timestamp: 1505325876486
Creating the Signature
To create the [signature] value in the X-CT-Authorization header, several steps need to be followed.
- [signature] = Base64(HMAC-SHA-256(PrivateKey, StringToSign ) )
The PrivateKey along with a StringToSign body will need to be HMAC-SHA-256 hashed. Then, that resulting hash will be Base64 encoded to create the signature. This signature is then added to the X-CT-Authorization header along with the public key as seen in the example.
To start, the StringToSign parameter will be created by appending the strings below separated by a new-line (“\n”) character.
StringToSign = HTTP-Verb + "\n" +Content-MD5 + "\n" +Content-Type + "\n" +Timestamp + "\n" +RequestURI
StringToSign = HTTP-Verb + "\n" +Content-MD5 + "\n" +Content-Type + "\n" +Timestamp + "\n" +RequestURI
- HTTP Verb:the HTTP method (GET, POST,PUT, etc.)
- Content-MD5:an MD5 hash of the exact request body (JSON Format)
- Content-Type:Currently, the only value supported for POST/PUT requests is application/json
- Timestamp:the UNIX timestamp
- RequestURI:the URL with the query string parameters. This is not the full path, just the path and query string after domain.
- For example, the RequestURI for https://api.crowdtwist.com/v2/activities, would be /v2/activities.
Sample PUT Request
To generate the signature the below process needs to be followed:
signature = Base64(HMAC-SHA-256(PrivateKey, StringToSign))
To create the StringToSign, the request body will need to be MD5 hashed.
{
“email_address”: “testing@crowdtwist.com”,
“postal_code”: “10010”,
“last_name”: “test”
}
MD5 value:
d8d84b98493543c9d51bda8c7c73f622
Next, the StringToSign is created by adding the MD5 hash.
StringToSign value:
PUT
d8d84b98493543c9d51bda8c7c73f622
application/json
1505759963477
/v2/users/11116703
After forming the StringToSign, the HMAC SHA-256 hashing algorithm using the private key is applied.
HMAC SHA-256 value:
3a9805afa6ec3850b80273c61a06a11702c38b868cc986e8d981b4a63d2356f2
To create the signature the above HMAC SHA-256 value will be Base64 encoded using UTF8.
Base 64 value:
M2E5ODA1YWZhNmVjMzg1MGI4MDI3M2M2MWEwNmExMTcwMmMzOGI4NjhjYzk4NmU4ZDk4MWI0YTYzZDIzNTZmMg==
The public key, and the signature are sent in the X-CT-Authorization header.
<!--?php$curl = curl_init();curl_setopt_array($curl, array( CURLOPT_URL =--> "https://api.crowdtwist.com/v2/users/11116703", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_POSTFIELDS => "{\n \"email_address\": \"testing@crowdtwist.com\",\n \"postal_code\": \"10010\",\n \"last_name\": \"test\"\n}", CURLOPT_HTTPHEADER => array( "cache-control: no-cache", "content-type: application/json", "x-ct-authorization: CTApiV2Auth publickey:signature", "x-ct-timestamp: 1505325876486" ),));$response = curl_exec($curl);$err = curl_error($curl);curl_close($curl);if ($err) { echo "cURL Error #:" . $err;} else { echo $response;}
<!--?php$curl = curl_init();curl_setopt_array($curl, array( CURLOPT_URL =--> "https://api.crowdtwist.com/v2/users/11116703", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_POSTFIELDS => "{\n \"email_address\": \"testing@crowdtwist.com\",\n \"postal_code\": \"10010\",\n \"last_name\": \"test\"\n}", CURLOPT_HTTPHEADER => array( "cache-control: no-cache", "content-type: application/json", "x-ct-authorization: CTApiV2Auth publickey:signature", "x-ct-timestamp: 1505325876486" ),));$response = curl_exec($curl);$err = curl_error($curl);curl_close($curl);if ($err) { echo "cURL Error #:" . $err;} else { echo $response;} Sample Authentication Request
Following similar steps as seen above, a sample Authentication request will appear as follows:
POST https://api.crowdtwist.com/v2/user_auth_sign_inHeadersX-CT-Authorization CTApiV2Auth ABCl3y7r0s5ukCXz5lCJOCrTZ427pjp5: YTUyNDU0MTc1YTg1MTZiN2IyMTc2Mzc5ZTA2YTlkN2Q1ZmEwNzAyYzM4ZmM0NWUzZWY2M2JmMWE1NzQ2YzBjMA==Content-Type application/jsonX-CT-Timestamp 1437604131Body{ "redirect" : "http://test-rewards.crowdtwist.com", "username" : "AliceTwist", "verified" : 1}
POST https://api.crowdtwist.com/v2/user_auth_sign_inHeadersX-CT-Authorization CTApiV2Auth ABCl3y7r0s5ukCXz5lCJOCrTZ427pjp5: YTUyNDU0MTc1YTg1MTZiN2IyMTc2Mzc5ZTA2YTlkN2Q1ZmEwNzAyYzM4ZmM0NWUzZWY2M2JmMWE1NzQ2YzBjMA==Content-Type application/jsonX-CT-Timestamp 1437604131 Body{ "redirect" : "http://test-rewards.crowdtwist.com", "username" : "AliceTwist", "verified" : 1} First, to generate the StringToSign the above request body will be MD5 hashed to produce the below value:
- de26bd80b53577dbe47738239d23f0b3
This value will then be added the StringToSign which will have the below format
POST
de26bd80b53577dbe47738239d23f0b3
application/json
1437604131
/v2/user_auth_sign_in
Taking the above StringToSign along with the private key (ABttp1b92Tb65445rmZL835f263n1q4Y) and applying the HMAC-SHA-256 algorithm will result in the below string:
- a52454175a8516b7b2176379e06a9d7d5fa0702c38fc45e3ef63bf1a5746c0c0
Lastly, this value will then need to be Base64 encoded, resulting in the following value:
- YTUyNDU0MTc1YTg1MTZiN2IyMTc2Mzc5ZTA2YTlkN2Q1ZmEwNzAyYzM4ZmM0NWUzZWY2M2JmMWE1NzQ2YzBjMA==
With the signature complete, the request can be sent with the appropriate HMAC Headers and a valid response will be returned.
Sample GET Request
Following similar steps as seen above, a sample GET request will appear as follows:
GET https://api.crowdtwist.com/v2/activitiesHeadersX-CT-Authorization CTApiV2Auth ABCl3y7r0s5ukCXz5lCJOCrTZ427pjp5:YmQ0YTgyY2QzMTlhYmFiZTU3ZDBhODIyMDQ5YWU4OTg1MDI5ZjgyMjM3NTA5ZDNmMDkxYzgyY2JjN2E2OTQ1Yw==X-CT-Timestamp 1437659826
GET https://api.crowdtwist.com/v2/activities HeadersX-CT-Authorization CTApiV2Auth ABCl3y7r0s5ukCXz5lCJOCrTZ427pjp5:YmQ0YTgyY2QzMTlhYmFiZTU3ZDBhODIyMDQ5YWU4OTg1MDI5ZjgyMjM3NTA5ZDNmMDkxYzgyY2JjN2E2OTQ1Yw==X-CT-Timestamp 1437659826
Since there is no request body, the StringToSign value can be immediately generated with the below format:
GET
1437659826
/v2/activities
Applying the HMAC-SHA-256 algorithm with the private key (ABttp1b92Tb65445rmZL835f263n1q4Y) and the string to sign results in the below string:
- bd4a82cd319ababe57d0a822049ae8985029f82237509d3f091c82cbc7a6945c
Next, this hash is then Base64 encoded, which results in the following value:
- YmQ0YTgyY2QzMTlhYmFiZTU3ZDBhODIyMDQ5YWU4OTg1MDI5ZjgyMjM3NTA5ZDNmMDkxYzgyY2JjN2E2OTQ1Yw==
This value is then placed in the X-CT-Authorization header as the [signature] to receive a valid response.
Error Conditions
Below are the possible HMAC specific error conditions; all responses are in JSON format.
Invalid HMAC header – Possibly due to missing http header or http header in unexpected format.
Response
{ "error": "hmac_verification_failed", "message": "Invalid hmac header."}
{ "error": "hmac_verification_failed", "message": "Invalid hmac header."} HMAC signature mismatch – The client generated hash value and the server generated hash value does not match.
Response
{ "error": "hmac_verification_failed", "message": "Hmac signature mismatch."}
{ "error": "hmac_verification_failed", "message": "Hmac signature mismatch."} HMAC timestamp expired – The client generated hash value and the server generated hash value matches, but the timestamp exceeded the acceptable limit. The timestamp must be within 15 minutes of the current time.
Response
{ "error": "hmac_verification_failed", "message": "Hmac timestamp expired."}
{ "error": "hmac_verification_failed", "message": "Hmac timestamp expired."} 