Authentication

Authentication and Authorisation for the active user on the API is done through the use of HTTP Headers containing the API Key to identify the user and a request signature, signed using the API Secret. To send requests, one must perform a login request first to acquire a valid cookie to use with subsequent requests.

Obtaining API Keys

With an active account, log in to your account and navigate to the API Keys tab on the side navigation. Once on the API Keys menu, click Create an API Key if one is not already created.

Once you have the API Key and Secret, you can now use them to access the API. The API Secret will be shown only once and then never again, if you lose the API Secret, you will need to log in again and rotate the API Secret. Therefore, it is recommended to make sure you copy your API Secret and keep it in a safe place.

Constructing Headers

To access the API, a few HTTP headers need to be present in order to be properly authenticated. Those headers are:

Header	Description
X-Api-Key	This is the API Key obtained in the previous step.
X-Api-Secret	This is the API Secret Key also obtained in the previous step and is shown once on the portal.
X-Api-Signature	This is the Base64 encoded HMACSHA256 signature, signed using the API Secret, of the JSON request body for all requests with a body. Not required for `GET` requests.
X-Application	The name of the application that uniquely identifies it (provided by Fiscal Harmony).
X-App-Station	The unique identifier for the workstation/till/operator/station/user using the third party application. The third party using this API must be able to uniquely identify each operator for audit purposes. This value should not change once set.
X-App-Version	The version of the application (provided by Fiscal Harmony).

The X-Api-Signature is constructed by hashing the body and the secret key together and then encrypting it. You may use the following code to perform that function:
C#

NodeJS

import crypto from 'crypto-js';

const hashBytes = crypto.HmacSHA256(YourBody, YourSecretKey);
const signature = crypto.enc.Base64.stringify(hashBytes);

The X-App-Station header is mandatory, therefore provide it to ensure that your API connections keep working without needing to re-develop your integration. The value in this header must be unique for each user or physical device operating your application.

Prescript for Postman and Apidog

If you are using Postman for testing the API, you may use the prescript below to handle requests. This prescript works on Apidog as well, however will only work when you Run in Apidog .

var body = pm.request.body.raw;
var key = pm.environment.get("X-Api-Key");
var secretKey = pm.environment.get("X-Api-Secret");
var hashBytes = require('crypto-js').HmacSHA256(body, secretKey);
var hashBase64 = require('crypto-js').enc.Base64.stringify(hashBytes);
pm.request.headers.add({
    key: "X-Api-Signature",
    value: hashBase64
});

pm.request.headers.add({
    key: "X-Api-Key",
    value: key
});

pm.request.headers.add({
    key: "X-Application",
    value: pm.environment.get("X-Application")
});

pm.request.headers.add({
    key: "X-App-Station",
    value: pm.environment.get("X-App-Station")
});

pm.request.headers.add({
    key: "X-App-Version",
    value: pm.environment.get("X-App-Version")
});

pm.request.headers.add({
    key: "X-Client-Count",
    value: pm.environment.get("X-Client-Count")
});

Authentication

Authentication#

Obtaining API Keys#

Constructing Headers#

Prescript for Postman and Apidog#

Authentication

Obtaining API Keys

Constructing Headers

Prescript for Postman and Apidog