Fivaldi Customer API

• REST API, communicates with the HTTPS protocol
• Responses are in JSON format
• The API can be used by registered Fivaldi partner users
  • See sections 2.5, 3, 3.1 and 3.2 in this guide (only in Finnish for now)
• A Fivaldi customer defines what data a Fivaldi partner can access

Authentication

A Fivaldi partner user will receive a partner id and a shared partner secret. The secret will be known to both the partner and Fivaldi, and must be kept safe. If the secret is leaked, contact Fivaldi development immediately.

Every request must be signed with a message authentication code (MAC) composed of different values extracted from the request. The different values are combined to a string, separating them by a linefeed (unicode code point U+000A). The resulting string is then hashed with HMAC SHA256, using the partner secret as a key. The resulting hash is Base64 encoded and added to the Authorization header of each request, using "Fivaldi" as the authentication type.

Mandatory headers

• X-Fivaldi-Timestamp (Unix time, seconds since the Epoch)
• X-Fivaldi-Partner (partner id)
• Authorization (contains the Fivaldi auth type and signature described below)

Components of the signature

1. HTTP method

GET, POST, PUT, PATCH, DELETE

2. MD5 hash of the request body

Substitute with an empty string if the request does not have a body.

3. Content type

Value of the Content-Type header. Substitute with an empty string if the request does not have a body.

4. Headers

All headers which start with "X-Fivaldi". This includes atleast "X-Fivaldi-Timestamp" and "X-Fivaldi-Partner", but specific endpoints might require additional headers. The key must be lowercase, the key and value separated by ":", with no whitespace around it.

5. Request URL path

Path must contain everything from the first "/" up to the query string, not including the "?".

6. Query string

Everything from the query string, except the prepending "?". Do not include if no query string is needed for the request.

Pseudocode for creating a request MAC

LF = unicode code point U+000A

stringToSign = 
    httpMethod + LF +
    bodyMD5 + LF +
    contentType + LF

for each header in headers loop
    stringToSign += headerKey + ':' headerValue + LF
end loop

stringToSign +=    path

if queryString exists then
    stringToSign += LF + queryString
end if

signature = base64(hmacSHA256(utf8EncodingOf(partnerSecret), utf8EncodingOf(stringToSign)))

Authorization header = "Fivaldi "  + signature

Testing with Postman

Included here is a Postman collection which contains code for creating the correct authentication headers and an endpoint for testing it.

Remember to add your partner id and partner secret here.