Alt-Svc

The HTTP Alt-Svc response header advertises alternative services capable of handling future requests for the same origin, enabling protocol upgrades such as HTTP/2 and HTTP/3 discovery.

Table of Contents

Usage
Directives
Example
Takeaway
See also

Usage

Servers send the Alt-Svc header to inform clients about alternative endpoints offering the same resources over a different protocol, host, or port. The primary use case is protocol negotiation: an origin serving HTTP/1.1 responses uses Alt-Svc to tell the client about an HTTP/3 endpoint, allowing the client to switch on subsequent requests.

Alternative services are transparent to the end user. The browser address bar and document URL remain unchanged. The client stores the advertisement and routes future requests to the alternative endpoint until the max-age expires or the network configuration changes.

Multiple alternative services are listed in a single header value, separated by commas. The client selects the preferred option based on protocol support and network conditions.

Directives

clear

The clear directive invalidates all previously advertised alternative services for the origin. The client discards stored advertisements and reverts to the original endpoint.

Alt-Svc: clear

protocol-id

The protocol-id is an ALPN (Application-Layer Protocol Negotiation) identifier specifying the protocol spoken by the alternative service. Common values include h2 for HTTP/2 over TLS and h3 for HTTP/3 over QUIC.

A full list of ALPN identifiers is maintained by IANA.

alt-authority

The alt-authority is a quoted string containing the alternative host and port. The host portion is optional and defaults to the origin host when omitted. The port is required.

Alt-Svc: h3=":443"

ma

The ma (max-age) parameter defines the number of seconds the advertisement remains valid. After this period, the client stops routing to the alternative service and falls back to the original endpoint. When omitted, the default is 86400 seconds (24 hours).

persist

The persist=1 parameter instructs the client to keep the cached advertisement across network changes. Without this flag, clients clear alternative service entries when the network configuration changes, such as switching from Wi-Fi to a cellular connection.

Example

An origin advertising an HTTP/3 alternative on port 443. The client stores the advertisement for the default 24-hour period.

Alt-Svc: h3=":443"

An origin offering both HTTP/2 and HTTP/3 alternatives, each with a two-hour lifetime. The client picks the highest supported protocol.

Alt-Svc: h3=":443"; ma=7200, h2=":443"; ma=7200

An origin advertising an alternative on a different host and port with persistence enabled. The client retains the advertisement even after network changes.

Alt-Svc: h2="alt.example.re:8443"; ma=3600; persist=1

An origin clearing all previous advertisements. The client discards stored entries and returns to the original endpoint.

Alt-Svc: clear

Takeaway

The Alt-Svc header directs clients to alternative endpoints for future requests, serving as the primary mechanism for HTTP/3 discovery and protocol upgrades. Advertisements are time-limited and transparent to end users.