What Are Well-Known URIs?
The /.well-known/ directory is a standardized location on web servers for hosting metadata and configuration files that describe the capabilities, policies, and contact information of a website or application. Defined in RFC 8615, the well-known URI registry is maintained by IANA and has grown to encompass dozens of specifications across security, identity, privacy, and discoverability.
Instead of different services placing configuration files at arbitrary paths — which causes collisions and discoverability problems — well-known URIs provide a predictable namespace. Clients, crawlers, automated tools, and other services know exactly where to look.
Key Well-Known URIs Every Developer Should Know
security.txt — Vulnerability Disclosure
Path: /.well-known/security.txt
Standard: RFC 9116
Provides security researchers with contact information and disclosure policies. A signed security.txt is the standard way to receive vulnerability reports responsibly.
openid-configuration — OIDC Discovery
Path: /.well-known/openid-configuration
Standard: OpenID Connect Discovery 1.0
Returns a JSON document describing an OpenID Provider's capabilities: token endpoint, authorization endpoint, JWKS URI, supported scopes, and more. Every OIDC provider must implement this. Clients use it to automatically configure themselves without hardcoded endpoint URLs.
oauth-authorization-server — OAuth 2.0 Metadata
Path: /.well-known/oauth-authorization-server
Standard: RFC 8414
Similar to OIDC Discovery but for OAuth 2.0 servers that don't implement OIDC. Returns authorization server metadata including supported grant types, response types, and endpoint URLs.
gpc.json — Global Privacy Control
Path: /.well-known/gpc.json
Standard: GPC Specification
A machine-readable disclosure that the site honors the Global Privacy Control signal. Regulators and privacy tools check this to verify compliance with CCPA/CPRA opt-out requirements.
assetlinks.json — Android App Links
Path: /.well-known/assetlinks.json
Standard: Android Digital Asset Links
Allows Android apps to verify they are associated with a website domain. Required for Android App Links to work — verified deep links that open directly in an app without browser disambiguation. The file contains the app's package name and certificate fingerprint.
apple-app-site-association — iOS Universal Links
Path: /.well-known/apple-app-site-association
Standard: Apple Universal Links
The iOS equivalent of assetlinks.json. Defines which paths on your website should open in your iOS app. Apple's CDN fetches this file when apps are installed; it must be served without redirects and with the correct MIME type (application/json).
change-password — Password Manager Integration
Path: /.well-known/change-password
Standard: WHATWG Spec
A simple redirect to your site's password change page. Password managers and browsers use this to help users navigate directly to where they can update their credentials, improving security hygiene. Implementation is trivial — return a 301/302 redirect to your actual change-password URL.
nodeinfo — Federated Social Web
Path: /.well-known/nodeinfo
Standard: NodeInfo Protocol
Used by federated social platforms (Mastodon, Pleroma, Misskey, etc.) to advertise server capabilities and software version. Returns a JSON object pointing to versioned NodeInfo documents. Relevant if you're building ActivityPub-compatible software.
Implementation Best Practices
- Serve all well-known files over HTTPS. Plaintext versions can be tampered with.
- Use correct Content-Type headers. JSON files need
application/json; text files needtext/plain; charset=utf-8. Mismatched types cause silent failures in automated clients. - Avoid redirects for security-critical files. Apple, Google, and several spec parsers do not follow redirects when fetching well-known files.
- Keep files up to date. Stale expiry dates in security.txt, outdated cert fingerprints in assetlinks.json — these cause real breakage.
- Monitor with automation. Add well-known endpoints to your uptime monitoring. A missing
openid-configurationwill break all OIDC logins silently.
Well-Known URI Quick Reference
| URI | Purpose | Standard |
|---|---|---|
| security.txt | Vuln disclosure contacts | RFC 9116 |
| openid-configuration | OIDC provider metadata | OIDC Discovery 1.0 |
| oauth-authorization-server | OAuth 2.0 server metadata | RFC 8414 |
| gpc.json | GPC compliance disclosure | GPC Spec |
| assetlinks.json | Android App Links | Digital Asset Links |
| apple-app-site-association | iOS Universal Links | Apple AASA |
| change-password | Password change redirect | WHATWG |
| nodeinfo | Federated server metadata | NodeInfo |
Implementing the well-known URIs relevant to your application is a sign of a mature, interoperable, security-conscious deployment. Start with security.txt and OIDC discovery, then layer in the rest as your application's features demand.