Request signing (HMAC)

When the gateway forwards a request to your service backend, it adds HMAC-signed headers so you can verify the request came from the platform. When you call the usage service (report, progress, completion), you sign the body with the service secret. The full HMAC specification and test vectors live in the SDK monorepo (tollara-sdk); this page gives a high-level overview.

Headers from gateway to backend

The gateway sends at least:

  • X-Tollara-Signature — HMAC-SHA256 of a canonical string (see below), Base64-encoded
  • X-Tollara-Timestamp — Unix epoch seconds as a numeric string
  • X-Tollara-User-ID, X-Tollara-Plan, optional X-Tollara-Roles (comma-separated when present)
  • X-Tollara-Signing-Version — 2 for the current HMAC user-context schema (no quota in signed material)
  • X-Tollara-Subscription-Active — true or false (always present)
  • X-Tollara-Billing-Model, X-Tollara-Measurement-Type, X-Tollara-Unit-Label — optional; omitted for the developer path with no subscriber product (same snapshot as validate service key)

Canonical string (v2): Concatenate, with no separators between parts: the raw request body (empty string if none), the timestamp digits from the header, then a user context that starts with literal 2 (schema version), then userId (or empty), plan (or empty), comma-joined roles if any, subscriptionActive as true or false, then billing model, measurement type, and unit label (each empty string when absent). There is no quota segment. HMAC-SHA256 with the service secret and compare (constant-time) to X-Tollara-Signature. For pre-flight numbers (credits, caps), use core usage estimate APIs, not headers.

Use constant-time comparison. Optionally enforce a timestamp window (e.g. ±5 minutes) to limit replay. The SDK implements this; the tollara-sdk repo has the full spec, test vectors, and reference alignment with platform code.

Outbound (report, progress, completion)

When you POST to the usage service (report, progress, or completion), you build a canonical string (body + timestamp), compute HMAC-SHA256 with the service secret, Base64-encode, and send it in X-Tollara-Signature with X-Tollara-Timestamp. The SDK handles this; for a full spec and test vectors, see the tollara-sdk repo (e.g. docs/hmac-spec.md).

Use the SDK overview and the SDK repo for verify/sign APIs and examples.