Key takeaways
- NIST SP 800-57 defines cryptoperiods and SP 800-53 IA-5(1) requires enforced lifetimes and on-demand rotation, but neither mandates a specific day count.
- A 30/60/90 day rotation policy is a defensible mapping of NIST guidance, not a NIST requirement; match cadence to blast radius.
- In AWS API Gateway, attach the replacement key to the same usage plan so quota and throttle counters carry over, then disable the old key before deleting it.
- Dual-key overlap windows should be 24 hours for internal keys, 7 days for most SaaS credentials, and 30 days when consumers cannot be enumerated.
- Vaults store secret values but do not track ownership and expiry deadlines, so a written policy with named per-key owners is still required.
API key rotation is the scheduled replacement of credentials before they leak or expire, and your vault only stores keys, it does not coordinate who owns them or when they turn over. This guide maps NIST SP 800-57/800-53 guidance to a written rotation policy template, then walks through AWS API Gateway usage-plan key rotation with a dual-key overlap window and explicit rollback criteria.
What is API key rotation and why does it matter?
API key rotation is replacing a live credential with a new one on a schedule, then retiring the old key after a defined overlap window. The point is to cap how long a leaked or stale key stays usable. NIST's cryptoperiod guidance in SP 800-57 Part 1 Rev 5 sets explicit lifetimes for authentication and key-derivation keys, and those limits are the usual anchor for a 30/60/90 day rotation policy.
If you already pay for a vault, rotation still fails on coordination: nobody owns the deadline, nobody tracks expiry, and secrets sprawl into Postman collections and CI configs. We cover that operational gap in more depth in API key management best practices.
What do NIST guidelines actually require for API key rotation?
NIST does not publish a single rotation number for API keys. SP 800-57 defines the cryptoperiod: the lifetime a key is authorized for use, chosen based on risk, usage volume, and how quickly the key could be compromised. SP 800-53's IA-5(1) then requires you to enforce that lifetime and be able to rotate on demand, not on a fixed calendar alone.
Cryptoperiods vs rotation policy
A cryptoperiod is a property of the key. A rotation policy is what your team writes down: who owns the key, when it expires, what triggers early rotation, and how the swap happens. The 30/60/90 day rotation policy many teams adopt is a defensible mapping of NIST's "shorter for high-risk keys" guidance onto operational reality, not a NIST mandate.
What 800-53 IA-5(1) asks for in practice
IA-5(1) expects documented key types, cryptoperiods per key type, and evidence that rotation actually happened. A table like this is the usual starting point:
| Key type | Cryptoperiod | Owner | Rotation trigger |
|---|---|---|---|
| AWS usage-plan key | 90 days | Platform engineering | Scheduled or suspected exposure |
| Stripe restricted key | 90 days | Payments platform | Scheduled or suspected exposure |
| GitHub PAT (fine-grained) | 60 days | Owning team | Scheduled or suspected exposure |
The hard part is not the table; it is keeping expiry dates, owners, and actual rotations reconciled across AWS and SaaS providers. That coordination layer is the gap KeyGuardRail targets, and we cover concrete policy examples separately at api key expiration policy examples.
How do you rotate an API key in AWS API Gateway without breaking quota tracking?
Create the replacement key and attach it to the same usage plan
In API Gateway, a usage plan key is an API key bound to a usage plan, and the quota and throttle limits live on the plan, not the key. So rotation starts by generating a new key with create-api-key, then calling create-usage-plan-key to attach it to the identical usage plan your old key uses. The new key inherits the plan's quota and throttling counters from the moment it is attached; it does not start with a fresh allowance unless you put it on a different plan. Stage the key in Secrets Manager or your vault of choice with an owner tag and an expiry date, so the next rotation deadline is visible before it arrives.
Verify quota and throttling counters
Before any client touches the new key, confirm it resolves to the right plan with get-usage-plan-keys, and check get-usage to see the plan's used-versus-remaining quota. If you attached the key to the wrong plan, quota tracking breaks silently: clients hit limits that do not match their entitlement, or worse, share a pool with another team. A five-minute check here is cheaper than a quota incident.
Cut over clients, then disable the old key
Deploy the new key to clients through your usual secret distribution path, verify a real request succeeds, then disable the old key with update-api-key before deleting it. NIST's authenticator management control, IA-5(1), requires that old credentials be invalidated when replacements are issued, and the disable-then-delete sequence gives you a rollback path that satisfies that requirement (NIST SP 800-53 Rev. 5, IA-5(1)). Keep the overlap window short and dated: an old key left enabled indefinitely is the secrets sprawl problem again. Assign an owner to each key so the disable step has a name attached to it, not just a cron entry.
How long should the dual-key overlap window be during rotation?
Match the window to blast radius, not to a policy template. 24 hours works when the key is internal, low-traffic, and you control every caller. 7 days fits most SaaS credentials like Stripe or GitHub, where third-party integrations, webhooks, or a teammate's laptop may still hold the old key. 30 days is for keys embedded in customer deployments or long-lived batch jobs you cannot enumerate. If you cannot list every consumer of a key, take the longer window.
What to monitor during overlap
Overlap is not idle time. Track request counts and error rates per key so you can see which consumers have migrated. When old-key traffic hits zero, retire it early; when it stalls, find the straggler before the deadline. Log which service accounts and IP ranges still call the old key, and check the permissions attached to it (see https://keyguardrail.com/blog/how-to-audit-api-key-permissions) so an unused key is not sitting over-privileged through the whole window.
When a shorter window is safe
Go short when callers are all in your own repos, deploy times are hours not weeks, and you have a tested rollback path. If any of those three is missing, the overlap window is doing rollback work for you, so widen it.
What should a written key rotation policy include?
A policy that survives contact with production has six fields: scope, cadence, owner, overlap window, rollback criteria, and exception process. Write each one down. If a key's owner is "the platform team," nobody owns it.
Policy template fields
For every credential, record: the key identifier and where the secret value lives (Secrets Manager, Vault, Infisical), a named owner (person, not team), rotation cadence, overlap duration, the rollback trigger ("4xx spike above baseline within 30 minutes"), and who can approve an exception. Metadata only stays in the policy doc; the secret value never leaves the vault. A shared register covering ownership, expiry, and deadlines beats scattered notes, and the same fields work whether you run AWS, Stripe, or GitHub credentials (API key lifecycle management tips).
Mapping cadence to key type
Match cadence to blast radius, not to one blanket rule. Usage-plan keys in API Gateway can be created, disabled, or deleted at any time, and AWS recommends disabling before deleting so you can re-enable on failure (disabling and deleting API keys). Suggested illustrative cadences: 30 days for high-traffic usage-plan keys, 60–90 days for lower-risk SaaS tokens, and short-lived credentials wherever the provider supports them. Where KeyGuardRail falls short: it tracks deadlines and ownership but does not rotate keys for you, so your policy still needs a named human or script to execute each rotation.
How do you roll back a rotation that breaks production?
Rollback is a decision, not a reflex. Decide the criteria before you rotate, so nobody is improvising during an incident.
Rollback criteria checklist
Re-enable the old key first, then verify, then decide. A rotation rollback is safe precisely because the old key is still valid inside the overlap window.
Treat any of these as rollback triggers:
- API Gateway returns
401or403at a rate above your pre-rotation baseline - A consumer reports auth failures and the new key is confirmed deployed on their side
- Quota or usage-plan tracking shows requests not being counted against the new key
- Latency or error-rate alarms on the API fire within your verification window
Procedure: re-enable the old key (or remove its disable/schedule if you staged it), confirm traffic recovers to baseline, then hold the old key active and investigate before retrying. If the new key itself is misissued, abort rather than retry the same steps.
Post-incident: what to log
Record the rotation attempt, the trigger that fired, the exact time old-key traffic resumed, and the root cause. This audit trail is what turns a failed rotation into a documented retry with a fix, not a repeat incident.
How does rotation differ for usage-plan keys versus IAM credentials in AWS?
Usage-plan keys, IAM access keys, and Secrets Manager secrets rotate on different mechanics. Usage-plan keys are quota identifiers: you create a second key on the same usage plan, ship it, then deactivate the old one. IAM access keys are auth material with real blast radius, so AWS recommends rotating them regularly and updating your applications before retiring the old key, per AWS IAM best practices.
IAM access key rotation
Treat IAM keys as 90-day credentials: create the new key, deploy it everywhere it is used (CI runners, scripts, Postman collections), confirm no traffic on the old key in CloudTrail, then deactivate and delete. The dual-key overlap window from the API Gateway section applies here too, just with a wider deploy surface.
Secrets Manager automatic rotation
Secrets Manager secrets can rotate on a Lambda-backed schedule per rotation template, so the vault moves the value for you. What it does not track is ownership and who is still holding copies. KeyGuardRail monitors expiry and rotation deadlines as metadata only, so you can run a 30/60/90 day rotation policy across AWS, Stripe, and GitHub without giving anyone custody of the secret value.
How do you keep rotation on schedule when the vault is not enough?
What the vault does and does not cover
AWS Secrets Manager, Vault, and Infisical store secret values and, in some cases, rotate what they hold. What they do not answer is the operational question: who owns this key, when does it expire, and who is on the hook for the 30/60/90 day rotation deadline. That metadata lives in tickets, spreadsheets, and tribal knowledge, which is why secrets sprawl survives even after everyone moves keys into a vault.
Honest criteria: metadata-only vs custody tools
Judge tools on three criteria: do they hold secret values, do they track expiry and ownership, and do they enforce deadlines. Doppler, HashiCorp Vault, Infisical, and Akeyless are custody tools: they hold values and some rotate them. Clutch Security focuses on non-human credential risk. KeyGuardRail is deliberately metadata-only: it monitors credential lifecycle across AWS, Stripe, and GitHub without ever touching the secret value, so it cannot leak what it never holds. The tradeoff is real: it will not rotate a key for you, and if you want custody plus rotation in one place, a vault is the better fit. If you already have a vault but still cannot answer "who owns this key and when does it expire," a lifecycle layer on top is the missing piece.
FAQ
Can I rotate an API key without downtime if clients cache the old key?
Yes, if you keep the dual-key overlap window long enough to cover the longest cache or deploy cycle among your callers. Ship the new key, let clients pick it up on their next deploy or config refresh, and watch old-key traffic per consumer. Retire the old key only after its request count hits zero or the deadline arrives.
Does AWS rotate API Gateway usage-plan keys automatically for me?
No. Usage-plan keys have no built-in expiry, so AWS never rotates them on your behalf. You create a replacement key, attach it to the same usage plan, deploy it to clients, then disable and delete the old one. Secrets Manager can rotate certain secret types on a schedule, but usage-plan keys are not among them.
What is a reasonable 30/60/90 day rotation policy for long-lived keys?
Match cadence to blast radius: 30 days for high-traffic usage-plan keys and IAM credentials with broad permissions, 60-90 days for lower-risk SaaS tokens, and shorter-lived credentials wherever the provider supports them. If you cannot enumerate every consumer of a key, take the longer window and a wider overlap rather than a tighter calendar.
Who should own API key rotation on a small team?
One named person per key, not a team. If the owner is "the platform team," nobody owns it, and the deadline quietly slips. On a small team, the same engineer may own several keys, but each key needs a single name attached, plus a written trigger for early rotation so coverage is clear when that person is on vacation.
How do I prove rotation compliance during an audit?
Map each key to SP 800-53 IA-5(1): documented key type, cryptoperiod, named owner, and evidence the rotation happened. Keep a register with expiry dates and completed rotation timestamps, plus logs showing old keys were disabled before deletion. NIST does not mandate a specific number; auditors check that your stated policy matches what actually occurred.