Ingest API authentication

The Ingest API uses HMAC-SHA256 to verify requests. You do not send the API secret in the request; you use it to sign the body.

Required headers

• x-app-uuid
  Your application’s UUID (e.g. ef37169d-6a9b-4574-945a-89bbd1a09052). Identifies the app and loads its secret on the server.

• x-signature
  HMAC-SHA256 of the raw request body (bytes) using your app’s API secret, as lowercase hex.

The server looks up the app by x-app-uuid, retrieves the API secret, computes HMAC-SHA256(secret, raw_body) and compares it to x-signature (constant-time). If they do not match, the response is 401 Unauthorized with "Invalid signature". If the app UUID is unknown or inactive, the response is 404 Not Found with "Unknown app_uuid".

How to compute the signature

⚠ The signature must be computed over the exact byte sequence sent in the request body. Changes in whitespace, key order, or encoding will invalidate the signature.

1. Build the JSON body (e.g. with json.dumps(payload, separators=(',', ':')) so it is deterministic).
2. Use the exact bytes you will send as the body (no extra spaces or key order changes).
3. Compute HMAC-SHA256(api_secret, body_bytes).hexdigest() (lowercase hex).
4. Send that value in the x-signature header.

Example (Python):

import hmac
import hashlib
import json

payload = {"event": "page_view", "user_hash": "0" * 64, "customer_org_id": "org_1", "path": "/"}
body = json.dumps(payload, separators=(",", ":"))
signature = hmac.new(api_secret.encode(), body.encode(), hashlib.sha256).hexdigest()
# POST with headers: x-app-uuid, x-signature, Content-Type: application/json; body = body

Where to get credentials

In the SaaS Tracker UI: Settings → Applications → [Your app] → App settings. You will see the ingest URL (e.g. https://receive.saastracker.eu/v1/events), the App UUID, and the API secret (masked after first view; copy when creating or rotating).

Best practices

• Keep the secret safe – do not commit it to source control; use environment variables or a secrets manager.
• One app, one secret – each application has its own UUID and secret for isolation and revocation.
• Rotate if compromised – if the secret may have been exposed, generate a new one in the UI and update your clients.

Next: Event schema or Overview.