Key lifecycle & security

Storage rules

• The HMAC secret goes in your secrets manager only — never in code, config repos, logs, or client-side apps. It is shown exactly once at issuance.
• The apiKeyId is public-safe (it identifies, the signature proves).
• Server-side only: signing must never happen in a browser or mobile app you ship to end users.

Rotation (zero-downtime)

Request a rotation any time (scheduled hygiene or suspected exposure):

1. We issue a new secret; the old one keeps working.
2. You deploy the new secret at your pace and confirm.
3. We retire the old secret. Total downtime: zero.

During the grace window both secrets sign valid requests, and our webhooks are signed with the new (active) secret.

Revocation

If a key is compromised, revocation takes effect within 60 seconds of the request. Your integration halts until a replacement is issued — prefer rotation unless the secret is definitely exposed.

Automatic protections on our side

Protection	Behaviour
Signature-failure lockout	≥10 invalid signatures in 5 min → key soft-locked 15 min (429 AUTH_LOCKED), both sides alerted. A leaked key ID without the secret is useless and noisy.
Environment locking	Test keys rejected in production and vice versa — misconfiguration fails loudly, immediately.
Replay window	Requests older/newer than 5 minutes are rejected.
IP allowlist (optional)	Keys restricted to your registered egress IPs.
Audit trail	Every request is logged (metadata only, 90 days) — usable for your own incident forensics on request.