What Are Well-Known URIs?

The Well-Known URI standard (RFC 8615) defines a reserved path prefix — /.well-known/ — at the root of a web origin where machine-readable metadata and discovery documents can be reliably found. Rather than every service inventing its own location for configuration files, well-known URIs create a predictable, standardized convention.

Search engines, security researchers, federated social software, authentication systems, and AI crawlers all look for specific files under this path. Implementing the right ones signals that your site is standards-compliant and interoperable with the broader web ecosystem.

Essential Well-Known URIs You Should Implement

1. security.txt — Vulnerability Disclosure

Defined in RFC 9116, /.well-known/security.txt tells security researchers how to responsibly disclose vulnerabilities in your service. It's a plain text file with a small set of standardized fields:

Contact: mailto:security@yourdomain.com
Expires: 2025-12-31T23:59:59Z
Preferred-Languages: en
Policy: https://yourdomain.com/security-policy

Security researchers actively look for this file before (and sometimes instead of) contacting you through other channels. Without it, you may miss critical vulnerability reports.

2. openid-configuration — OIDC Discovery

If you operate an OpenID Connect Identity Provider, you must publish a discovery document at /.well-known/openid-configuration. This JSON document tells clients where your authorization endpoint, token endpoint, JWKS URI, and supported scopes live. Relying parties use it for zero-config integration.

3. webfinger — User Discovery

Used by the Fediverse, WebFinger (/.well-known/webfinger) allows lookup of user-associated metadata by account URI. It responds to queries like ?resource=acct:user@yourdomain.com with a JSON Resource Descriptor linking to the user's profile data. Required for Mastodon-compatible federation.

4. nodeinfo — Server Capabilities

/.well-known/nodeinfo is used by federated social platforms to advertise server software, protocols, and basic usage stats. It returns a JSON object with links to versioned NodeInfo documents. Third-party apps and network analysis tools use this for discovery.

5. robots.txt (Honorable Mention)

Technically at /robots.txt rather than /.well-known/, this venerable standard deserves mention. It instructs web crawlers which paths to index or skip. Modern AI training crawlers also respect robots.txt directives (with varying compliance). Keep it updated.

Implementing Well-Known URIs: Practical Steps

  1. Static files: For simple files like security.txt, place them directly in a public/.well-known/ directory. Most static hosting services will serve them automatically.
  2. Server routes: For dynamic endpoints like WebFinger (which must respond to query parameters), register an explicit route in your web framework: 
    app.get('/.well-known/webfinger', webfingerHandler)
  3. CORS headers: Many well-known endpoints are consumed cross-origin by browsers and external services. Add appropriate CORS headers: 
    Access-Control-Allow-Origin: *
  4. Content-Type: Return the correct MIME type. WebFinger responses use application/jrd+json, not plain application/json.
  5. HTTPS only: All well-known endpoints must be served over HTTPS. HTTP responses will be ignored or rejected by compliant clients.

Verifying Your Implementations

  • Use securitytxt.org to validate your security.txt.
  • Test WebFinger with Mastodon's search — search for your domain's user handle from any Mastodon instance.
  • Use the browser's Network DevTools to inspect responses, checking status codes, content types, and response bodies.
  • Check the IANA Well-Known URI Registry for the full list of registered suffixes.

A Small Investment, Significant Returns

Implementing well-known URIs takes less than an afternoon for most sites, yet it meaningfully improves your site's interoperability with security tools, federated platforms, authentication systems, and the broader web ecosystem. It's one of the highest-leverage standards investments you can make.