What Is .well-known

Content on WhatAnswers is provided "as is" for informational purposes. While we strive for accuracy, we make no guarantees. Content is AI-assisted and should not be used as professional advice.

Last updated: April 11, 2026

Quick Answer: The .well-known directory is a standardized URL path defined by RFC 5785 (2010) that allows websites to host configuration files and metadata at a predictable location without requiring prior knowledge of specific directory structures. It enables automated discovery of security configurations, service endpoints, and web standards compliance information for applications and services.

Key Facts

RFC 5785 standardized .well-known in 2010 as a universal discovery mechanism for web services
ACME protocol uses /.well-known/acme-challenge/ for domain validation in SSL/TLS certificate issuance
OAuth 2.0 and OpenID Connect implementations commonly use /.well-known/openid-configuration for service discovery
Android app linking verification uses /.well-known/assetlinks.json for app authenticity confirmation
Over 95% of modern websites support at least one .well-known endpoint for security or configuration purposes

Overview

The .well-known directory is a standardized URL path prefix that enables websites and web applications to publish configuration files and metadata at a predictable location. Defined by RFC 5785 in 2010, it provides a universal solution for service discovery without requiring clients to know the specific internal directory structure of a website.

Rather than scattering configuration files throughout a site's directory structure, the .well-known convention centralizes discoverable information in a single, standardized location. This approach benefits both website owners and client applications that need to automatically discover services, security policies, and configuration endpoints.

How It Works

The .well-known mechanism operates on a simple principle: place discoverable resources in a /.well-known/ directory at the root of a domain, allowing any client to access them using a predictable URL pattern.

Standardized Location: All .well-known resources are accessed via the /.well-known/ URL path at the domain root, ensuring consistency across different websites and services
Protocol Registration: Individual protocols and standards register their own subdirectories within .well-known (e.g., /.well-known/acme-challenge/, /.well-known/openid-configuration/) to avoid conflicts
Automatic Discovery: Client applications query the appropriate .well-known endpoint to retrieve configuration data without manual setup or configuration files
No Authentication Required: .well-known resources are typically publicly accessible and do not require authentication, allowing any client to discover available services
Content Format Flexibility: Different endpoints use different formats including JSON, text files, and XML depending on the specific use case and standard

Key Comparisons

.well-known Endpoint	Primary Purpose	File Format	Standard/Owner
/.well-known/acme-challenge/	SSL/TLS certificate validation for Let's Encrypt	Text files	ACME (Automated Certificate Management Environment)
/.well-known/openid-configuration	OAuth 2.0 and OpenID Connect service metadata discovery	JSON	OpenID Foundation
/.well-known/assetlinks.json	Android app linking and app authenticity verification	JSON	Google/Android
/.well-known/security.txt	Security contact information and vulnerability disclosure policies	Text file	RFC 9116 (2022)
/.well-known/webfinger	User profile and social identity discovery	JSON	RFC 7033

Why It Matters

The .well-known standard provides significant benefits for both website administrators and developers integrating web services. It reduces configuration complexity and enables automatic service discovery at scale.

Security Implementation: Enables automated SSL/TLS certificate validation through ACME protocol, which powers Let's Encrypt and reduced certificate costs from hundreds to free
Developer Experience: Simplifies OAuth 2.0 and OpenID Connect implementations by allowing client applications to automatically discover endpoints and capabilities
Standardization: Creates a single, predictable location for configuration files across different services, reducing implementation errors and support burdens
Scalability: Allows automated tools to discover and configure services without manual intervention, essential for modern DevOps and cloud-native architectures
Security Disclosure: RFC 9116's security.txt specification leverages .well-known to standardize how websites publish vulnerability disclosure policies and contact information

The widespread adoption of .well-known endpoints reflects their critical role in modern web infrastructure. Today, the majority of websites running Let's Encrypt certificates (over 300 million as of 2024) use /.well-known/acme-challenge/ for validation. Similarly, OAuth 2.0 providers including Google, Microsoft, and GitHub use /.well-known/openid-configuration as the standard endpoint for service discovery.