# Rotate runtime keys through automation

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:

```sh
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:

```sh
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.

Related pages: [Evaluation credentials](/docs/evaluate/credentials),
[Activity and audit history](/docs/operate/activity-and-audit), and
[Errors and fallbacks](/docs/evaluate/errors-and-fallbacks).