What Are .well-known Endpoints?
The /.well-known/ URI prefix (defined in RFC 8615) is a standardized location on web servers where machine-readable metadata files live. From OIDC discovery documents to Apple's app site associations, a growing ecosystem of protocols relies on these well-known paths to enable automatic discovery, verification, and federation.
If you're building any kind of web service that integrates with external systems — authentication providers, mobile apps, federated social networks, security scanners, or AI agents — you'll almost certainly need to deploy at least one /.well-known/ file.
The Most Important .well-known Files
| File Path | Standard | Purpose |
|---|---|---|
/.well-known/openid-configuration | OpenID Connect | OIDC provider discovery document |
/.well-known/security.txt | RFC 9116 | Security vulnerability reporting contact |
/.well-known/webfinger | RFC 7033 | Identity/resource discovery (used by ActivityPub) |
/.well-known/nodeinfo | NodeInfo | Fediverse server metadata |
/.well-known/assetlinks.json | Android App Links | Domain-to-Android app verification |
/.well-known/apple-app-site-association | Apple Universal Links | Domain-to-iOS app verification |
/.well-known/ai-plugin.json | ChatGPT Plugins | AI plugin manifest discovery |
/.well-known/change-password | WHATWG | Password manager redirect target |
Serving .well-known Files Correctly
Content-Type Headers Matter
Most .well-known files should be served as application/json. A few (like security.txt) should be text/plain. Getting this wrong can silently break integrations — browsers and consuming services often check Content-Type before parsing.
HTTPS Only
All .well-known endpoints must be served over HTTPS. If your server still serves HTTP, redirect to HTTPS using a 301 before the path is resolved. Some protocols (like OIDC) will outright reject non-HTTPS discovery documents.
CORS Configuration
Many .well-known files are fetched client-side by JavaScript running on other domains. Add appropriate CORS headers — typically Access-Control-Allow-Origin: * — to public discovery documents to prevent cross-origin blocking.
WebFinger: The Discovery Protocol Behind ActivityPub
WebFinger deserves special attention. It's a query protocol that resolves a resource identifier (like user@example.com) into structured metadata. ActivityPub uses it to resolve @user@instance.social into an actor URL.
A WebFinger request looks like: GET /.well-known/webfinger?resource=acct:alice@example.com
The response is a JRD (JSON Resource Descriptor) that includes links to the user's ActivityPub actor, profile page, and other endpoints. If you're building any Fediverse-compatible service, WebFinger is non-negotiable.
NodeInfo: Advertising Your Server's Capabilities
NodeInfo is used by Fediverse tools and directories to discover metadata about server software. The /.well-known/nodeinfo file is a simple pointer to a versioned NodeInfo document that contains:
- Which software is running and its version
- Supported protocols (e.g., ActivityPub, Diaspora)
- Usage stats (optional, can be set to zero for privacy)
- Whether registrations are open
Nginx Configuration Example
For most static .well-known files, you can configure Nginx to serve them directly from a directory:
location /.well-known/ {
root /var/www/well-known;
default_type application/json;
add_header Access-Control-Allow-Origin *;
add_header Cache-Control "public, max-age=3600";
}Keeping Your .well-known Files Up to Date
Discovery documents are often cached aggressively. Set sensible cache headers (1 hour to 24 hours for stable files), but be mindful that consumers may cache for longer. When rotating keys or changing endpoints referenced in discovery documents, use a deprecation period where both old and new values are valid simultaneously.
Treat your /.well-known/ directory as first-class infrastructure. It's the address book of the open web — keep it accurate, available, and well-maintained.