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:

Name	Required	Description	Example
date	Always	RFC 2822 formatted date	Wed, 26 Feb 2020 17:29:51 GMT
digest	POST PUT PATCH	Hashed payload	SHA-256=cjuagrzhZ8joOWLlQCCe5co30bRISL1VIWNq99da+hM=
x-request-id	Always	UUID v4 identifier	123e4567-e89b-12d3-a456-42665544
Signature	Always	HTTP calculated signature	keyId="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

Name	Description	Example
(request-target)	Method and pathname of an URL	get /ais/v1/customer/123/accounts
date	An RFC 2822 formatted date	Wed, 26 Feb 2020 17:29:51 GMT
digest	The SHA-256 digest of the body as described in point 1	SHA-256=cjuagrzhZ8joOWLlQCCe5co30bRISL1VIWNq99da+hM=
x-request-id	An UUID v4 formatted unique value	123e4567-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=="