Authenticate with the Fipto API

This guide is the friendly walkthrough version of the reference page. If you only want the strict spec, read that page instead.

The Fipto API is authenticated with RSA-SHA256 HTTP Signatures (hs2019). You generate an RSA key pair, send Fipto your public key, and from then on every request is signed locally with your private key. There are no shared secrets to rotate and no bearer tokens to leak.

Quick facts

• Algorithm: RSA-SHA256, declared as hs2019
• Key size: 2048-bit
• Required headers (all): Host, Date, Signature
• Required headers (POST/PUT/PATCH): plus Content-Type and Digest
• Date window: values are expected to be earlier than the present time, but not
  earlier than 1 minute.

Generate Private and Public Key

Generate a 2048-bit RSA private key and the matching public key. Keep private-key.pem strictly secret.

##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

In the Fipto web application, go to Settings > API integrations, click Create integration and upload the public key file (public-key.pem in the example above) or paste its content. Once the integration is created, its Key ID is your api key (referred as keyId in documentation).

What gets signed

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

Frequently asked questions

Does Fipto use API keys or signatures?

Signatures. Specifically, RSA-SHA256 HTTP Signatures (hs2019). There is no bearer token.

Can I use the same key pair in demo and production?

Yes, but you'll receive two distinct API user UUIDs, one per environment.

What if my server clock drifts?

Requests where the Date header is more than a minute off will be rejected. Run NTP.

Where do I send my public key?

Email [email protected] or contact your Fipto account manager.