Retire and respond

An API version is not retired when the documentation disappears. It is retired when callers and credentials can no longer reach it. Deleting /v1 documentation does not stop an old token from calling it.

Retire with evidence, not hope

Measure real use, announce a deadline, migrate clients, block new credentials, disable the deployment, and monitor attempted calls.

Start with who still depends on the old version:

# which credentials still call /v1?
grep ' /v1/' /var/log/nginx/access.log | awk '{print $3}' | sort | uniq -c | sort -rn
#  4102 key_mobile_prod_x91b   <- this client needs a migration plan
#     7 key_partner_acme_v22

Immediate shutdown reduces exposure, but measured migration may be needed for clients you cannot update instantly. A mobile app version already in the field takes months to drain.

When the deadline arrives, make the block explicit and permanent:

curl -i https://api.example.com/v1/invoices \
  -H "Authorization: Bearer $OLD_TOKEN"
# HTTP/1.1 410 Gone
# {"error":"v1 retired 2026-10-01, see /docs/migration-v2"}

After blocking the route, watch denied calls for an agreed period. That evidence reveals forgotten clients without reopening the version or trusting an inventory that may already be incomplete.

Rehearse the incident before you have one

For an incident, identify affected objects and identities, contain the path, preserve evidence, fix related routes, and communicate from facts.

The tenant-boundary rehearsal is worth running on purpose. Given the claim “tenant acme’s export leaked”, can you list which invoices were touched, by which credential, in what time range?

SELECT target, credential, ts FROM audit_events
WHERE tenant = 'acme' AND op LIKE '%export%'
  AND ts BETWEEN '2026-07-01' AND '2026-08-01';

If that query cannot be answered from today’s logs, you found the gap in a rehearsal instead of during a disclosure deadline. Fix the logging first; the response plan depends on it.

Record real /v1 traffic, credential owners, migration dates, and the final block rule. Call the route after retirement and prove it cannot mutate data, then rehearse identifying invoices touched by a leaked tenant boundary.