Well-Known URIs

Well-known URIs are standardized paths under the /.well-known/ prefix where websites expose machine-readable metadata about their services, policies, and capabilities. The mechanism gives clients a predictable location to find site-wide information without probing random paths or relying on ad-hoc conventions.

Table of Contents

Usage

Before well-known URIs existed, every protocol and service invented its own discovery path. Certificate authorities looked for validation tokens at arbitrary locations. Identity providers published configuration at provider-specific endpoints. Security researchers had no reliable place to find vulnerability disclosure contacts.

The /.well-known/ prefix solves this by reserving a single directory at the root of an origin for metadata resources. A client requesting https://example.re/.well-known/security.txt knows exactly where to look, regardless of the site's structure or technology stack.

The prefix works with HTTPS, HTTP, WebSocket (ws and wss), and CoAP URI schemes. Each scheme must explicitly opt in to supporting well-known URIs. Schemes not listed in the IANA URI Schemes registry as supporting the mechanism are excluded.

Root origin only

Well-known URIs exist only at the root of an origin. The path /.well-known/security.txt is valid, but /blog/.well-known/security.txt is not. No default resource is defined at /.well-known/ itself.

Supported URI schemes

The well-known URI mechanism is not universal across all URI schemes. A scheme must explicitly declare support. The IANA URI Schemes registry tracks which schemes opt in.

Currently supported schemes:

  • http / https -- the original and primary target of the mechanism
  • ws / wss -- WebSocket schemes, enabling discovery of WebSocket-related metadata
  • coap / coaps -- Constrained Application Protocol for IoT devices, along with TCP and WebSocket transport variants (coap+tcp, coap+ws, coaps+tcp, coaps+ws)

Registration

The IANA Well-Known URIs registry tracks all registered suffixes. Adding a new well-known URI requires a specification document and follows a "Specification Required" review process evaluated by designated experts. Each registration includes:

  • URI suffix -- the path segment after /.well-known/ (must conform to the segment-nz production from URI syntax, meaning no forward slashes)
  • Change controller -- the organization or individual responsible for the entry
  • Reference -- the specification defining the resource format and media type
  • Status -- permanent or provisional

Permanent entries come from stable specifications with broad implementation. Standards Track RFCs automatically receive permanent status. Provisional entries are less established and risk removal if unused.

Registrations are expected to use specific, descriptive names. Generic terms like /.well-known/metadata are discouraged to prevent namespace conflicts. A name like /.well-known/acme-challenge clearly signals its purpose.

Common well-known URIs

The IANA registry contains over 100 entries. The following are among the most widely deployed, grouped by function.

Security and trust

URI suffix Purpose
security.txt Vulnerability disclosure policy in plain text. Contains contact information, encryption keys, preferred languages, and an expiration date.
acme-challenge Domain validation for TLS certificate issuance via the ACME protocol. Certificate authorities retrieve a token from this path to verify domain ownership.
pki-validation Certificate authority domain validation files, used by CA/Browser Forum baseline requirements for non-ACME validation methods.
mta-sts.txt Mail Transport Agent Strict Transport Security policy. Email servers fetch this to enforce TLS on SMTP connections for the domain.
gpc.json Global Privacy Control signal. Indicates whether the site respects the GPC opt-out preference for data selling and sharing.

Identity and authentication

URI suffix Purpose
openid-configuration OpenID Connect discovery document. Identity providers publish a JSON document listing authorization endpoints, supported scopes, and signing algorithms.
oauth-authorization-server OAuth 2.0 authorization server metadata. Equivalent to openid-configuration for OAuth servers not using OpenID Connect.
webfinger Account discovery for federated protocols. Accepts a resource query parameter (typically an acct: URI) and returns JSON describing the account.
webauthn Related origins list for WebAuthn credentials. Allows passkeys registered on one origin to work across related origins under the same relying party.
change-password Redirects to the site's password change page. Password managers use this path to guide users directly to the correct form.

Mobile app linking

URI suffix Purpose
apple-app-site-association iOS Universal Links (Apple convention, not IANA-registered). A JSON file associating a domain with Apple apps, enabling direct app navigation from web links without disambiguation prompts.
assetlinks.json Android App Links (Digital Asset Links). A JSON file declaring associations between a website and Android applications for verified deep links.

Federation and discovery

URI suffix Purpose
nodeinfo Fediverse server metadata. Returns links to a JSON document describing the software, version, protocols, and usage statistics of a federated server.
host-meta Web Host Metadata in XML or JSON format. A bootstrap mechanism for WebFinger and other discovery protocols.
matrix Matrix federation server discovery. Directs clients and other servers to the appropriate homeserver endpoints.
api-catalog API discovery endpoint. Returns a Linkset document listing available APIs, documentation links, and version information.

Calendar and contacts

