Authentication

This section covers the different authentication methods supported by the Algbra Labs API platform

HMAC Signing

HMAC (Hash-based Message Authentication Code) signing is a method of authenticating REST API requests. HMAC involves using a secret key and a hashing algorithm (ie. hmac-sha1) to create a digital signature of the request. The signature is then included in the request headers or parameters, allowing the server to verify that the request was indeed sent by the authorized user and has not been tampered with.

To create the digital signature, the client application uses a combination of the request data payload and a secret key known only to the client and the server. The hashing algorithm is applied to this combination of data and secret key to produce the digital signature.

When our platform receives the request, it applies the same hashing algorithm and secret key to the request data to generate its own digital signature. It then compares its signature to the one included in the request to verify the authenticity and integrity of the request. If the two signatures match, the request is deemed authentic and is processed by the server.

HMAC signing provides an additional layer of security for REST APIs by ensuring that only authorized users can access the API and that requests have not been tampered with during transmission.

Signature Payload

For each request, you need to provide the following headers:

Header	Value
Authorization	Header contains signature, keyId, alghoritm, headers used in signature and encoded signature.
Date	HTTP-date header as specified in RFC 7231
x-alg-nonce	Unique value that represents an individual operation.

Signature payload should contain, date and nonce headers as detailed below.

Date Header

The HMAC calculation above uses a date/time value and also implements the recommended clock-skew from the HMAC specification to prevent against replay attacks. It is therefore essential that the sending system has an accurate time (e.g. synchronised with NTP), any significant time error may cause the request to be rejected.

All time values are sent in UTC/GMT, so you should ensure this still continues to send the correct UTC/GMT time if your sending system is subject to changes for daylight savings.

Nonce Header

The previous HMAC calculation uses a nonce value. This value should be set and be unique per distinct api request/operation that you send to our system (see below for limited exceptions). This is used in conjunction with the date-time to prevent replay attacks and detect duplicate messages.

A nonce should be re-used only if you wish to retry the same request in certain conditions. If the same request content is received with a new nonce, it will be treated as a separate request and may be executed again. Therefore if you wish to re-send a POST request (perhaps because the previous one errored) you need to understand the status of the previous request and that it has not been processed before doing this.