Glossary
Well-known URI
A well-known URI is a path under `/.well-known/` reserved by RFC 8615 for site-wide metadata that a client needs to find without being told where it is. The problem it solves is coordination: several protocols each need a file at a fixed location on every host, and without a reserved namespace each one would claim a different root path and collide with real content. The suffixes are registered with IANA, so the namespace does not fragment.
What lives there
`security.txt` — contact details for reporting a vulnerability.
`acme-challenge/` — the token a certificate authority reads to verify domain control during automated issuance.
`change-password` — a URL browsers and password managers use to send a user directly to the password change page.
`openid-configuration` — the discovery document for an OpenID Connect provider.
`mta-sts.txt` — the SMTP transport policy, served from the `mta-sts` subdomain.
`assetlinks.json` and `apple-app-site-association` — the declarations linking a website to mobile applications for deep linking.
`dnt-policy.txt`, `host-meta` and a long tail of protocol-specific documents, each registered so that no two claim the same name.
Why the namespace is reserved
Before it existed, each protocol claimed its own root path, and a site with content at that path had a conflict it could not resolve.
One reserved prefix means a site has one directory to think about rather than a growing list of root files.
Registration with IANA means two protocols cannot claim the same suffix, which is the coordination the registry exists for.
A leading dot in the directory name is a conventional signal that it is infrastructure rather than content, and it keeps the path out of the way of ordinary URLs.
How to serve it correctly
Each file needs its documented content type. A JSON discovery document served as HTML is unreadable to the client that needs it.
It must be reachable over HTTPS without authentication and without a redirect to a login page.
It must not be blocked by robots.txt or a firewall rule, since the clients reading it are automated.
Some servers hide dot-directories by default, which is the usual reason a correctly placed file returns 404.
What to check
`curl -I https://example.com/.well-known/security.txt` and the same for any other file you expect to be there.
A 404 for `acme-challenge` during certificate renewal is the classic failure, usually caused by a redirect rule applied before the path is served.
Directory listing must be off for the directory: the files are meant to be fetched by name, not enumerated.
Check the content type of each file, which is the defect a browser check never reveals because a browser displays text regardless.
Check them on every hostname that needs them rather than only on the main one. The path is per host, so a subdomain serving an application has its own set to get right.
Frequently asked questions
- What is the /.well-known/ directory for?
- Site-wide metadata that clients must find at a predictable path: security contacts, certificate validation tokens, protocol discovery documents.
- Why does my ACME challenge return 404?
- Usually a redirect rule applied before the path is served, or a server configured to hide directories whose names begin with a dot.
- Can I put my own files there?
- The namespace is for registered suffixes. An unregistered file will not collide today and risks doing so later, so ordinary paths are better.
Sources
Related
VeriFixScan crawls a site and applies its checks to every page it reaches, keeping the evidence behind each finding. Scanning one website is free.
Scan a website