Payload Signing

This section covers the details of authentication mechanisms required by the Algbra Labs API platform.

Request Signing

We require you to sign all API requests using the approach detailed below. 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, your client application should use a combination of the request data payload parameter.

When our platform receives the request, it verifies the signature using your public key to verify the authenticity and integrity of the request. We won't process your request if the signature verification fails.

Signature Payload

For each request, you need to combine following fields as JSON formatted string and sign with your private key. The resulting signature must be added to your request with x-alg-signatureheader.

Signing Payload Object Fields

Field	Value
url	URL of the API endpoint excluding base URL (eg. `/v1/resource/path?q=xyz`) This should contain all URL params if you are executing GET operations.
method	HTTP method of the API. ie. GET, POST, PUT, PATCH, DELETE
headers	Object containing important header values. Please refer to table below detailing subfields required.
body	Raw HTTP request body, or empty string for GET requests or similar.

Below you can find the required fields of the headers object of the signature payload.

Headers Object Fields for Signature Payload

Field	Value
authorization	Your API Token
date	HTTP-date header as specified in RFC 7231
x-alg-nonce	Unique value that represents an individual operation. This is different than idempotency key required for certain API operations.

Request Headers

Below you can find the list of required request headers per each individual request.

Header	Key
Authorization	authorization
Signature	x-alg-signature
Nonce	x-alg-nonce
Date	date

Authorization Header

Value containing your API Token.

Signature Header

Digital signature of your signed payload explanied above.

Date Header

The signing approach uses a date/time value and also implements the recommended clock-skew 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

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.

This nonce value is different than the idempotency key required by certain API operations.

A nonce should be re-used only if you wish to retry the same request in certain conditions such as request failures due to connectivity issues. 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.

Testing API Connectivity

Once you complete setting up your authentication prerequisites, you can use Testing API Connectivity method to check if everything works well.