Skip to main content

Rotating and revoking keys

API keys are session-administered: rotation and revocation are driven from the FlowBeacon console or via the session-authenticated /api/v1/keys/* admin endpoints (not /api/public/v1/*). This guide covers the operational moves you'll make most often.

When to use this​

  • Periodic rotation (recommended every 90 days).
  • Suspected key compromise.
  • Employee turnover.
  • Region or environment migration.

Rotation (zero-downtime)​

Rotation creates a replacement key with identical configuration and schedules the old key to expire after a configurable grace period.

POST /api/v1/keys/{key_id}/rotate
Cookie: __Secure-next-auth.session-token=...
Content-Type: application/json

{ "grace_period_hours": 24 }
  • Grace period range: 1–168 hours (default 24h).
  • Both keys authenticate during the grace window.
  • Deploy the new key first; verify; then expire the old.

Playbook​

  1. Click Rotate in Settings → API Keys (or call the endpoint above).
  2. Copy the new raw key from the reveal dialog.
  3. Update your secret store and roll a deploy.
  4. Watch logs for any 401 against the new key. Resolve before the grace period ends.
  5. After verifying production traffic on the new key, you can revoke the old key explicitly if you want to end the grace period early.

Revocation​

DELETE /api/v1/keys/{key_id}
Cookie: __Secure-next-auth.session-token=...
  • Effect: immediate. Subsequent requests with the revoked key return 401 Invalid or expired API key.
  • There is no undo. Recreate the key if needed.
  • Revoking a key does not revoke its already-issued result tokens (single-use, 15-minute TTL — they expire naturally).

What to do if a key leaks​

  1. Rotate the key with a grace period of 1 hour and capture the new value.
  2. Update production with the new key.
  3. Revoke the old key explicitly after confirming the new one is live.
  4. Search internal logs for the leaked key prefix (fb_live_xxxx — the first 12 chars).
  5. Notify security@flowbeacon.ai so the platform team can correlate any anomalous activity on the watermark log.

API key tagging conventions​

Use clear key names:

  • Per environment (make-grid-production, make-grid-staging).
  • Per consumer (zapier-integration, n8n-self-hosted).
  • Per purpose (ci-blueprint-gating).

The key_prefix (first 12 characters) is safe to include in support tickets and dashboards.

Listing keys​

GET /api/v1/keys
Cookie: __Secure-next-auth.session-token=...

Returns metadata only: id, name, key_prefix, permissions, is_active, created_at, expires_at, revoked_at, last_used_at. Never returns the raw key after creation.

Next steps​