/.well-known/ Directory

Definition

The /.well-known/ directory is a reserved path at the root of a domain, defined by RFC 8615, where services publish machine-readable metadata files at standardised URLs.

It exists so that a client can find a domain's declaration about itself without asking anyone. Both mobile deep linking association files live there — apple-app-site-association and assetlinks.json — alongside certificate challenges, security contacts and payment verification. The directory is trivially simple and breaks constantly, always for the same handful of reasons.

What RFC 8615 actually says

The specification is short. It reserves the path prefix /.well-known/ on every host, and establishes an IANA registry of suffixes so that two services cannot claim the same filename. A well-known URI is always https://<host>/.well-known/<registered-name> — no subdirectories in the middle, no version segment, no query string.

The hosting rules that apply to all of it

Consumers of well-known URIs are machines with no user to ask, so every one of them is strict in the same ways.

The redirect rule deserves emphasis: a browser follows a redirect and shows you the file, so a domain that redirects example.com to www.example.com looks perfectly healthy in a browser and fails every association check. Always test with headers visible.

# Expect exactly one 200. Any 301/302 in the chain is a failure.
curl -sSIL https://example.com/.well-known/apple-app-site-association

# Both hosts, both files
for host in example.com www.example.com; do
  for f in apple-app-site-association assetlinks.json; do
    echo "== $host/$f"
    curl -sSI "https://$host/.well-known/$f" | head -3
  done
done

# Confirm the body is valid JSON and not an HTML error page
curl -sS https://example.com/.well-known/assetlinks.json | python3 -m json.tool

Why the directory vanishes in production

The leading dot is the problem. A large amount of tooling treats dot-prefixed paths as hidden or dangerous, and does so silently. If the file is committed and 404s in production, the cause is almost always on this list.

# ^~ takes precedence over the regex location below it
location ^~ /.well-known/ {
    root /var/www/example.com/public;
    default_type application/json;
    add_header Cache-Control "public, max-age=3600";
    try_files $uri =404;          # never fall through to the SPA
}

location ~ /\. {
    deny all;
}

Practical guidance

• Serve the directory from static hosting, not from application code — one fewer thing that can 500 at 3am.
• Put the files under version control next to the app they authorise, so a bundle ID change and a file change land in the same commit.
• Add a CI check that fetches both files from production and asserts a 200, a JSON content type, and the expected identifier in the body.
• Cache for an hour, not a year. A long max-age on a file you occasionally need to fix is a bad trade.
• When you add a host to an entitlement or manifest, add the file to that host in the same change.

If a file is confirmed missing, the ordered checklist in aasa-file-not-found covers the iOS case end to end, and how-to-validate-assetlinks-json covers Android.