Authentication

Getting Started

Before using the API you need to get an API_KEY by sending us an email with your Public Key.

HTTP request signing

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)

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=

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

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

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

where $BODY contains the string representation of the request body.

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.