Guide

Rotate keys and secrets

Replace an API key or a webhook signing secret without dropping requests or events.

API keys#

Two keys can be active at once, so a key rotation has no gap.

1. An organization admin creates a new key with the same scopes (Settings → Developers → API keys).
2. You deploy it everywhere the old key is used.
3. Once the new key shows recent use and the old one doesn't, the admin revokes the old key.

Webhook signing secrets#

POST /webhook-endpoints/{id}/rotate-secret, or Rotate in the app, returns a new secret. The old secret stops working at once: from then on, Flux signs every delivery, including retries, with the new secret only.

1. Make your verifier accept a list of secrets, so you can add the new one without removing the old.
2. Rotate, and add the new secret to the list straight away.
3. Once deliveries verify with the new secret, remove the old one.

// FLUX_WEBHOOK_SECRETS="whsec_new,whsec_old" during a rotation, then just the new one.
const secrets = process.env.FLUX_WEBHOOK_SECRETS.split(",").map((s) => s.trim()).filter(Boolean);
const valid = secrets.some((secret) => verifyFluxSignature(secret, req.get("Flux-Signature"), req.body));

# FLUX_WEBHOOK_SECRETS="whsec_new,whsec_old" during a rotation, then just the new one.
secrets = [s.strip() for s in os.environ["FLUX_WEBHOOK_SECRETS"].split(",") if s.strip()]
valid = any(verify_flux_signature(s, request.headers.get("Flux-Signature"), raw) for s in secrets)

Deliveries that fail verification in the gap between steps 2 and 3 aren't lost. Your endpoint returns 400, and Flux retries them a minute later, then on its retry schedule.