How to Retire Old API Versions Without Breaking Web Integrations

An old API version may remain available long after a web migration, a CRM change, or the implementation of a new checkout. The problem arises when nobody can confirm which application, provider, or automation consumes it. Switching it off without checking can interrupt orders, forms, synchronisations, or customer registrations; keeping it without control extends an exposure surface that the company does not fully understand.

Retiring old API versions requires treating the change as an operations and security task, not as a simple technical deletion. The aim is not to disconnect everything that appears obsolete, but to have sufficient evidence of its use, its owner, the data it transfers, and the ability to roll back if a critical process fails.

The problem: a legacy integration that nobody dares to switch off

It is common to find routes such as /v1/, test subdomains, connectors created by an agency, or endpoints that survived a WordPress or online store redesign. The fact that an API is documented does not mean it remains active, and its absence from documentation does not prove that it can be retired either. The useful question is who uses it, for which business process, how often, and under whose responsibility.

OWASP identifies inadequate inventory management as a specific risk for APIs. Related issues include not knowing which versions are operational, which environment runs them, who should access them, or how to retire old versions. It also recommends assessing the risk of earlier versions when newer ones include security improvements. [1]

Create a minimum inventory that supports decisions

The inventory does not need to become an endless documentation project. For each API, host, relevant endpoint, or integration, it is advisable to record an identifier, URL or domain, environment, version, planned review date, technical owner, business owner, and external provider where applicable. It should also be clear which system sends the information and which one receives it.

Add a practical classification of the data exchanged—operational, personal, commercial, credentials, or payments—the authentication method, the secure location of the credentials, and the intended exposure level: public, internal, or limited to specific partners. Complete each record with evidence of recent use and its source, such as gateway, server, CDN, or application logs. NIST considers inventories of software, services, custom applications, API services, and cloud services, and highlights the need to assign responsibilities and update the inventory during changes and retirements. [2] [3]

• Identifier, URL or host, and version.
• Environment: production, pre-production, testing, or development.
• Technical owner, business owner, and provider, where applicable. Data exchanges and known consumers. Evidence of use, date,

Check what is active without affecting the service

Compare the inventory with authorised observation sources, such as access logs, gateway metrics, application events, or cloud infrastructure records. There is no need to perform intrusive testing or explore third-party systems. Look for recent requests, the origin of calls, response codes, service accounts, and related business processes. If there is not enough traceability, the integration is not ready to be switched off: it remains pending confirmation.

A simple classification reduces ambiguous decisions. Mark each item as active and approved when its use, owner, and maintenance are known; in migration if identified consumers and a change date exist; pending confirmation when the evidence does not allow a decision; or eligible for retirement when there is no confirmed use, the owner approves the decommissioning, and a defined rollback exists. For a hypothetical example, if a catalogue endpoint receives no calls during the agreed observation period, but a provider has not confirmed its replacement, it should remain pending confirmation rather than be declared retired.

Retire the version using a controlled change sequence

Before disabling a version, confirm who assumes the technical decision and who validates the business impact. Identify internal consumers, third-party integrations, and seemingly minor automations, such as a form that creates contacts or a task that updates inventory. Communicate a date, an incident channel, and the exact scope of the change. An agreed observation window makes it possible to detect dependencies without turning the retirement into an improvised shutdown.

Apply the change at a time planned by the company and verify any critical flows that may be affected: form submissions, order creation, customer registrations, synchronisations, and notifications. Keep evidence of the retirement, update the inventory, and maintain a limited, documented rollback with an internally defined duration. ENISA recommends maintaining an API inventory, comparing it with perimeter visibility and the knowledge of development and operations teams, as well as restricting incoming traffic to the necessary services. [4]

• Confirm technical and business owners.
• Notify internal consumers, providers, and operational owners.
• Observe, apply the change, and validate authorised critical processes. Document the decommissioning, update the inventory, and retain a roll

Prevent the retired API from becoming orphaned again

Non-production environments require attention proportionate to their exposure and the data they process. Using real data as a shortcut in testing can increase the impact of a legacy API if its controls are weaker or if it is unnecessarily exposed. OWASP recommends not using production data in non-production API deployments; when this cannot be avoided, it states that they must receive the same security treatment. [1]

Turn the inventory into a source of operational truth. Review it after every new integration, web migration, provider change, or service retirement, and establish a realistic periodic review. A web security audit can help organise exposed assets and dependencies within an authorised scope, but the decision to retire an integration must retain clearly defined business and technology owners.

• Does it have a technical and business owner?
• Is it known which systems and third parties consume it?
• Is there recent evidence of use or non-use? Is there a communicated change date and a limited rollback?

Frequently asked questions

When can an old API version be considered retired?

When there is sufficient evidence that it has no active consumers, the technical and business owners approve the decommissioning, affected processes have been verified, and the inventory reflects the retirement. The existence of a new version alone is not enough.

How long should an API be observed before retiring it?

There is no universal timeframe. It should be defined according to the frequency of the associated processes, their operational cycles, and the criticality of the service. What matters is that the period is agreed, authorised evidence sources are reviewed, and infrequent dependencies can be identified.

What should be done if it is not known who uses an old endpoint?

Classify it as pending confirmation. Gather authorised observation data, consult related teams and providers, and avoid switching it off until there is a documented decision. If its exposure or the data it processes increases the risk, prioritise its analysis and apply proportionate defensive controls while its situation is clarified.