API Reference

Generating the Client Request Header and Signature

The pseudo-code below illustrates construction of the HTTP "X-Authorization" header and signature:

// Create the canonical representation of the request payload
CanonicalContent = Canonicalize( Request-Body )

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

Version = "connextor-1.0"

// Metadata describing the key ID, algorithm version and unique request identifier
AuthorizationHeaderParameters = "id=" + URLEncode( AccessKey ) + "&" + 
   "nonce=" + URLEncode( HexV4OfRandomUUID ) + "&" +
   "version=" + URLEncode( Version )

// This is the string that is signed
StringToSign = HTTP-Verb + "\n" +
   Path + "\n" +
   AuthorizationHeaderParameters + "\n" +
   X-Authorization-Timestamp +
   [ "\n" + Content-Type + 
     "\n" + HashedContent, if Content-Length > 0 ]
                
// Generate the signature
HMACSignature = Base64( HMAC-SHA256 ( SecretKey, UTF-8-Encoding-Of( StringToSign ) ) )

// Create the final X-Authorization header
HMACAuthorization = "wpay-http-hmac" + " " +
                "id=" + DoubleQuoteEnclose( URLEncode( AccessKey ) ) + "," +
                "nonce=" + DoubleQuoteEnclose( URLEncode( HexV4OfRandomUUID ) )+ "," +
                "version=" + DoubleQuoteEnclose( URLEncode( Version ) ) + "," +
                "headers=" + DoubleQuoteEnclose( URLEncode( AdditionalSignedHeaderNames ) ) + "," +
                "signature=" + DoubleQuoteEnclose( URLEncode( HMACSignature ) )

"\n" denotes a Unix-style line feed (ASCII code 0x0A).

Secret key and Access Key

The AccessKey is the identifier for the SecretKey used to sign the request.
See the key management APIs for details on how to generate signing keys.

String to Sign

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

  • HTTP-Verb: The uppercase HTTP request method e.g. "GET", "POST"
  • Path: The HTTP request path with leading slash, e.g. /resource/11
  • AuthorizationHeaderParameters: normalized parameters similar to section 9.1.1 of OAuth 1.0a. The parameters are the id, nonce, realm, and version from the Authorization header. Parameters are sorted by name and separated by '&' with name and value separated by =, percent encoded (urlencoded)
  • X-Authorization-Timestamp: The value of the X-Authorization-Timestamp header
  • Content-Type: The lowercase value of the "Content-type" header (or empty string if absent). Omit if Content-Length is 0.
  • HashedContent: The base64 encoded SHA-256 digest of the HTTP request, for POST, PUT, PATCH, DELETE or other requests that may have a body. Omit if Content-Length is 0. This should be identical to the string sent as the X-Authorization-Content-SHA256 header.
    • When calculating the hash the JSON request 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.