API Credentials & Authentication

API Credentials

Before you can pair a terminal or make any API calls, contact mx51 to obtain the following credentials:

🔒

Security requirement

Your API credentials must be kept secure at all times. It must not be visible, configurable, or editable anywhere on your POS UI, and must not be stored in frontend code or disclosed externally.

mx51 will provide a test key for use during development and certification. A live key will be issued separately once your integration is certified.

Authentication

SCI uses different authentication methods for each API.

SCI Pairing API - API key

All requests to the SCI Pairing API use your API Secret Key in the Authorization header:

Authorization: ApiKey [APISecretKey]

Example:

curl --location 'https://sci-pairing-api.integrations.mx51.io/v1/progress-pairing' \
--header 'Authorization: ApiKey pak_xxx==' \
--header 'Content-Type: application/json' \
--data '{"pairing_code": "041234"}'

SCI API - HTTP Message Signatures

All requests to the SCI API are authenticated using HTTP Message Signatures (RFC 9421). Three headers are required:

Step 1 - Generate the Content-Digest (POST/PUT/PATCH only)

Hash the request body using SHA-256 and Base64-encode the result, then wrap it in the required format:

var content_digest = CryptoJS.SHA256(request_body).toString(CryptoJS.enc.Base64)
// Wrap as: sha-256=:[value]:
// e.g. sha-256=:9AmU2hRsZnqEo2HiNTLacLN0fOs8YmDiuX4WYeYWvh0=:

Step 2 - Generate the Signature-Input header

sig1=("@method" "@authority" "@request-target" "content-digest");created=[unix_timestamp];alg="hmac-sha256";keyid="[key_id]"

• key_id — returned as key_id in the POST /v1/progress-pairing response
• unix_timestamp — current Unix timestamp, generated fresh per request (not quoted)
• For GET requests, omit "content-digest" from the component list

Step 3 - Build the signature base

The signature base is a multiline string. For a POST request:

"@method": POST
"@authority": sci-api.<tenant-specific-domain>
"@request-target": /v1/transactions
"content-digest": sha-256=:9AmU2hRsZnqEo2HiNTLacLN0fOs8YmDiuX4WYeYWvh0=:
"@signature-params": ("@method" "@authority" "@request-target" "content-digest");created=1715151961;alg="hmac-sha256";keyid="kid_xxx"

For a GET request:

"@method": GET
"@authority": sci-api.<tenant-specific-domain>
"@request-target": /v1/transactions/30fd4b36-a63a-4552-ad5e-b0a2d5223a56?min_version=2
"@signature-params": ("@method" "@authority" "@request-target");created=1715151961;alg="hmac-sha256";keyid="kid_xxx"

Step 4 - Sign and set the Signature header

Your full Signing Secret is signing_secret_part_a + signing_secret_part_b concatenated. Part B is returned in the POST /v1/progress-pairing response.

var signing_secret = signing_secret_part_a + signing_secret_part_b
var signature = CryptoJS.HmacSHA256(signature_base, signing_secret).toString(CryptoJS.enc.Base64)
// Set header as: Signature: sig1=:[signature]: