Alt-Svc

Protocol upgrades from HTTP/1.1 to HTTP/3 happen through alternative service discovery. The Alt-Svc response header advertises alternative services capable of handling future requests for the same origin, enabling HTTP/2 and HTTP/3 negotiation.

Table of Contents

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.

Browsers apply Alt-Svc mainly for HTTP/3 discovery. The upgrade from HTTP/1.1 to HTTP/2 happens through TLS ALPN during the handshake, with no header involved. HTTPS and SVCB DNS records are the emerging alternative, advertising HTTP/3 support before the first connection is made.

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

The bootstrap problem

Alt-Svc arrives inside a response, so learning about HTTP/3 costs one full connection over TCP first. The first visit negotiates TCP, TLS, and HTTP/2, reads the advertisement, and only later connections race QUIC. A cold client never starts on HTTP/3 through this header alone.

The alternative discovery path is the HTTPS DNS record, which delivers the protocol hint before any connection exists. Firefox ships the record and treats the entry the way a cached Alt-Svc value works. Safari queries the record and races QUIC on the hint. Chromium-based browsers query the record by default and read its ALPN list for HTTP/3 discovery, so the DNS record and this header work side by side, with the header covering resolvers limited to A and AAAA answers.

Cached entries govern the in-between visits. The default freshness is 24 hours, adjustable through ma, spent down by time already recorded in the Age header. Entries normally clear on a network change, and persist=1 hints the entry survives one. The special value clear wipes every stored alternative for the origin, including any advertised in the same response.

Trust never transfers. The alternative endpoint has to present a certificate valid for the origin hostname, so a CDN advertising an alternative on another name fails validation rather than silently rerouting.

Cloudflare zones advertise h3=":443"; ma=86400 on every response. Older documentation showing draft-version lists, h3-27 through h3-29, records a historical form the edge no longer sends.

See also

Last updated: August 17, 2026