Skip to content
AdminKit

Well-known URI

What is Well-known URI?

A well-known URI is a resource published at a path beginning /.well-known/ on a host, under the registry RFC 8615 establishes so a new protocol can define a discoverable location for site-wide metadata. AdminKit's MCP server hardening checklist requires publishing OAuth metadata at two separate well-known URIs.

By AdminKit team, Netbase JSC · Updated

A well-known URI is a resource published at a path beginning /.well-known/ on a host, under the registry RFC 8615 establishes for exactly this purpose: letting a new protocol or specification define a standard, discoverable location for site-wide metadata without inventing a new DNS record type or coordinating with whatever content the host already serves. A specification that needs this kind of discovery registers its own suffix after /.well-known/ in IANA’s Well-Known URIs registry rather than picking an arbitrary path that might collide with something else already on the host; examples already in wide use include /.well-known/acme-challenge/ for ACME domain-control validation, the automated protocol a certificate authority uses to issue a TLS certificate; /.well-known/security.txt for a site’s security contact per RFC 9116, a practice OWASP’s Vulnerability Disclosure Cheat Sheet recommends for publishing a coordinated-disclosure contact; and /.well-known/oauth-authorization-server for OAuth 2.0 Authorization Server Metadata. Let’s Encrypt’s challenge types documentation shows the ACME case in practice: for the HTTP-01 challenge, the ACME client puts a file containing a token at http://<YOUR_DOMAIN>/.well-known/acme-challenge/<TOKEN>, and Let’s Encrypt then retrieves it to confirm control of the domain.

RFC 8615 obsoletes the earlier RFC 5785, which introduced the same convention with a narrower registration process. Despite the shared “well-known” name, this is a completely different registry from a well-known port: a well-known URI is a path on a specific host’s web server, registered in IANA’s Well-Known URIs registry, while a well-known port is a TCP/UDP port number reserved in IANA’s separate Service Name and Transport Protocol Port Number Registry under RFC 6335 — the two namespaces don’t interact, and a protocol can use either, both, or neither.

AdminKit groups well-known URI under its machine protocols cluster — browse the AdminKit glossary index for other related terms.

Frequently asked questions

What is a well-known URI?

A resource published at a path beginning /.well-known/ on a host, under the registry RFC 8615 establishes.

Why was the well-known URI registry created?

So a new protocol or specification can define a standard, discoverable location for site-wide metadata without inventing a new DNS record type or risking a path collision.

What is an example of a well-known URI already in wide use?

/.well-known/security.txt, which RFC 9116 defines for publishing a site's security contact information.

Is a well-known URI the same thing as a well-known port?

No -- despite the shared name, a well-known URI is a path on a specific host's web server, registered in a completely separate IANA registry from well-known ports.