HTTP Signature


Some APIs required HTTP signature for reinforced security. Your app_private_key, as defined in the console, will be required for this. The HTTP header follows the signing HTTP Messages IETF standard, with the following particularities:

  • the keyId value is your app_id
  • the only algorithm currently supported is rsa-sha256

All endpoints requesting HTTP signature will require following additional header parameters:

dateAlwaysRFC 2822 formatted dateWed, 26 Feb 2020 17:29:51 GMT
Hashed payloadSHA-256=cjuagrzhZ8joOWLlQCCe5co30bRISL1VIWNq99da+hM=
x-request-idAlwaysUUID v4 identifier123e4567-e89b-12d3-a456-42665544
SignatureAlwaysHTTP calculated signaturekeyId="0354d723-d8d3-469a-8926-4f3f18b2c416",
headers="(request-target) date x-request-id",

💡 Note

An interactive HTTP Signature guide has been created to help you through the process of creating the Digest and Signature headers.


1. Build the message digest

The digest is a SHA-256 hash of the payload encoded into base64, and concatenated with a "SHA-256=" prefix.

Digest function
digest = "SHA-256=" + base64( SHA256( body ) )

💡 Note

Make sure your body is encoded into a UTF8 with unescaped unicode to avoid bad surprises in case accents or other special characters are included in the body.

2. Create the signing parameters

(request-target)Method and pathname of an URLget /ais/v1/customer/123/accounts
dateAn RFC 2822 formatted dateWed, 26 Feb 2020 17:29:51 GMT
digestThe SHA-256 digest of the body as described in point 1SHA-256=cjuagrzhZ8joOWLlQCCe5co30bRISL1VIWNq99da+hM=
x-request-idAn UUID v4 formatted unique value123e4567-e89b-12d3-a456-42665544

3. Build the signing string

For GET & DELETE requests, use:

  • (request-target)
  • date
  • x-request-id

For POST & PATCH requests, use:

  • (request-target)
  • date
  • digest
  • x-request-id

Concatenate all fields in one string like below:
(request-target): get /ais/v1/customer/123/accounts?querystring=true\n
date: Wed, 26 Feb 2020 17:29:51 GMT\n
x-request-id: 123e4567-e89b-12d3-a456-42665544

💡 Note

Make sure the name of each parameter is lower cased (no the value), there is a ": " between the name and the value, and a return character "\n" at the end of each line except the last one. For the (request-target) include query params to the pathname.

4. Encrypt the signing string

Use your private key and encode it into base64:

Signing function
signature = base64( RSA-SHA256( signing string ) )

5. Create the signature string

Concatenate all fields separating them by a comma (",").

For GET & DELETE requests:

headers=(request-target) date x-request-id,

For POST & PATCH requests:

headers=(request-target) date digest x-request-id,

This results to an HTTP signature with the following structure:

keyId="0354d723-d8d3-469a-8926-4f3f18b2c416",algorithm="rsa-sha256",headers="(request-target) date digest x-request-id",signature="eyvAyh5kuqifP8vkUy5KBWPgtQAurB7xMeC6T/KGJQm2JA=="