The Deprecation header tells clients a resource is, or will be, deprecated. The Sunset header tells them when it is expected to stop responding. Both are hints that help clients plan a move. They do not change how the API behaves, so you still need notices, monitoring and a plan.
Definitions and status
Deprecation is defined in RFC 9745, an IETF Standards Track document published in March 2025. Its value is a date in structured field form, such as a Unix timestamp with an at sign prefix. The date can be in the future or the past.
Sunset is defined in RFC 8594, published in May 2019 as an Informational RFC. Its value is a single HTTP date, and it should be in the future.
| Header | Meaning | Format | RFC status |
|---|---|---|---|
| Deprecation | Resource is or will be deprecated | Structured date, for example a Unix timestamp prefixed with an at sign | Standards Track |
| Sunset | Resource is expected to become unresponsive | HTTP date | Informational |
Rules worth knowing
- The Sunset date must not be earlier than the Deprecation date.
- Sunset is for decommissioning, and RFC 8594 says an API that is deprecated but still running should not use it.
- Clients should treat both as hints, not guarantees. After a sunset time, requests may fail with 4xx or 3xx responses, or the resource may be unreachable.
- A Link header with the relation
deprecationorsunsetcan point to migration guidance. - Sunset information can reveal planning details, so protect it as you would the resource itself.
An example response, in a code block:
Deprecation: @1788134399
Sunset: Fri, 31 Jul 2027 23:59:59 GMT
Link: [https://api.example.com/docs/migrate-v2](https://api.example.com/docs/migrate-v2); rel="deprecation"
The dates above are illustrative values, not a policy.
Why this is a security topic
OWASP API9 warns that attackers go after forgotten old versions and unpatched endpoints, and says to decide whether to backport fixes or retire older versions. Retirement is how you shrink that surface. OWASP's example of a beta host that lacked rate limiting shows what happens to versions nobody maintains.
A safe retirement plan
- Announce a deprecation date and publish migration guidance.
- Add the headers to every response from the old version.
- Track which clients still call it, using logs and API keys.
- Contact the heaviest remaining callers directly.
- Until retirement, keep applying protections to the old version too, as OWASP advises.
- On the sunset date, switch off and confirm with traffic data. Remove DNS and gateway routes.
See also retire or backport security fixes to old API versions.
Quick check
Will clients automatically stop using a deprecated API?
No. The headers are hints. Many clients ignore them, which is why you need usage tracking and direct outreach.
Do I need both headers?
No. Deprecation alone announces the status. Add Sunset when you have a firm decommission date.
Safeguard's free scan at gold.safeguard.sh/scan checks dependency risk in old versions that are still running.
Sources
- RFC 9745: The Deprecation HTTP Response Header Field
- RFC 8594: The Sunset HTTP Header Field
- OWASP API9:2023 Improper Inventory Management
Last reviewed: 19 October 2026.
