API Token Rotation: A Practical Guide to Safe, Zero-Downtime Rotation

API token rotation means replacing a token with a new one on a schedule, or right after a suspected leak, and then disabling the old one. Done well, it shrinks the window in which a stolen token is useful. It also shouldn't break a single request. The way to get both is to overlap the old and new tokens, test the new one before you cut over, and automate every step you can.
This guide covers the full routine: what rotation is, how often to do it, the overlap pattern, what to automate, how to store and track tokens, and what to do when a token leaks or a rotation fails. We run scrapers and data pipelines against our own proxy API all day, so we write with automated workloads in mind.
TL;DR
- Rotation is a three-part sequence: create a new token, deploy it to every consumer, then revoke the old one. Never revoke first.
- Rotate regularly (CISA suggests typically at least every 90 days) and immediately after any suspected exposure.
- Overlap old and new tokens, test the new one against the real endpoint, and only then retire the old one.
- Automate creation, testing and distribution. Keep an inventory of owner, scope, consumers and rotation dates for every token.
- Plan for failure: keep the current token live until its replacement is verified, and have a break-glass path.
Table of Contents
- What API token rotation is, and where it fits in token management
- Why rotate tokens at all
- How often should you rotate?
- The zero-downtime pattern: overlap, test, then retire
- What to automate, and what to verify before revoking
- Scope, store and track every token
- If a token is exposed or a rotation fails
- Our perspective
- Rotating credentials for scraping and data workloads
- Try it on real mobile carrier IPs
- FAQ
- Sources
What API token rotation is, and where it fits in token management
Rotation is one lifecycle step in a larger practice. One technical doc defines it as generating a new token, distributing it to applications, and then disabling the existing token. CISA describes the same pattern for API keys: generate a new key, replace the compromised one, then revoke and securely delete the old key.
Token management is the wider discipline around that step. It covers who can create a token, what the token may do, where it lives, who uses it, when it expires and how you find out if it is misused. OWASP makes the same point: rotation is only one part of secrets management, and inventory, expiration, backups and recovery decide whether rotation stays sustainable.
A quick vocabulary check helps, because the terms get mixed up:
- API key or static token: a long-lived secret sent with each request. These are the main target of rotation schedules.
- Access token: usually short-lived, issued by an authorization server and often renewed automatically.
- Refresh token: used to obtain new access tokens. It needs its own expiration and revocation controls.
If you are deciding between delegated-authorization approaches in the first place, this explainer on OAuth and SAML differences is a good primer. Rotation then applies to whatever long-lived credentials remain after that choice.
Why rotate tokens at all
Tokens leak. They end up in a committed config file, a CI log, a screenshot, a laptop that gets lost or a contractor's old setup. Rotation caps how long any single leak is useful. CISA frames it as a way to disrupt stolen-key attacks.

