API Reference

Processing Response Header and Signature

The pseudocode below illustrates construction of the HTTP "X-Server-Authorization-HMAC-SHA256" header and signature for all non-HEAD requests:

// Create the canonical representation of the response payload
CanonicalContent = Canonicalize( Response-Body )

// Generate the hash of the response body
HashedContent = Base64( SHA256 ( CanonicalContent ) )

// Generate the string to sign
ResponseStringToSign = Nonce + "\n" +
    X-Authorization-Timestamp + "\n" +
    HashedContent

// Sign the string with the same secret that was used to sign the request
// The result is the X-Server-Authorization-HMAC-SHA256 response header
HMACServerAuthorization = Base64( HMAC-SHA256 ( SecretKey, UTF-8-Encoding-Of( ResponseStringToSign ) ) )

Clients must validate responses using the signing algorithm above.

HMAC Server Authorization

The server authorization is a base64 encoded binary HMAC-SHA256 digest generated from the following parts:

  • SecretKey: The API key's shared secret\
  • ResponseStringToSign: The string being signed as described below

Response String to Sign

The response signature base string is a concatenated string generated from the following parts:

  • Nonce: The nonce that was sent in the Authorization header.
  • X-Authorization-Timestamp: The timestamp that was sent in the X-Authorization-Timestamp header
  • HashedContent: The base64 encoded SHA-256 digest of the raw body of the HTTP response
    • When calculating the hash the JSON response body must be formatted into a canonical form using the RFC 8785 scheme. Libraries exist in most popular programming languages, see cyberphone/json-canonicalization for examples.