Rotate an API key

Replacing an API key happens in two scenarios: regular hygiene (rotate every N months as policy) or emergency response (key was leaked). Both flows are similar; the speed differs.

The pattern is always: generate → update consumers → revoke. Doing it in this order means zero downtime.

Standard rotation (no time pressure)

Use this for periodic rotations. Recommended cadence is at least annually, more often for keys with broad scope.

Steps

1. Generate a replacement key in Settings → API Keys with the same scopes and rate limit tier as the existing key. Name it with a clear successor relationship (e.g. KB Sync Script — Production v2). See Generate an API key.
2. Store the new key in your secrets manager. Don’t delete the old key’s entry yet — keep both for the rotation window.
3. Update each consumer to use the new key. Common consumers:
   Scripts and CI workflows — update env vars, secrets, or 1Password references
   Integrations — re-authenticate with the new key
   Webhook receivers — verify they continue working with the new key
4. Verify each consumer. Make a real request through each updated path and check the new key’s lastUsedAt timestamp updates in Settings → API Keys.
5. Wait 24–48 hours to confirm no consumer was missed. Watch the old key’s lastUsedAt — if it stops updating, every consumer has migrated. If it keeps updating, find the missed consumer.
6. Revoke the old key in Settings → API Keys → the key → Revoke. Once revoked, any consumer still using the old key gets 401s — your safety net for catching anything missed.
7. Delete the old key entry from your secrets manager.

Emergency rotation (key leaked)

When a key is compromised — committed to a public repo, included in a screenshot, exposed in error logs — speed matters more than zero downtime.

Steps

1. Revoke the old key first. Don’t wait to migrate consumers. The leak is a higher risk than the temporary downtime. In Settings → API Keys → the key → Revoke immediately.
2. Generate a replacement with the same scopes.
3. Update consumers as fast as possible. Until they’re updated, they’ll be returning 401s — accept that downtime. The leaked key is doing more damage than the broken integration.
4. Investigate the leak source. Where was the key exposed? Repo? Logs? Email? CI artifacts? Find and remediate so it doesn’t happen again.
5. Audit usage of the leaked key. In Settings → API Keys → the (revoked) key → Usage, look at the request history for the period before revocation. Anything anomalous? Endpoints the key shouldn’t have hit, IP addresses you don’t recognize, request volume spikes? If yes, treat it as a security incident — review what data was accessed, notify affected parties per your security policy.

What “revoke” does

Revoking a key:

• Marks it inactive in the database
• Causes all subsequent requests with the key to return 401 Unauthorized
• Preserves the usage history (for audit)
• Does NOT delete the key record — you can still see its name and history in Settings

A revoked key cannot be reactivated. If you revoke by mistake, you generate a new key — there’s no undo.

Common rotation mistakes

• Revoke before updating consumers — Downtime — consumers get 401s — Always do generate → update → verify → revoke
• Forget to update one consumer — That consumer breaks when old key is revoked — Watch lastUsedAt on the old key for 24-48 hours; revoke only when it stops updating
• Use the same key name for replacement — Confusing in monitoring; can’t distinguish old from new — Use v2 or a date suffix in the new key’s name
• Skip the secrets manager update — Old key still in storage; could be re-used by accident — Update the secrets manager as part of the consumer update

Rotation cadence

• Low-risk read-only key (e.g. analytics) — Annually
• Standard write key — Every 6 months
• Broad scope or high-privilege key — Quarterly
• Key with full_access — Quarterly minimum, ideally with the key replaced by narrower-scope keys
• Key suspected to be compromised — Immediately

Automating rotation

For mature integrations, treat rotation as a regular CI/CD task:

• Schedule a monthly job that generates a new key, runs an integration test against it, updates the secrets manager, and revokes the old key
• Use 1Password Service Accounts or AWS Secrets Manager rotation hooks to do this automatically
• Track rotation dates so you can audit “every key in production was rotated within the last 90 days”

See also

• Generate an API key
• Monitor API usage