The UK National Cyber Security Centre is blunt about the alternative. Long-term access keys can grant indefinite access after a compromise, so it recommends shorter-lived credentials when secure storage or replay resistance is not available.
There is a second benefit that teams underrate: practice. A token you rotate every quarter is a token whose consumers you know. A token nobody has touched in three years is one nobody dares to change, and that fear is itself a risk.
How often should you rotate?
There is no single correct interval. Published guidance gives a range:
| Source | Guidance |
|---|---|
| CISA | Regular rotation, typically at least every 90 days |
| Esri developer documentation | 90 days used as an example interval, with two valid keys and staggered expiry |
| Synoptic docs | A 1-to-30-day rotation period for its tokens, plus an extra full period left for overlap |
| OWASP | Lifetimes depend on the secret's function and protection, from minutes to years |
A workable way to choose is to ask three questions:
- What can the token do? A token that can read public price data deserves a longer interval than one that can create users or spend money.
- Where does it live? A token injected at runtime from a secret manager is safer than one baked into a container image.
- How painful is a swap? If rotation is automated and tested, you can afford a short interval. If it needs a manual deploy across five services, start at 90 days and automate your way down.
Whatever interval you pick, rotate immediately when a token may have been exposed, someone with access leaves the team, or a system that held the token is retired.
The zero-downtime pattern: overlap, test, then retire
Most rotation outages come from one mistake: the old token is disabled before every consumer has the new one. Microsoft's reliability guidance treats rotation as a deployment problem as well as a security problem, and recommends redundancy in secrets, consumers and access methods so a swap does not affect workload reliability.
The pattern looks the same across providers:
- Inventory the consumers. CISA advises reviewing which applications and services use an affected API before rotating, because rotation can break anything that depends on a hardcoded or device-stored key.
- Create the new token while the old one stays valid.
- Test the new token against the real service endpoint. One vendor warns that token changes propagate asynchronously, so a token that fails in the first second may work a moment later, and a quick smoke test beats assuming.
- Migrate consumers in stages: a canary job first, then the rest.
- Watch for stragglers. Look at authentication failures and last-used timestamps on the old token.
- Retire the old token only when nothing is using it.
Two slots and grace periods
Providers implement overlap in a few ways. Some give you two token slots: add a secondary token, migrate clients, then delete the old one, with both accepted in between. Esri supports two simultaneously valid API keys with staggered expiration dates, which allows production rotation with no application downtime. Others rotate in place and keep the old token alive for a configurable window; one incident-management API allows a grace period of up to 60 minutes.
When a provider invalidates the old token immediately, build retry logic into the client. AWS describes the approach: after a 401 or 403, the application can retry with the previous secret version. It is a cheap safety net that turns a hard failure into a single retried request.
A worked example
Say a pricing scraper runs on three workers and reads one API token from environment variables. A safe quarterly rotation looks like this:
- Day 0: generate token B in the provider dashboard. Token A stays active.
- Day 0: store B in your secret manager as a pending version and run one test request using B.
- Day 0 to 1: restart workers one at a time so each picks up B. Confirm each worker's first successful request in your logs.
- Day 2: check the provider's usage view for any remaining traffic on A.
- Day 3: revoke A, record the date and the next rotation due date in your inventory.
Nothing in that list is clever. It is simply an order of operations that never leaves you without a working credential.
What to automate, and what to verify before revoking
Manual rotation is error-prone, which is why OWASP recommends automated rotation of static secrets or, at minimum, tooling that supports it. The NCSC goes further and says credential renewal should happen without human involvement, treating automation as a security control and not only a convenience.
AWS's reference design is a good template even if you do not use its service. Its rotation function has four steps: createSecret, setSecret, testSecret and finishSecret. The new key is stored as pending, tested with the provider, and only then promoted to current. The current credential is preserved until the replacement is proven.
Turn that into a checklist your own job can follow:
- Create the new token with the minimum scope needed.
- Store it in the secret manager as pending, not current.
- Test it with a real, low-impact request.
- Promote it so consumers pick it up.
- Verify that authentication failures stay flat and the old token's traffic drops to zero.
- Revoke the old token and log the event.
If the test step fails, AWS's guidance is to delete the pending key at the provider and raise an exception. It also retries a failed step, and if the failure happens during key creation the current key stays active. Copy that behavior: failure should leave you exactly where you started.
For OAuth-style flows, NIST's 2026 report on token protection recommends automatic token refresh, while requiring refresh tokens themselves to be securely managed and subject to expiration and revocation policies.
Scope, store and track every token
Rotation works best on tokens that are already well behaved. NIST IR 8587 says workload identities should use tightly scoped, short-lived tokens, issued through approved enterprise identity platforms and, where feasible, sender-constrained with mechanisms such as mTLS or DPoP.
Storage rules
- Keep tokens in an approved secret manager or equivalent. AWS's framework says to store secrets in a managed service and rotate them automatically where possible.
- Inject them at runtime, ephemerally.
- Keep them out of source code, logs, CI artifacts and build outputs, as the NIST guidance lists.
What to record for each token
NIST suggests tracking owner, purpose, consumers, environment, scope, creation and rotation dates, expiration and responsible operators. OWASP adds that metadata should cover creation, consumption, archival, rotation and deletion times, responsible actors and intended use. A simple table or secrets-manager tags are enough to start:
| Field | Example |
|---|---|
| Name | pricing-scraper-prod |
| Owner | data-platform team |
| Consumers | three scraper workers |
| Scope | read-only data access |
| Created / next rotation | recorded at each swap |
| Expiry | set to the rotation interval |
What to monitor
Watch usage volume, authentication failures, unusual locations or behavior, and attempts to reuse a token after revocation. Feed those events into whatever alerting you already run. A sudden burst of failures right after a rotation usually means a consumer was missed. A burst of failures on a revoked token is worth a closer look.
If a token is exposed or a rotation fails
Speed matters more than elegance here. CISA's advice for an exposed key is to identify and remediate the theft path, rotate the key, revoke and securely delete the old key, and consider additional authentication protections. Closing the hole matters: rotating a key while the leak path is still open just hands the attacker the new key.
A short incident runbook:
- Revoke or rotate the token now. In an emergency you accept some downtime, since Microsoft's guidance says active secrets should not be retired except in an emergency.
- Find how it leaked: repository history, logs, CI output, a shared document.
- Review usage logs for the exposure window.
- Issue the replacement with a narrower scope if you can.
- Update your inventory and note what you changed to stop it happening again.
Be aware that revocation is not always instant for every token type. NIST notes that immediate global revocation is not always possible for stateless tokens, so short-lived access tokens plus refresh-token controls are what limit the compromise window.
For your own recovery, OWASP recommends dynamic secrets where possible, defined expiration, secure backups, tested restores and break-glass credentials held in a secondary secure system. If your only way to issue a new token is the primary system that just failed, you have a gap.
Our perspective
We build a proxy API that automated workloads call thousands of times a day, so we see rotation from the operator's side. The credential is not the hard part. The hard part is knowing every job that holds it.
That is why we give teams self-serve credential management and a usage dashboard. You can set up access immediately, with no sales call, and see which credentials are doing what. When each job or team has its own credential, you can swap one without touching the others, and an organization can keep ownership clear as people come and go.
Our advice for scraping and data teams: give every pipeline its own credential, put it in a secret manager, and treat rotation as a routine deploy. The overlap, test, retire sequence in this guide is the one we would run ourselves.
Jon
Rotating credentials for scraping and data workloads
Automated collection jobs are exactly where rotation habits pay off. They run unattended, they are spread across workers and schedulers, and their credentials often sit in environment files. A few practices carry over directly:
- One credential per pipeline or environment. Staging and production should never share a secret.
- Load credentials at startup from your secret manager, so a rotation is a restart and not a code change.
- Log which credential version a worker used, never the secret itself.
- Test after every swap with a single low-volume request before the full job resumes.
If your workloads route through proxies, the same logic applies to the proxy credentials, and our guide to proxy API integration walks through wiring them into common languages. For a first working request, the quickstart from credential to first request is the shortest path, and session management tips cover keeping long-running jobs stable. Note that IP rotation is a separate idea from credential rotation: our post on rotating vs sticky sessions explains the IP side.
Try it on real mobile carrier IPs
If your team collects data at scale, we built MaskLabs for you: real US mobile carrier IPs in 46 cities, rotating or sticky sessions, API access, HTTP, HTTPS and SOCKS5 support, metered per-byte billing and team credential management. Plans start at $30 per month for Starter, with Basic at $100 per month, Advanced at $500 per month and Scale at $1,000 per month, and there is a free trial with limited data. See the details on our pricing page or start from the MaskLabs homepage.

