API Key Rotation Workflow

Issue a new key alongside the old, support an overlap window, monitor usage on both keys, and revoke the old key once traffic has moved.

intermediate~60 minsecuritysecretsapi

Objective

Rotate an API key so consumers can migrate without downtime and the old key is not left valid forever.

Environment

A key management system supporting multiple active keys
Usage telemetry per key

Steps

1. Create the new key and share

Create the new key and share it through a secure channel.

Expected state: The consumer has a new credential.

2. Allow both keys for a defined

Allow both keys for a defined overlap window.

Expected state: The consumer can switch without an outage.

3. Monitor usage on each key during

Monitor usage on each key during the overlap.

Expected state: You can see when traffic has moved.

4. Revoke the old key after

Revoke the old key after the window and confirm no usage remains.

Expected state: The old credential is dead.

Decision points

How long should the overlap be?

24 hours
One billing cycle

Give at least one full usage cycle; a billed monthly consumer needs a month so the switch is not rushed.

What if the old key is still used at the deadline?

Revoke anyway
Extend and notify

Revoke only after explicit confirmation; an unexplained user is likely an unowned integration.

Expected outcome

The new key is in use, the old key is revoked, and there was no authentication outage for the consumer.

Verification

Check that the old key reports zero calls for a full cooling period before revocation, and that the new key handles the expected volume.

Cleanup

Remove the old key from any inventory and update documentation to reference the active key.

Overview

Rotate an API key so consumers can migrate without downtime and the old key is not left valid forever. Check that the old key reports zero calls for a full cooling period before revocation, and that the new key handles the expected volume.

Steps

Create the new key and share it through a secure channel. Expected state: The consumer has a new credential.
Allow both keys for a defined overlap window. Expected state: The consumer can switch without an outage.
Monitor usage on each key during the overlap. Expected state: You can see when traffic has moved.
Revoke the old key after the window and confirm no usage remains. Expected state: The old credential is dead.

# issue new key, keep both active
curl -X POST https://api.example.com/keys -H "Authorization: Bearer $ADMIN" -d '{"label":"2026-10"}'
# after overlap, revoke old
curl -X DELETE https://api.example.com/keys/old-key-id -H "Authorization: Bearer $ADMIN"

Verification

The new key is in use, the old key is revoked, and there was no authentication outage for the consumer.

Decision points

How long should the overlap be? Options: 24 hours; One billing cycle. Recommended: Give at least one full usage cycle; a billed monthly consumer needs a month so the switch is not rushed.
What if the old key is still used at the deadline? Options: Revoke anyway; Extend and notify. Recommended: Revoke only after explicit confirmation; an unexplained user is likely an unowned integration.