URI suffix Purpose
caldav [[webdav
carddav [[webdav

robots.txt is not a well-known URI

The file /robots.txt lives at the site root, not under /.well-known/. The robots.txt convention predates the well-known URI mechanism and is not part of the IANA registry. The same applies to /sitemap.xml, /favicon.ico, and /humans.txt.

Examples

A certificate authority validates domain ownership during TLS certificate issuance. The ACME client places a token at the challenge path, and the CA retrieves the expected value over plain HTTP on port 80.

GET /.well-known/acme-challenge/YnVzaW5lc3M HTTP/1.1
Host: example.re

HTTP/1.1 200 OK
Content-Type: application/octet-stream

YnVzaW5lc3M.dGhpcyBpcyBhIHRva2Vu

The response body contains the token concatenated with a thumbprint of the account key. The CA compares this value against the expected token to confirm the requester controls the domain.

OpenID Connect discovery

An OpenID Connect relying party fetches the provider's discovery document to learn the authorization endpoint, token endpoint, and supported grant types. This eliminates hardcoded endpoint configuration.

GET /.well-known/openid-configuration HTTP/1.1
Host: auth.example.re
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer": "https://auth.example.re",
  "authorization_endpoint": "https://auth.example.re/authorize",
  "token_endpoint": "https://auth.example.re/token",
  "userinfo_endpoint": "https://auth.example.re/userinfo",
  "jwks_uri": "https://auth.example.re/.well-known/jwks.json",
  "response_types_supported": ["code", "token"],
  "subject_types_supported": ["public"]
}

The jwks_uri field points to the JSON Web Key Set containing public keys for verifying token signatures. Clients use this document to configure themselves automatically.

Vulnerability disclosure

A security researcher or automated scanner checks for a vulnerability disclosure policy.

GET /.well-known/security.txt HTTP/1.1
Host: example.re

HTTP/1.1 200 OK
Content-Type: text/plain

Contact: mailto:security@example.re
Preferred-Languages: en
Canonical: https://example.re/.well-known/security.txt
Expires: 2027-01-01T00:00:00.000Z

The Contact field is required. Expires is also required and ensures stale policies are not used indefinitely. Canonical indicates the authoritative location of the file, protecting against tampering through unauthorized copies.

SEO and security.txt

Search engine crawlers index /.well-known/security.txt on some sites. Having a valid security.txt signals operational maturity, and some security rating services factor its presence into trust scores.

Password change redirect

A password manager directs a user to the change-password page. The well-known path returns a redirect to the actual form location.

GET /.well-known/change-password HTTP/1.1
Host: example.re

HTTP/1.1 302 Found
Location: https://example.re/account/password

The redirect target is the site's real password change form. The well-known path acts as an indirection layer so password managers do not need site-specific knowledge.

Fediverse server discovery

A Fediverse client discovers server metadata through the nodeinfo endpoint. The initial response provides a link to the full nodeinfo document.

GET /.well-known/nodeinfo HTTP/1.1
Host: social.example.re
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "links": [
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.0",
      "href": "https://social.example.re/nodeinfo/2.0"
    }
  ]
}

The href points to the actual nodeinfo document, which contains software name, version, protocol support, active user counts, and post statistics.

WebFinger account lookup

A Mastodon instance resolves a user handle to an ActivityPub actor URI through WebFinger.

GET /.well-known/webfinger?resource=acct:alice@social.example.re HTTP/1.1
Host: social.example.re
Accept: application/jrd+json

HTTP/1.1 200 OK
Content-Type: application/jrd+json

{
  "subject": "acct:alice@social.example.re",
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://social.example.re/users/alice"
    }
  ]
}

The resource query parameter accepts an acct: URI. The response contains a JSON Resource Descriptor with links to the user's profile in various formats. Fediverse software like Mastodon, Pleroma, and Misskey relies on WebFinger for cross-server user discovery.

Security considerations

Well-known URIs expose metadata about a server's capabilities and configuration. Several risks accompany their deployment.

Access control

On shared hosting environments where multiple tenants share an origin, write access to the /.well-known/ directory is critical. An unauthorized tenant writing to this directory risks impersonating the site's security policy, hijacking certificate validation, or publishing fraudulent app association files. Server operators restrict write access to /.well-known/ with the same rigor applied to other security-sensitive paths.

Information disclosure

Resources under /.well-known/ are accessible via normal HTTP requests. Automated scanners routinely probe common well-known paths. Any information placed at these endpoints is effectively public. Sensitive data never belongs in a well-known resource without encryption or access controls.

Browser exposure

Well-known URIs served over HTTPS are reachable by web browsers. Specifications defining new well-known URIs account for cross-site scripting and cross-origin data leakage. Best practices for well-known resources served over HTTP/HTTPS include:

  • Using Content-Type values like application/json or text/plain (not text/html)
  • Sending X-Content-Type-Options: nosniff to prevent MIME type sniffing
  • Applying Content-Security-Policy headers
  • Avoiding compression on sensitive data to prevent compression side-channel attacks

DNS rebinding

An attacker performing a DNS rebinding attack tricks a browser into fetching well-known resources from an internal server. Specifications relying on well-known URIs for sensitive operations require HTTPS to mitigate this risk.

Scope ambiguity

Applications using well-known URIs must define the scope of the metadata they serve. A well-known resource at example.re does not automatically apply to sub.example.re or other.example.re. Each specification defines its own scoping rules. Applying metadata from one hostname to another without explicit authorization creates administrative and security risks.

Implementing a well-known URI

Serving a well-known resource requires configuring the web server to respond at the appropriate path under /.well-known/. For static files like security.txt, place the file in a .well-known directory at the document root. For dynamic resources like openid-configuration, configure a route handler.

Nginx configuration for serving security.txt:

location = /.well-known/security.txt {
    alias /var/www/example.re/.well-known/security.txt;
    default_type text/plain;
}

Applications behind a reverse proxy ensure the proxy passes /.well-known/ requests through to the backend rather than returning a 404 or blocking the path.

No redirects for some well-known URIs

Certain well-known URIs (notably apple-app-site-association and assetlinks.json) must be served directly over HTTPS without any redirects. The verifying client (iOS, Android) rejects responses behind redirects. ACME HTTP-01 challenges are fetched over plain HTTP on port 80.

Takeaway

Well-known URIs provide a standardized discovery mechanism for site-wide metadata, replacing ad-hoc path conventions with a single, registered namespace under /.well-known/. From TLS certificate validation and identity provider configuration to vulnerability disclosure and Fediverse federation, the mechanism gives clients a predictable location to find the information needed to interact with a service. The IANA registry tracks over 100 registered suffixes across security, identity, mobile app linking, and protocol discovery use cases.

See also

Last updated: March 11, 2026