Well-Known URIs Reference

Discover site metadata with well-known URIs

The /.well-known/ path prefix is a small but powerful corner of the web. Defined by RFC 8615, it reserves a predictable location under every origin where protocols can publish site-wide metadata: security contacts, OAuth and OpenID endpoints, federation records, certificate-validation tokens and more. Instead of every standard inventing its own URL, they all register a suffix with IANA and live under /.well-known/. This reference lets you search that registry, see what each path is for, and build the exact URL for your own host.

How it works

Each entry in the IANA Well-Known URIs registry has a registered suffix — the text that follows /.well-known/ — plus the application that uses it, a registry status (permanent or provisional), and the spec that defines it. The full address is always:

https://<host>/.well-known/<suffix>

For example, the security disclosure file is https://example.com/.well-known/security.txt, and OpenID Connect discovery lives at https://example.com/.well-known/openid-configuration. When you enter a host, the tool strips any scheme or path you paste and assembles the canonical HTTPS URL for each entry so you can copy it straight into a request.

The most important well-known URIs

Serving well-known files: practical requirements

Every well-known document must be:

1. Reachable at the apex origin. /.well-known/ is always relative to the root of the domain — not a subdirectory, not a CDN path. If your main site is at https://app.example.com, the security.txt goes at https://app.example.com/.well-known/security.txt, not https://example.com/.well-known/security.txt (unless both origins need to be covered).
2. Served over HTTPS without authentication. Automated clients — certificate authorities, federation servers, OAuth clients — cannot log in to fetch these files. Any 401 or 403 response means they cannot discover your metadata.
3. Returned with the correct Content-Type. security.txt must be text/plain; charset=utf-8. openid-configuration must be application/json. Returning HTML instead of plain text is a common deployment mistake that breaks clients silently.
4. Not cached too aggressively. For files that change (like ACME validation tokens or rotated JWKS keys), avoid long-lived cache headers. ACME challenge tokens in particular are created and deleted within minutes.

Specific notes on common entries

security.txt — RFC 9116 requires a signed file with at minimum a Contact: field and an Expires: date in ISO 8601 format. Many vulnerability scanners now flag missing or expired security.txt files. The file should be signed with PGP if practical, and Expires should be set no more than a year out and renewed annually.

acme-challenge — ACME HTTP-01 validation writes a random token to this path during certificate issuance. You do not host these files permanently; your ACME client (Certbot, acme.sh, Caddy, etc.) manages them automatically. Never configure a catch-all 200 response at this path as it will cause false validation successes.

apple-app-site-association — Apple fetches this on app install, not at runtime. It must be served with Content-Type: application/json (not .json extension logic) and with a 200 status — redirects may be ignored. The CDN or proxy serving it must not strip the body.

Tips

• Permanent vs provisional — Prefer permanent registrations when building something durable; provisional ones such as apple-app-site-association are conventions that work but are not yet locked to a single frozen spec.
• Use this tool’s URL builder to quickly confirm the exact path for your domain and paste it into curl -I to check that it returns 200 with the right Content-Type.
• Keep a checklist of the well-known files your origin serves and review them when renewing domains or migrating infrastructure — they are easy to forget in a platform migration.