Overview

Authorization to our backend is managed through API keys. Each main account is provided with a secret key and a public key, generated by our customer service team. In the future, we may provide a UI for the main account to generate and invalidate these keys.

HTTP Request Headers

Required Headers

Header	Description	Mandatory For
`x-api-key`	Public API key of the master account.	All requests
`x-api-account-id`	Account ID (master or sub-account). If acting on behalf of a sub-account, include its ID.	All requests
`x-api-signature`	SHA-256 signature of the JSON payload and private key. Required only for POST and PUT requests.	POST and PUT requests
`x-idempotency-key`	A unique client-generated identifier for idempotency. Prevents duplicate requests if the same ID is used more than once. Example: 123e4567-e89b-12d3-a456-426614174000	POST and PUT requests.

Signature Header: `x-api-signature`

For POST and PUT requests, the x-api-signature ensures the payload's integrity and authenticity.

How to Generate a Signature

Concatenate the stringified JSON payload and the secret key.
Convert the concatenated string into a UTF-8 byte array.
Compute the SHA-256 hash of the byte array.
Convert the hash into a hexadecimal string (lowercase). This becomes the value for x-api-signature.

Example of Signature Generation

Field	Value
Private (Secret) Key	`DOSsQcRP9NnzFJxVQL4W`
Stringified JSON Payload	`{"accountType":"PERSONAL","firstName":"Jon","lastName":"Snow","country":"AU","externalId":"01946d9e-6c36-7000-8098-57c88fc5594e"}`
Concatenated String	`{"accountType":"PERSONAL","firstName":"Jon","lastName":"Snow","country":"AU","externalId":"01946d9e-6c36-7000-8098-57c88fc5594e"}DOSsQcRP9NnzFJxVQL4W`
Converted to byte array	[123, 34, 97, 99, 99, 111, 117, 110, 116, 84, 121, 112, 101, 34, 58, 34, 80, 69, 82, 83, 79, 78, 65, 76, 34, 44, 34, 102, 105, 114, 115, 116, 78, 97, 109, 101, 34, 58, 34, 74, 111, 110, 34, 44, 34, 108, 97, 115, 116, 78, 97, 109, 101, 34, 58, 34, 83, 110, 111, 119, 34, 44, 34, 99, 111, 117, 110, 116, 114, 121, 34, 58, 34, 65, 85, 34, 44, 34, 101, 120, 116, 101, 114, 110, 97, 108, 73, 100, 34, 58, 34, 48, 49, 57, 52, 54, 100, 57, 101, 45, 54, 99, 51, 54, 45, 55, 48, 48, 48, 45, 56, 48, 57, 56, 45, 53, 55, 99, 56, 56, 102, 99, 53, 53, 57, 52, 101, 34, 125, 68, 79, 83, 115, 81, 99, 82, 80, 57, 78, 110, 122, 70, 74, 120, 86, 81, 76, 52, 87]
Calculate the SHA-256 digest	`[144, 165, 96, 144, 15, 36, 234, 158, 192, 251, 176, 233, 67, 190, 83, 61, 85, 106, 179, 165, 161, 219, 213, 91, 157, 102, 84, 159, 226, 56, 220, 240]`
Get sign value	`90a560900f24ea9ec0fbb0e943be533d556ab3a5a1dbd55b9d66549fe238dcf0`

Step-by-Step Example

Concatenation

Combine the JSON payload and secret key:

{"accountType":"PERSONAL","firstName":"Jon","lastName":"Snow","country":"AU","externalId":"01946d9e-6c36-7000-8098-57c88fc5594e"}DOSsQcRP9NnzFJxVQL4W

UTF-8 Conversion

Convert the string into a byte array:

[123, 34, 97, 99, 99, 111, 117, 110, 116, 84, 121, 112, 101, 34, 58, 34, 80, 69, 82, 83, 79, 78, 65, 76, 34, 44, 34, 102, 105, 114, 115, 116, 78, 97, 109, 101, 34, 58, 34, 74, 111, 110, 34, 44, 34, 108, 97, 115, 116, 78, 97, 109, 101, 34, 58, 34, 83, 110, 111, 119, 34, 44, 34, 99, 111, 117, 110, 116, 114, 121, 34, 58, 34, 65, 85, 34, 44, 34, 101, 120, 116, 101, 114, 110, 97, 108, 73, 100, 34, 58, 34, 48, 49, 57, 52, 54, 100, 57, 101, 45, 54, 99, 51, 54, 45, 55, 48, 48, 48, 45, 56, 48, 57, 56, 45, 53, 55, 99, 56, 56, 102, 99, 53, 53, 57, 52, 101, 34, 125, 68, 79, 83, 115, 81, 99, 82, 80, 57, 78, 110, 122, 70, 74, 120, 86, 81, 76, 52, 87]

Compute SHA-256 Digest

Calculate the SHA-256 digest from the byte array and return the value as a byte array:

[144, 165, 96, 144, 15, 36, 234, 158, 192, 251, 176, 233, 67, 190, 83, 61, 85, 106, 179, 165, 161, 219, 213, 91, 157, 102, 84, 159, 226, 56, 220, 240]

Hexadecimal Conversion

Convert an array of bytes into an array of characters representing the hexadecimal values of each byte in order in lowercase. That's your sign value:

90a560900f24ea9ec0fbb0e943be533d556ab3a5a1dbd55b9d66549fe238dcf0