Skip to main content

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 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 /graphql 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
{
    "query": "mutation CreateOrder($orderItems: [OrderItemInput]) { orderCreate(orderItems: $orderItems) { id } }",
    "variables": {
        "orderItems": [{ "amountToOrder": 1, "bundleId": "e3ac7f3a-a117-46d7-a5f0-232fbc7cfe38" }]
    }
}

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-SHA1 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, "bundleId": "e3ac7f3a-a117-46d7-a5f0-232fbc7cfe38" }]
    }
}
Last updated on