If you’ve ever configured SSL certificates, mobile app verification, password managers, or security policies, you’ve probably encountered a URL like this:

https://example.com/.well-known/

At first glance, it looks like just another directory on a web server. In reality, .well-known is a standardized location that allows websites to expose important metadata and configuration files in a predictable way.

This small convention enables browsers, search engines, certificate authorities, applications, and other services to automatically discover information without requiring custom URLs or APIs.

What Is the .well-known Directory?

The .well-known directory is a standardized URI path defined by RFC 8615.

Instead of every application inventing its own discovery endpoint, all applications can publish configuration files under:

https://yourdomain.com/.well-known/

This creates a single, universally recognized location for machine-readable information.

For example:

https://example.com/.well-known/security.txt
https://example.com/.well-known/assetlinks.json
https://example.com/.well-known/apple-app-site-association

Each file serves a specific purpose and follows its own specification.

Why Was It Introduced?

Before .well-known, different applications required different URLs:

https://example.com/security
https://example.com/api/config
https://example.com/mobile-verification
https://example.com/special-file

There was no consistency.

The .well-known standard solved this problem by providing:

• A predictable location
• Easier automatic discovery
• Better interoperability
• Simpler integration between services

Common Use Cases

SSL Certificate Validation (ACME)

Services like Let’s Encrypt use:

/.well-known/acme-challenge/

to verify domain ownership.

Example:

https://example.com/.well-known/acme-challenge/abc123xyz

If the validation file is accessible, the certificate authority knows you control the domain.

Security Contact Information

Organizations can publish:

/.well-known/security.txt

Example:

Contact: mailto:security@example.com
Expires: 2027-01-01T00:00:00Z
Preferred-Languages: en

Security researchers can quickly find where to report vulnerabilities.

Android App Verification

Android App Links use:

/.well-known/assetlinks.json

Example:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:..."
      ]
    }
  }
]

This verifies that the website and Android application belong together.

Apple Universal Links

Apple devices look for:

/.well-known/apple-app-site-association

This enables links like:

https://example.com/profile/123

to automatically open the corresponding iOS application instead of the browser.

Password Change Discovery

Some password managers support:

/.well-known/change-password

which redirects users directly to the site’s password update page.

Instead of searching through account settings, users can be taken directly to:

https://example.com/change-password

Directory Structure

A typical .well-known directory might look like:

public/
│
├── index.html
├── images/
├── css/
└── .well-known/
    ├── security.txt
    ├── assetlinks.json
    ├── apple-app-site-association
    ├── change-password
    └── acme-challenge/

How to Create One

Simply create a folder named:

.well-known

inside your website’s public root.

Example:

/var/www/html/.well-known/

or

public/.well-known/

depending on your framework.

Server Configuration Tips

Nginx

location /.well-known/ {
    allow all;
}

Apache

<Directory "/var/www/html/.well-known">
    Require all granted
</Directory>

Ensure hidden files and directories beginning with . are not accidentally blocked.

Best Practices

Use HTTPS

Always serve .well-known resources over HTTPS whenever possible.

Follow Official Specifications

Each file has its own format and requirements.

Examples:

• security.txt uses a text format.
• assetlinks.json requires valid JSON.
• apple-app-site-association has strict formatting rules.

Keep Files Public

These files are intended for automated discovery and should generally be accessible without authentication.

Keep Information Current

Expired certificates, outdated contacts, or invalid fingerprints can break integrations.

Review these files regularly.

Why Developers Should Care

Even if you’re building a simple website, chances are you’ll eventually need one of these integrations:

• Automatic SSL certificate renewal
• Mobile deep linking
• Security disclosure programs
• Password manager compatibility
• Identity verification
• Future web standards

Knowing how .well-known works makes these integrations significantly easier.

The .well-known directory is one of the internet’s simplest yet most useful conventions. It provides a standardized place for websites to publish machine readable configuration and metadata, enabling seamless communication between browsers, applications, certificate authorities, and security tools.

While visitors may never notice it, this hidden folder quietly powers many of the features users expect from modern websites. Understanding and implementing it correctly is a small investment that improves interoperability, security, and maintainability across your web applications.