Authentication

Prerequisites

• Contact us to request access to our demo environment.
• After getting in contact with us, you will need to provide us with a public key to handle your API access.

HTTP signature request

All authenticated requests must include the following headers:

• Host: target host of the request, e.g. "api.fipto.app"
• Date: time of creation of the request, in RFC3339 format
• Signature: signature of the request (see below)

Date values are expected to be earlier than the present time, but not earlier than 1 minute.

In addition, requests with a body (POST, PUT, PATCH) must include:

• Content-Type: MIME type of the body, e.g. "application/json"
• Digest: base64-encoded SHA-256 hash of the body, in the format SHA-256

Digest values must obviously match to the actual hashes of their request bodies. The way of getting the digest is language-dependent but a basic UNIX approach would be as follows.

echo -n $BODY | openssl dgst -sha256 -binary | openssl enc -base64 -A

Signature header

We follow the HTTP signatures protocol when it comes to verifying the signatures of requests. Libraries exist in different languages for building signed requests using that protocol. We focus here on our specific requirements.

The protocol requires a "signature string" to be built from elements of the request. That signature string will then be signed using some algorithm and the resulting signature will be added in a Signature header, along with some properties allowing the receiver to identify which elements of the request were used to sign it, so that a verification can take place.

These requests elements are basically just headers, along with pseudo-headers defined in the specification like (created), (request-target), etc.

We require the signature to include all the headers mentioned in the previous section, as well the (request-target) pseudo-header (see section 2.3).

The signing algorithm must be RSA-256.