Home / Knowledge hub / API key rotation
Knowledge hub
API key rotation
Issuing new API keys on a schedule and retiring the old ones.
What it means
API key rotation is the routine of creating a new API key, moving clients to it, and switching the old one off. It can happen on a calendar, after a staff change, or straight away when a key is suspected to have leaked.
The aim is to shorten how long a stolen key stays useful. A key that never changes is a password nobody can remember changing. If it leaked two years ago, it may still work today. Rotation is the habit that turns that unknown into a known, short window.
Why it matters
Keys leak in quiet ways: a public repository, a support screenshot, a build log, a contractor's laptop. Nobody notices for months. Rotation puts a ceiling on how long the finder can use it, and it forces you to learn where each key is really used.
That second benefit matters as much as the first. If rotating a key breaks production, you have found a hardcoded secret and a fragile dependency before an attacker did. Auditors also ask about key rotation in questionnaires. Both are worth having even when no key has ever leaked.
How it shows up
Good rotation lets two keys work at once for a short overlap, so clients can move without downtime. Each customer or integration gets its own key, so one leak does not force everyone to change. Keys come from a secrets manager, not from files.
The usual failures are keys with no expiry, one shared key for every service, rotation done by hand and then forgotten, and old keys left active after the new one is live. Check that a retired key really returns an error, and that you can see when each key was last used.
Questions people ask
API key rotation, answered
How often should API keys be rotated?
There is no single right interval. It depends on how sensitive the access is and how easy rotation is. NIST ties key lifetimes to how much data a key protects and how exposed it is.
Make rotation automatic first, then shorten the interval.
What do we do when a key leaks?
Revoke it at once, issue a new one, and check the logs for use you do not recognise. Do not wait for the next scheduled rotation.
Then find out how it leaked, or the next key will follow it.
Is rotation the same as revocation?
No. Revocation kills one key now. Rotation is the planned replacement of keys before anything has gone wrong.
You need both: the habit and the emergency switch.
Does rotation fix a weak key design?
No. A key with no scope still gives a thief everything. Give each key the least access it needs, and limit it by endpoint or by source where you can.
Rotation limits the time; scope limits the damage.
How do we rotate without downtime?
Allow the old and new key together for a short overlap, move clients one by one, then disable the old key. Watch the last-used time on the old key before you remove it.
If it is still being used, someone has not moved.
Sources
Where this comes from
Related
Terms that sit next to this one
API key
A secret string that identifies the app calling your API, and is easily leaked.
Key rotation
Replacing a credential on a schedule so a leaked one has a short life.
Secrets management
Keeping keys, passwords and tokens out of code and in a vault.
Hardcoded secret
A password, API key or token written straight into source code.
API authentication
How an API decides which caller is making a request before it does anything.
Does a retired key really stop working?
We check whether old keys, leaked keys and over-broad keys still open doors, and we show the request that proves it. Retests re-run the same exploit. Book a pilot on one app.
Or start with a $199 pilot on one application: thirty days, success criteria agreed before day one, credited against the annual if you convert.