HTTP Subdomain Gateway Specification
Path gateways break the web origin model — every CID shares the gateway origin. Subdomain gateways are the production-correct choice for hosting independent sites. This is also the only model that makes single-page apps with cookies and Service Workers function on a public gateway.
What It Defines
Defines the gateway behavior where each CID or IPNS name lives on its own subdomain — `https://<cid>.ipfs.<gateway>` or `https://<name>.ipns.<gateway>` — instead of under a shared path. Subdomain isolation gives every site its own browser origin, which fixes the security model: cookies, localStorage, Service Workers, and Same-Origin Policy all work correctly because two pieces of IPFS content can no longer collide on a single origin. Requires CIDv1 in DNS-safe lowercase base32 so the CID can fit in the hostname label.
Canonical (Normative)
Convenient (Practical)
Open community of implementers (Protocol Labs, Shipyard, Boost, Helia, Kubo, and others) that maintains the InterPlanetary File System spec family at specs.ipfs.tech. Publishes content-addressing primitives (CID, Multihash, Multibase, Multiaddr), the IPLD data model, naming systems (IPNS, DNSLink), and the HTTP Gateway specs (Path, Subdomain, Trustless, DNSLink) that bridge content-addressed storage to ordinary browsers.
Related Specs
Every DNSLink record, IPFS gateway URL, IPNS publish, and Filecoin deal references content by CID. If you do not understand what the bytes after `/ipfs/` mean, you cannot debug deploy/cache issues, validate signed manifests, or design content-addressed pipelines.
Multibase is the reason CIDv1 strings are DNS-safe lowercase base32 and can therefore appear in subdomain gateway hostnames like `bafy….ipfs.example.com`. If you build URL routers or parsers that touch CIDs, you encode and decode through multibase.
Path gateways are how a regular browser without IPFS support fetches content-addressed data. Knowing the spec is required to operate a self-hosted gateway, debug 404/range/CORS issues, or build clients that fall back from native IPFS to HTTP gateways.
DNSLink alone tells nobody how a browser request actually turns into a served HTML page. The DNSLink Gateway spec is the contract between your DNS records and the gateway that browsers hit — required reading if you operate a custom gateway for user sites under a wildcard like `*.dial.wtf`.
Sessions, auth tokens, tracking, and CSRF defenses all run through cookies. Know SameSite, Secure, HttpOnly, and domain scoping to avoid security bugs.
Every browser-side API call to a different origin hits CORS. Misconfigured CORS is a top source of dev frustration and security holes.