What Are .well-known URIs?
The /.well-known/ path prefix is a reserved URI space defined by RFC 8615. It provides a standardized location on any web domain where machine-readable metadata files can be discovered without prior coordination. Instead of every service inventing its own convention for where to find configuration or policy documents, the /.well-known/ path offers a single, predictable namespace.
The IANA maintains a registry of well-known URI suffixes, ensuring that different standards don't accidentally collide in the same namespace.
Why This Matters
Before well-known URIs, developers had to hard-code locations or rely on out-of-band documentation to find things like security contacts, authorization server metadata, or WebFinger endpoints. Well-known URIs make the web more self-describing: automated systems — crawlers, identity libraries, AI agents, security scanners — can discover what a domain supports just by probing a known path.
Key Well-Known Files You Should Know
security.txt
Defined in RFC 9116, /.well-known/security.txt tells security researchers how to responsibly disclose vulnerabilities to you. A minimal example includes a Contact: field (email or web form URL) and an Expires: date. This is a quick win for any production domain — it signals that you take security seriously and gives researchers a clear path to reach you rather than going public.
openid-configuration
OIDC Discovery documents live at /.well-known/openid-configuration. Identity providers like Google, Okta, and Keycloak publish this JSON document so client libraries can auto-discover authorization endpoints, token endpoints, supported scopes, and signing key URLs without manual configuration.
webfinger
Used heavily in the Fediverse, /.well-known/webfinger accepts a query parameter (resource=acct:user@domain) and returns a JSON Resource Descriptor (JRD) linking to a user's ActivityPub actor profile. It's the discovery layer that makes cross-server federation work in Mastodon and similar platforms.
ai-plugin.json
OpenAI's plugin specification uses /.well-known/ai-plugin.json as the entry point for AI plugin discovery. When an AI system wants to know if a domain offers a plugin, it looks here first.
nodeinfo
/.well-known/nodeinfo is used by Fediverse software to advertise server metadata: software name, version, protocol support, and usage statistics. It allows network monitoring tools and other federated servers to understand what kind of node they're talking to.
gpc.json
The Global Privacy Control specification uses /.well-known/gpc.json to let websites declare their GPC support policy — specifically, whether they honor the GPC signal sent by browsers to opt out of the sale or sharing of personal data.
A Summary Table
| File | Standard | Purpose |
|---|---|---|
security.txt | RFC 9116 | Vulnerability disclosure contact |
openid-configuration | OIDC Discovery | Identity provider metadata |
webfinger | RFC 7033 | User/resource discovery for federation |
ai-plugin.json | OpenAI spec | AI plugin manifest |
nodeinfo | NodeInfo spec | Fediverse server metadata |
gpc.json | GPC spec | Privacy signal support declaration |
change-password | WICG | Link to change password page |
Serving Well-Known Files
There's no magic involved in serving these files — they're static JSON or text files served at specific paths. Key implementation notes:
- Serve with the correct
Content-Type(usuallyapplication/jsonortext/plain). - Ensure they are accessible over HTTPS — many specs require it.
- Set appropriate CORS headers (
Access-Control-Allow-Origin: *) so browser-based tools can fetch them. - Keep them up to date — stale metadata (especially expired
security.txt) is worse than none.
Implementing well-known URIs is one of the lowest-effort, highest-signal things you can do to make your domain a well-behaved participant in the open web ecosystem.