Retire an old API version when few clients use it and migration is easy. Backport a security fix when many clients cannot move soon. Either way, keep protections on every exposed version, because attackers will test the old ones first.
Why old versions are risky
OWASP's improper inventory entry says running multiple API versions adds management overhead and enlarges the attack surface. Old versions often lack controls added later, and nobody is looking at their logs.
OWASP's example is a beta host that lacked the rate limiting the main API had. A researcher brute-forced six digit reset tokens there and reset any user's password. The newer code was fine. The old surface was not.
What OWASP recommends
Two lines from the prevention list apply directly:
- Apply external protections to every exposed API version, not just production.
- When newer versions add security improvements, assess risk to decide whether to backport them or retire older versions and move clients to the latest.
So the choice is explicit, and it should be made on purpose.
Decision guide
- Client count: Points to retire: Few active clients; Points to backport: Many active clients
- Migration effort: Points to retire: Small, documented; Points to backport: Large, needs partner work
- Severity of the gap: Points to retire: Gap is minor; Points to backport: Gap allows takeover or data exposure
- Maintenance cost: Points to retire: Old code is hard to change; Points to backport: Fix is small and local
- Contractual notice: Points to retire: Notice period is short; Points to backport: Long commitments
If the gap is severe and the version cannot be fixed soon, restrict it. Put it behind stricter limits or take it off the public internet while you work on migration.
Steps for a retirement
- Find real usage from logs: who calls the version, how often, which endpoints.
- Announce a date and a migration path.
- Add deprecation notices in responses.
- Tighten limits on the old version as the date nears.
- Switch it off, then remove the routes and the hosts.
Removing the host matters. A version left running with no traffic is the typical unpatched machine.
Steps for a backport
- List the specific controls missing: rate limits, auth checks, field level checks, error handling.
- Patch them in the old code and add tests.
- Confirm the old host sits behind the same gateway rules.
- Set a retirement date anyway. Backporting buys time, not permanence.
Keep environments honest
OWASP also says to keep production data out of non-production environments, or give them equal security if unavoidable. Beta and staging hosts holding real data are a frequent source of leaks.
For the inventory that makes these decisions possible, see what to record for every API host.
Quick check
Is it enough to hide old docs?
OWASP does advise limiting documentation access to authorized users, but the endpoints still answer. Hiding docs is not retirement.
Do beta hosts need the same protections?
Yes, if they are exposed. The OWASP example turned on a beta host without rate limiting.
Safeguard's asset discovery and policy gates can help find and govern forgotten services, and the free scan at gold.safeguard.sh/scan checks dependencies and SBOMs.
Sources
Last reviewed: 19 October 2026.
