API key rotation: do's and don'ts
Updated 2026-05-07
API key rotation is unsexy and load-bearing. The teams that get it right when they don't have to are the teams who don't scramble during their first leaked-credential incident or first SOC 2 audit.
For broader credential management context, see the session management guide and the token revocation best-practice.
Do
Rotate API keys on a fixed schedule (90 days for sensitive, 365 for less)
Long-lived keys accumulate exposure: leaked into commits, copied into Slack, embedded in old test scripts. Scheduled rotation bounds the exposure window.
OWASP and NIST SP 800-63 both recommend bounded credential lifetimes. Major cloud providers (AWS, Google Cloud, Azure) default API keys and service-account credentials to bounded lifetimes with rotation reminders.
Support overlapping validity during rotation (old + new both work)
If rotation invalidates the old key immediately, every consumer must update simultaneously. Overlapping validity (typically 30 days) lets consumers update at their own cadence without breakage.
Standard pattern in major cloud APIs (AWS access keys allow two active per user, GCP service account keys support multiple). The CIAM equivalent: the management API supports issuing a new key with overlap, then revoking the old after consumers migrate.
Bind keys to a specific scope and origin where possible
A scoped key that only works for specific operations from specific IPs limits the damage when leaked. Unscoped keys are root credentials.
OAuth scopes plus IP allowlisting reduce exposure surface meaningfully. Production deployments that scope keys see materially smaller blast radius from accidental leaks (committed to git, leaked in logs, etc.).
Audit-log every key issuance, rotation, and revocation
Key lifecycle is a security-relevant event. Without audit, a leaked key cannot be traced back to its issuance context, which user requested it, which service consumed it.
Required by SOC 2, ISO 27001. Modern CIAM ships key lifecycle events to the audit log automatically; verify your platform does.
Don't
Don't use long-lived API keys when short-lived tokens work
API keys are static credentials; short-lived tokens (OAuth client credentials, signed assertions) carry less leak exposure. Modern services should prefer the token model.
Cloud-native architecture patterns explicitly favor short-lived tokens (OAuth, IAM role assumption, signed JWT assertions) over static API keys. Static keys are acceptable for legacy compatibility but not the default for new development.
Don't commit API keys to source control
Public and private repositories both leak. Public repos to scrapers; private repos to anyone with read access (former employees, audited contractors, breach-exfiltrated copies).
GitHub secret scanning has surfaced millions of leaked credentials. Tools like git-secrets, Gitleaks, and TruffleHog routinely catch credentials in commits. Use secret managers (AWS Secrets Manager, GCP Secret Manager, Vault, Doppler) instead.
Don't share API keys across multiple consumers
Shared keys cannot be revoked per-consumer. When one consumer is compromised, all consumers lose access during rotation.
Standard credential-hygiene practice. Per-consumer keys add operational overhead but enable surgical revocation; shared keys make rotation an all-or-nothing event.
Don't display the full API key in UI after creation
Display the key once at creation time, then store only a prefix or fingerprint. UI that perpetually displays the full key creates additional leak surfaces (screenshots, screen-share, shoulder-surfing).
GitHub, AWS, Stripe, and most modern API platforms display the key once and never again. The pattern is well-established; deviating from it is the antipattern.