Setup is self-serve, with no sales call and no long-term commitment, so you can get a credential into your secret manager and run your first request the same day.
FAQ
How often should I rotate API tokens?
CISA suggests regular rotation, typically at least every 90 days. Higher-risk or broadly scoped tokens deserve shorter intervals, and anything possibly exposed should be rotated at once. Automating the process is what makes shorter intervals realistic.
What is the difference between API token rotation and API token management?
Rotation is the act of replacing a token with a new one and retiring the old. Token management is the whole lifecycle around it: scoping, storage, inventory, monitoring, expiration and revocation. Rotation only stays sustainable when the rest of that lifecycle is in place.
How do I rotate a token without downtime?
Keep the old and new tokens valid at the same time, test the new one against the real endpoint, move consumers over, and revoke the old one only when nothing uses it. If your provider offers two token slots or a grace period, use them. If it does not, add client-side retry logic for 401 and 403 responses.
Can I automate API token rotation?
Yes, and the major security guidance says you should. A typical automated flow creates the new token, stores it as pending, tests it, promotes it and then revokes the old one. If any step fails, the current token should remain active while the job raises an alert.
What should I do if an API token is leaked?
Rotate or revoke it immediately, and find and close the path it leaked through, or the new token may leak the same way. Then review usage logs for the exposure window and update your inventory.
Sources
- Token Rotation Guide, Synoptic Docs
- CISA, API key rotation countermeasure
- NCSC, Securing HTTP-based APIs
- Microsoft, Architecture strategies for protecting application secrets
- OWASP Secrets Management Cheat Sheet
- AWS, Manage API keys for security-sensitive workloads
- AWS Well-Architected, Store and use secrets securely
- Esri, Tutorial: Rotate API keys
- Anyscale, Rotate a service bearer token
- incident.io, Rotate API key
- NIST IR 8587, Protecting Tokens and Assertions