The IANA Well‑Known URI Registry

Every time a browser or service requests a resource at a path beginning with /.well-known/, it is tapping into a standardized, machine‑readable directory that was designed to make the web more discoverable and secure. The Internet Assigned Numbers Authority (IANA) maintains a public registry of these URIs, documenting the specification, status, and controlling body for each entry.

Why a Dedicated Namespace Matters

  • Uniform discovery – Developers can rely on a single, predictable location to fetch configuration or metadata, reducing hard‑coded URLs.
  • Security by design – Many entries expose information that can be leveraged by attackers (e.g., security.txt), but the registry also defines how to publish protective data (e.g., mta‑sts.txt).
  • Interoperability – Protocols such as OAuth, OpenID Connect, and WebFinger use well‑known endpoints to negotiate capabilities without prior knowledge of the server’s layout.

A Quick Look at the Registry

URI Suffix Specification Status Controller
acme-challenge RFC8555 Permanent IETF
assetlinks.json Google’s Digital Asset Links Permanent Google Inc.
openid-configuration OpenID Connect Discovery Permanent OpenID Foundation
security.txt RFC9116 Permanent IETF
mta-sts.txt RFC8461 Permanent IETF
webfinger RFC7033 Permanent IETF
oauth-authorization-server RFC8414 Permanent IESG
nodeinfo Diaspora’s NodeInfo Provisional NodeInfo Developer Community
did.json W3C Credentials Community Group Provisional Credentials Community Group

(Full list available at the IANA website.)

How to Use a Well‑Known URI in Your Project

Below is a minimal example of how a Go HTTP server can expose a security.txt file and how a client might fetch it:

// server.go
package main

import (
    "net/http"
)

func main() {
    http.HandleFunc("/.well-known/security.txt", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        w.Write([]byte("Contact: [email protected]
Expires: 2026-12-31T23:59:59Z"))
    })
    http.ListenAndServe(":8080", nil)
}

# Client fetch
curl http://localhost:8080/.well-known/security.txt

The server’s response can be parsed by security tools to identify responsible parties and compliance dates.

The Evolution of the Registry

  • Early days – The first entries, such as acme-challenge (RFC8555), were created to simplify automated certificate issuance.
  • Growth in security – Entries like security.txt (RFC9116) and mta‑sts.txt (RFC8461) emerged as the web’s threat surface expanded.
  • Identity and trust – The rise of decentralized identifiers (DIDs) and OAuth‑based federation has added did.json, openid-configuration, and oauth-authorization-server.
  • Emerging standards – Provisional entries such as nodeinfo and did-configuration.json signal protocol pilots that may become permanent.

Implications for Developers

  1. Reduced friction – By exposing configuration at a known path, services can auto‑discover capabilities, cutting onboarding time.
  2. Security hygiene – Publishing security.txt or mta‑sts.txt becomes a best practice rather than an optional add‑on.
  3. Interoperability testing – Automated tests can fetch well‑known resources to validate compliance with standards.
  4. Future‑proofing – As new protocols adopt well‑known URIs, developers can adopt them with minimal changes to existing codebases.

Looking Ahead

The registry is already a living document; entries are added, updated, or deprecated as the web evolves. The IETF and W3C are actively working on new specifications (e.g., privacy-sandbox-attestations.json, gpc.json) that will further tighten privacy controls. For engineers, staying informed about the registry is not just a matter of curiosity—it is a prerequisite for building secure, interoperable, and standards‑compliant services.

Source: IANA Well‑Known URI Registry – https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml