Well-known URIs
The /.well-known/ path prefix is a standardised place to publish site-level metadata. RFC 8615 defines it; IANA keeps the registry of allowed names.
What it is
A well-known URI is a resource served from a fixed path under /.well-known/ on your origin. RFC 8615 reserves this prefix so that protocols and tools can probe a site for capabilities without guessing URLs or polluting the root namespace.
https://example.com/.well-known/change-password
https://example.com/.well-known/security.txt
https://example.com/.well-known/webfinger?resource=acct:[email protected]The names allowed under /.well-known/ are not arbitrary. IANA maintains a public registry; new names go through a review process. If you publish at a name that is not registered, you are claiming a path that may later be assigned to someone else.
Why it matters
- Discoverability. Clients, browsers, password managers, federated servers, mobile operating systems and crawlers know exactly where to look. They do not need configuration per site.
- Interoperability. Standardised paths are what let Mastodon, Apple, Google, OpenID Connect, ACME (Let’s Encrypt) and others work across millions of sites without coordination.
- Stability. The reserved prefix keeps protocol metadata out of the way of your application’s routing. You will not accidentally collide with
/security.txtif it lives under/.well-known/.
How to implement
- Serve the resource over HTTPS on the canonical host.
- Use the exact path and filename the spec defines. Case matters on most servers.
- Set the correct Content-Type (often
application/json, sometimes plain text or JSON variants likeapplication/jrd+json). - Return HTTP 200 with the body, or follow the spec where it allows a redirect (for example,
change-password). - Allow your CDN, firewall and authentication middleware to pass through. A well-known URI behind a login wall is invisible.
- Do not invent new names. If you need a new well-known URI, register it via the IETF process described in RFC 8615 §3.
Common mistakes
- Publishing under
/well-known/(no leading dot). The spec requires/.well-known/. - Serving the file with
Content-Type: text/htmlbecause a framework wrapped it. - Requiring authentication, blocking by user-agent, or rate-limiting probes so aggressively that legitimate clients fail.
- Using a name not in the IANA registry. Custom names belong elsewhere.
Verification
curl -I https://example.com/.well-known/<name>should return200and the correct content type.- Confirm the name appears in the IANA registry.
- Probe from a network outside your own to catch firewall and WAF rules.