Understanding the .well-known directory on the web

What is .well-known?

A standard location on the web

The .well-known directory is a conventional path defined by web standards for hosting small, publicly discoverable resources. When a server serves a file under https://example.com/.well-known/, clients can retrieve it in a predictable way. The purpose is to provide a single, predictable place for services to look up configuration, verification data, or metadata.

Why the name starts with a dot

The dot in the directory name signals a special, often hidden, location in Unix-like systems. On the web, it’s used as a convention to indicate that the resources under this path are not interactive content but machine-readable data.

Common uses of .well-known

ACME verification and TLS certificates

Certificate authorities and clients use the ACME protocol to prove control of a domain. During validation, the CA requests a token from a path like /.well-known/acme-challenge/TOKEN. The server must respond with the token's contents to prove control; once validated, a certificate can be issued.

Security and privacy resources

The security.txt file at /.well-known/security.txt lets security researchers reach the site owners. It contains contact details, encryption methods, and other policy information in a machine-readable format.

Other conventions and tools

Other standard resources live under this directory, such as .well-known/webfinger for user discovery in federated systems, or .well-known/openid-configuration for OpenID Connect discovery. These paths make it easier for clients to learn how to interact with a domain.

Security and privacy considerations

• Public access: resources under .well-known are typically public; avoid including sensitive data there.
• Access control: if you need to restrict access, implement proper authentication and reference only non-sensitive data.
• Disable directory indexing: ensure servers do not reveal a directory listing if a file is missing.
• Use HTTPS: serve all .well-known content over TLS to prevent tampering.

How web servers serve .well-known

• Path mapping: .well-known is served like any other URL path; the files live in the server’s document root or a configured directory.
• Apache: you can place files in the document root, or use an Alias to point / .well-known to another location.
• Nginx: a simple location / .well-known block will serve files from a designated directory.
• Defaults: if the file is missing, the server returns 404; if a redirect is used, ensure the target remains public.

Best practices

• Keep only non-sensitive, machine-readable files in .well-known.
• Use clear filenames that reflect their purpose (for example, acme-challenge tokens, security.txt).
• Test accessibility from multiple networks and ensure no accidental redirects break discovery.
• Prefer HTTPS to protect integrity and privacy.