HTTP Signature

Description

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:

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

🚧 Important

Signature, digest (if a POST, PUT or PATCH), date and x-request-id headers are optional in SANDBOX environment but mandatory when calling the PRODUCTION one.

💡 Note

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

Process

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

NameDescriptionExample
(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

(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:

keyId=`app_id`,
algorithm=rsa-sha256,
headers=(request-target) date x-request-id,
signature=`signature`

For POST & PATCH requests:

keyId=`app_id`,
algorithm=rsa-sha256,
headers=(request-target) date digest x-request-id,
signature=`signature`

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=="