Recently, I came across the .well-known/ during a research on the A2A (Agent2Agent Protocol) where the Agent Card is to be stored in a file “agent-card.json” within the .well-known/ folder, which prompted me to look it up, because I’ve only seen it appear when setting up TLS (former SSL) certificates (using Let’s Encrypt or similar certificate authorities).
Definition of the .well-known/ folder
According to Wikipedia, the .well-known/ folder is a well-known URI (often called well-known identifier). It’s been defined under RFC8615 published by Mark Nottingham (Co-chair at IETF HTTP Working Group, currently employed at Cloudflare) in May of 2019. Wikipedia says:
This implementation is in response to the common expectation for web-based protocols to require certain services or information be available at URLs consistent across servers, regardless of the way URL paths are organized on a particular host. The URIs are implemented in webservers so that requests to the servers for well-known services or information are available at URLs consistently in well-known locations across servers.
Or in other words – web protocols often need certain information or services to be reachable at predictable URLs regardless of how a particular server organizes its paths. The .well-known/ standard solves this by giving every server a consistent, agreed-upon location for that kind of metadata.
Usage
The .well-known/ directory acts as a standardized discovery point that allows external machines to retrieve site metadata, security policies, and authentication protocols without needing a custom API or a full site crawl. The structure of the URI should contain the service your website or web app is supporting.
As an example, if an application hosts the service “example“, the corresponding well-known URIs on https://www.x-ample.com/ would start with https://www.x-ample.com/.well-known/example.
Some interesting examples
That URI can be used for a number of services including the aforementioned Let’s Encrypt’s acme-challenge. ACME stands for Automated Certificate Management Environment. Find more information in the table below:
| Service | Path within the .well-known/ folder | Used by | Description | Adoption |
| TLS/SSL Certificate Automation | acme-challenge | Certbot, Traefik, Caddy | When using Let’s Encrypt or other automated CAs, the server proves it owns the domain by placing a temporary token here | High |
| A2A Protocol | agent-card.json | A2A discovery mechanism | To collaborate using the Agent2Agent (A2A) protocol, AI agents need to first find each other and understand their capabilities. | Emerging |
| Security Vulnerability Reporting | security.txt | Google, Amazon, GitHub | This file provides a standardized way for security researchers to find your “bug bounty” program or contact info before they go public with a vulnerability. | High, but mostly for Big Tech companies like FAANG and security researchers |
| Mobile App Deep Linking | assetlinks.json, apple-app-site-association | Google Play Store, Apple App Store | To prove that a specific mobile app is allowed to open your website links automatically (and not a “fake” app), you host a verification JSON. | Medium |
| OpenID (Identity and Authentication) | openid-configuration | Okta, Auth0, Keycloak, Google | If your website acts as an identity provider (like “Log in with MySite”), clients look here to find your technical configuration (endpoints, public keys, etc.). | High |
| URL for password change redirects | change-password | Chrome, Safari password managers | A newer standard that allows browsers to redirect users to specific pages, like where to change a password, regardless of the site’s actual URL structure. | Low |
| Global Privacy Policy | gpc.json | All major web browsers (Firefox, Opera, Chrome, Safari, etc) | Allows a site to publicly declare that it respects the Global Privacy Control signal sent by browsers. Useful for demonstrating regulatory awareness (e.g. CCPA compliance), though it’s advisory — it signals intent, not enforcement | Medium-Low |
Summary
The .well-known/ folder is one of those web standards that most developers encounter once and then forget until they realize it underpins half a dozen things they use daily. Standardized under RFC8615, it gives servers a single, consistent location to expose metadata and service configurations, eliminating the need for custom discovery APIs or out-of-band documentation.
Its footprint is wider than it looks: TLS certificate automation, identity provider discovery, security disclosure, mobile deep linking, privacy signaling, and now AI agent discovery through A2A. If you run a web service of any meaningful size, there’s a good chance something already lives in your .well-known/ and probably something else that should.