Authenticating requests to serverside APIs

Access and Secret keys

The Spiff Commerce API at api.us.spiffcommerce.com can be interacted with via an HTTPS request that has been signed with an integration's access and secret keys. (Non-US users will use make requests to the appropriate subdomain instead e.g. users of the AU system will make requests to api.au.spiffcommerce.com) A request to the API might look like the following:

POST /api/v2/orders HTTP/1.1
Host: api.us.spiffcommerce.com
Date: Mon, 23 Apr 2012 12:45:19 GMT
Authorization: SOA df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Content-Type: application/json

{
    "orderItems": [{ "amountToOrder": 1, "transactionId": "e3ac7f3a-a117-46d7-a5f0-232fbc7cfe38" }]
}

note

This example uses the now-deprecated REST API. Orders should be placed using the GraphQL API, as shown by the example in the application keys section.

To compute the value for the Authorization header, you will need:

The access and secret keys for your integration, found in the hub Methods to perform SHA512 hashing, HMAC hashing and base64 encoding Computing the value for the Authorization header is done with the following pseudocode:

UnsignedString := "${RequestMethod}\n${SHA512(RequestBody)}\n${RequestContentType}\n${RequestDate}\n${RequestPath}"
Signature := HMAC("sha1", UnsignedString, SecretKey)
Authorization := "SOA  ${AccessKey}:${Base64(Signature)}"

In the following PHP example, request_headers is a function that generates the expected headers:

function hex_to_base64($hex) {
    $return = "";
    foreach (str_split($hex, 2) as $pair) {
        $return .= chr(hexdec($pair));
    }
    return base64_encode($return);
}

function auth_header($access_key, $secret_key, $method, $body, $content_type, $date_string, $path) {
    $sha512 = hash("sha512", $body);
    $string_to_sign = $method . "\n" . $sha512 . "\n" . $content_type . "\n" . $date_string . "\n" . $path;
    $signature = hex_to_base64(hash_hmac("sha1", $string_to_sign, $secret_key));
    return 'SOA ' . $access_key . ':' . $signature;
}

function request_headers($access_key, $secret_key, $body, $path) {
    $content_type = 'application/json';
    $date = new DateTime("now", new DateTimeZone("GMT"));
    $date_string = $date->format("D, d M Y H:i:s") . " GMT";
    return array(
        'Authorization' => auth_header($access_key, $secret_key, 'POST', $body, $content_type, $date_string, $path),
        'Content-Type' => $content_type,
        'Date' => $date_string,
    );
}

Application keys

Application keys are provided as a simple alternative to access and secret keys. They are typically used in situations where the integration is not able to keep a secret, such as in a client-side application or a mobile app.

Application keys are managed on the integration page in the hub.

A request to the API might look like the following:

POST /graphql HTTP/1.1
Host: api.us.spiffcommerce.com
Date: Mon, 23 Apr 2012 12:45:19 GMT
Content-Type: application/json
X-Application-Key: VqQ-0+7KRD$ej_WEz60EBCC#L9I3Ybw4

{
    "query": "mutation CreateOrder($orderItems: [OrderItemInput]) { orderCreate(orderItems: $orderItems) { id } }",
    "variables": {
        "orderItems": [{ "amountToOrder": 1, "transactionId": "e3ac7f3a-a117-46d7-a5f0-232fbc7cfe38" }]
    }
}