Service secret rotations

A secret rotation mints a fresh HMAC signing secret for an existing service. The response includes the new signing_secret value once — the same one-time-reveal contract as the original POST /v1/services response.

The previous secret stays valid on the ingest endpoint for the configured grace window (grace_hours, default 168 hours = 7 days) so already-deployed senders can roll over to the new credential incrementally without dropped events.

When to rotate

Rotation is a deployment-roll mechanism, not a panic-rotate. The expected use is "we want to retire an old credential as part of normal hygiene": create the rotation, deploy the new secret to your senders, let traffic migrate, then let the grace window expire.

For a true breach response — when the previous secret must be rejected immediately — pass grace_hours: 0. The next ingest request that arrives signed with the old secret will be rejected at the edge.

Notes

  • Rotations are serialised per service by an advisory lock. Two concurrent POST /secret_rotations calls against the same service will queue, not race.
  • The grace window is observed by the ingest worker, not by this endpoint — any value in [0, 720] (0 hours to 30 days) is accepted.
  • Rotation is owner/admin only — same capability gate as create_service.

Endpoints