Authorization

HMAC-SHA256 Authentication

All authenticated endpoints use HMAC-SHA256 signature verification. Each request must include three custom headers that prove your identity and protect against replay attacks.

Required Headers

Header	Description
`X-Public-Key`	Your business public key. Identifies which business is making the request.
`X-Timestamp`	Current Unix timestamp in seconds. Requests older than 5 minutes are rejected.
`X-Signature`	HMAC-SHA256 signature of the request (see below).

Generating the Signature

The signature is an HMAC-SHA256 hash of a signing string, using your private key as the secret.

Signing string format:
{timestamp}\n{METHOD}\n{path}\n{body}

Component	Description	Example
`timestamp`	Same value sent in `X-Timestamp`	`1709836800`
`METHOD`	Uppercase HTTP method	`GET`
`path`	Full URI including query string, with leading `/`	`/api/v1/events?count=5`
`body`	Raw request body (empty string for GET)	(empty)

Components are joined by literal newline characters (\n).

Authentication Errors

Status	Code	Description
`401`	`MISSING_CREDENTIALS`	One or more required headers are missing.
`401`	`REQUEST_EXPIRED`	`X-Timestamp` is more than 5 minutes from server time.
`401`	`INVALID_CREDENTIALS`	Public key not found, or signature does not match.
`403`	`ACCOUNT_INACTIVE`	Business account exists but is not active.

Example Code

PUBLIC_KEY="your-public-key"
PRIVATE_KEY="your-private-key"
TIMESTAMP=$(date +%s)
PATH_URI="/api/v1/events?count=5"

# Build signing string: timestamp\nMETHOD\npath\nbody
SIGNATURE=$(printf '%s\n%s\n%s\n' "$TIMESTAMP" "GET" "$PATH_URI" \
  | openssl dgst -sha256 -hmac "$PRIVATE_KEY" | awk '{print $2}')

curl -H "X-Public-Key: $PUBLIC_KEY" \
     -H "X-Timestamp: $TIMESTAMP" \
     -H "X-Signature: $SIGNATURE" \
     "https://backend.localbusiness.pro$PATH_URI"