🔐 Authentication: HMAC Guide

💡

This guide explains how to authenticate and call HaloSync APIs using HMAC-based signatures.

1. Purpose

HaloSync uses HMAC authentication to ensure that each API request is signed securely.
The signature combines a date header, the request body digest, and your secret key.

2. Method Overview

HMAC Signature and Date + Body Digest must be included in request headers.

Supported algorithm: HMAC-SHA512.

3. Header Construction

Step 1: Date Header

Generate a timestamp in GMT (RFC1123 format).
Example:

Tue, 26 Aug 2025 10:12:34 GMT

Step 2: Digest Header

Hash the request body with SHA-512 and encode it in Base64.

SHA-512=${bodyHash}

Step 3: Authorization Header

Build the Authorization header string:

hmac username="${keyId}", algorithm="hmac-sha512", headers="x-date digest", signature="${signature}"

keyId → Provided user name

signature → HMAC-SHA512 over (x-date + digest) using your secret key (Base64)

Step 4: Final Headers

Example:

4. Constraints

Clock Skew: Requests are valid within ±120 seconds of the server time.

Make sure client systems sync with NTP to avoid time drift.

5. Sample Codes

Node.js

Python

Postman / Apidog Script

Java

🔐 Authentication: HMAC Guide

1. Purpose#

2. Method Overview#

3. Header Construction#

4. Constraints#

5. Sample Codes#

1. Purpose

2. Method Overview

3. Header Construction

4. Constraints

5. Sample Codes