What Are .well-known URIs?
If you've ever tried to verify ownership of a domain, configure an OpenID provider, or let security researchers contact your team, you've likely encountered the /.well-known/ path. This special URL prefix is a standardized convention defined in RFC 8615 by the IETF, and it acts as a well-defined "mailbox" for machine-readable metadata about a website or service.
In short, .well-known URIs are reserved paths on a web server that expose structured metadata to browsers, bots, identity providers, and other automated systems — without requiring custom routing logic or site-specific documentation.
Why Does This Standard Exist?
Before RFC 8615, services had no consistent way to publish machine-readable information about themselves. Developers placed configuration files wherever was convenient — at the root, under /meta/, or buried in a subdirectory. This created fragmentation: every service needed custom documentation for every integration.
The .well-known convention solves this by creating a single, predictable namespace. Any system — a browser, an AI agent, an identity provider — can reliably check https://example.com/.well-known/[resource-name] and expect a standardized response.
Common .well-known Endpoints
The IANA maintains a registry of well-known URIs. Here are some of the most widely deployed:
| Path | Purpose | Defined By |
|---|---|---|
/.well-known/openid-configuration | OpenID Connect discovery document | OpenID Foundation |
/.well-known/security.txt | Security contact and disclosure policy | RFC 9116 |
/.well-known/change-password | Redirects to the site's change-password page | W3C / WHATWG |
/.well-known/webfinger | User/resource discovery (used by ActivityPub) | RFC 7033 |
/.well-known/nodeinfo | Fediverse server metadata | NodeInfo spec |
/.well-known/ai-plugin.json | AI plugin manifest (ChatGPT plugins) | OpenAI (de facto) |
/.well-known/jwks.json | JSON Web Key Sets for token verification | RFC 7517 |
How to Implement a .well-known Endpoint
Adding a .well-known resource to your server is straightforward. The process depends on your stack, but the general pattern is:
- Create the file or route: Place a static file or dynamic handler at the appropriate path under
/.well-known/. - Set the correct Content-Type: Most resources should return
application/jsonortext/plaindepending on the spec. - Serve over HTTPS: Well-known endpoints must be served over TLS for security-sensitive use cases.
- Check CORS headers: Some discovery endpoints need
Access-Control-Allow-Origin: *to be readable cross-origin.
Security Considerations
While .well-known paths are public by design, there are a few security points to keep in mind:
- Don't expose internal paths: Only publish information that is intentionally public. A discovery document should not reveal infrastructure details you wouldn't put in a public README.
- Validate inputs: If your well-known endpoint is dynamically generated, treat all query parameters as untrusted input.
- Keep data current: Stale keys in a JWKS endpoint or expired contact details in
security.txtcan break integrations or misdirect vulnerability reports.
The Growing Importance of .well-known in the AI Era
As AI agents and automated systems increasingly crawl and interact with the web, /.well-known/ paths are becoming more critical. Files like ai-plugin.json and emerging agent discovery specs rely on this convention to allow AI tools to understand a site's capabilities without human guidance. Developers building API-first products should treat these endpoints as a first-class part of their architecture.
Summary
The /.well-known/ URI prefix is one of the web's most useful — and underappreciated — standards. It provides a consistent, machine-readable discovery layer for identity, security, AI capabilities, and more. If you're building anything that interacts with the broader web ecosystem, understanding and implementing .well-known endpoints is an essential skill.