Rotate runtime keys through automation

Preview

Replace an environment key without avoidable evaluation downtime.

Runtime-key rotation follows create, store, deploy, verify, then revoke. The Management API can create and revoke server runtime keys but never returns an existing raw secret.

Use overlap for planned rotation. Revoke immediately only when suspected compromise outweighs availability.

Required scopes

Use management:runtime-keys:read to inventory metadata and management:runtime-keys:write to create or revoke. Discovery can also require project and environment read scopes.

The management key and new runtime key are different secrets. Keep both out of command output and logs.

Inventory the old key

Resolve the project ID and environment key through Management reads. List runtime-key metadata and identify the old key by stable ID, name, prefix, scopes, and revocation state.

Do not select a key only by array position or display name. Confirm it belongs to the intended project environment before rotation.

Create the replacement

Create a replacement with the minimum scopes needed by the caller:

curl -X POST \
  "https://api.featuregate.dev/v1/projects/$FEATUREGATE_PROJECT_ID/environments/production/runtime-keys" \
  -H "Authorization: Bearer $FEATUREGATE_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "checkout-api rotation 2026-07",
    "scopes": ["runtime:snapshot"]
  }'

The response contains rawKey once. Write it directly to the deployment secret store. Avoid shell arguments, temporary files, CI annotations, and JSON debug output that could retain it.

If secure direct transfer is unavailable, stop. Do not print the secret for later manual copying from logs.

Deploy with overlap

Deploy or reload consumers while the old key remains active. Account for rolling deployments, queued jobs, warm serverless instances, and processes that refresh snapshots on different schedules.

Verify the replacement through the actual integration path:

Direct callers receive a successful evaluation.
Snapshot clients complete a successful refresh.
The response binds to the expected environment.
Authentication errors do not increase.
Application defaults are not activated unexpectedly.

Observe an overlap window long enough for the deployment topology, not an arbitrary fixed delay.

Revoke the old key

Call the owner route for the exact old key ID:

curl -X POST \
  "https://api.featuregate.dev/v1/projects/$FEATUREGATE_PROJECT_ID/environments/production/runtime-keys/$FEATUREGATE_OLD_KEY_ID/revoke" \
  -H "Authorization: Bearer $FEATUREGATE_MANAGEMENT_KEY"

Confirm revoked metadata and project activity. Test that current callers continue through the new key.

Revocation blocks future API requests. It cannot erase a snapshot already held in process memory.

Recover from failure

Failure	Recovery
New secret lost before deployment	Create another key and revoke the unused record
Verification fails	Keep the old key active and inspect scope, binding, and deployment
Old key revoked too early	Deploy a newly created key and accept caller-default behaviour during recovery
Suspected compromise	Revoke immediately, rotate management access if exposed, and review activity
Snapshot process still uses old state	Refresh successfully with the replacement or restart it

Do not attempt to recover a one-time raw secret from list or audit endpoints.

Rotation ownership

Document who owns the deployment, verification, revocation, and incident response. Use separate keys for independently deployed callers so one rotation does not coordinate unrelated systems.