Getting started

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

Generate Private and Public Key

Private Key

openssl genrsa -out private-key.rsa 2048
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.rsa -out private-key.pem

Public Key

openssl rsa -in private-key.rsa -pubout -out public-key.pem

HTTP request signing

All authenticated requests must include the following headers:

Host: target host of the request
- Demo host : api.demo.fipto.tech
- Production host : api.fipto.app
Date: time of creation of the request, in RFC1123 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=<hash>

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

Requests are signed and verified using the HTTP signatures protocol. Libraries exist in different languages for building signed requests using that protocol. We focus here on our specific requirements.

We expect the authentication data to be present in a Signature header.

The "signing string" itself should contain all the headers mentioned in the previous section, as well as the (request-target) pseudo-header (see section 2.3).

For example, the signing string of a POST request would look like:

(request-target): post /companies/c240e5bf-863e-4f44-91aa-cc74a8b3303f/wallets
host: api.demo.fipto.tech
date: Fri, 24 Jan 2025 08:56:30 GMT
content-type: application/json
digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=

That string must then be signed using the RSA-256 algorithm, encoded in base64 and included in the signature field of the header.

The following constraints apply to other fields:

the keyId field must contain the UUID of your API user
the headers field must contain (request-target) as well as all the headers mentioned above
the algorithm field must be "hs2019" (or its synonym "rsa-sha256")

The final header of a POST request should look like:

Signature: keyId="<uuid of your api user>",algorithm="hs2019",headers="(request-target) host date content-type digest",signature="<base64-encoded signature>"