# What Is the .well-known Directory on a Website?

> What /.well-known/ is, the path RFC 8615 reserves for files that describe a site, what its IANA registry holds and what a store publishes there.

URL: https://clione.ai/glossary/well-known/
Lang: en

If a specification for [agentic commerce](/glossary/agentic-commerce/) tells you to publish a file at `/.well-known/`, or a vendor asks you to upload a verification file there, it is not asking for just any folder: it is **a path reserved by an internet standard for information that describes the whole site**. The dot at the start matters: on some operating systems, folders whose names start with a dot are hidden, and the standard itself warns that an administrator may not know they exist.[^rfc8615] It matters to you because the protocols an [AI agent](/glossary/ai-agent/) uses to discover what a store can do start looking right there.

## How it works

Some applications need to know something about a site before asking it for anything: what permissions it grants, what services it offers, whom to notify about a flaw. The obvious solution is to fix an address known in advance. The problem, says RFC 8615, is twofold: **two protocols may pick the same address, or step on a URL the site already uses**, and fixing one also takes away the site owner's control over their own URLs. The standard solves it by reserving a single prefix, `/.well-known/`, in `http`, `https`, `ws` and `wss` URLs, and asking that each use be registered.[^rfc8615]

RFC 8615 is from May 2019 and replaces RFC 5785, the first version. Its rules fit in a few lines:[^rfc8615]

- **Only the root counts.** `/.well-known/example` is a reserved address; `/store/.well-known/example` is not.
- **One name per application, no slashes and precise.** The standard discourages settling for generic words: for the metadata of an application called Example, `example-metadata` is better than `metadata`.
- **Each name's specification rules.** It is the one that defines the format and the content type. The RFC defines nothing for the `/.well-known/` path itself, and warns that clients should not expect anything to exist at it: **a bare `/.well-known/` returning a 404 error is normal**.

Names are registered in IANA's Well-Known URIs registry. To get in you need a published specification and an expert's review, and each entry gives its name, who controls it, which document defines it and its status: **permanent** for open standards and for what the experts see in use, **provisional** for the rest, which may be withdrawn if it falls out of use.[^rfc8615] The registry **had 105 entries on October 6, 2026**, and its last update was September 16, 2026.[^iana-well-known]

What lives on that path speaks for the whole site, and the standard draws its main security advice from there: **control who can write to `/.well-known/`**, especially if several people or services share the same domain. Whoever manages to write there can change what the site declares about itself without anyone noticing.[^rfc8615]

## In a store

This is what a store may find on that path. The first three are in IANA's registry; the fourth is not:

| Path                           | What it is for                                                                                                                                                         | In the IANA registry                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `/.well-known/security.txt`    | Says whom to notify about a vulnerability. It has two required fields, `Contact` and `Expires`, and is served over HTTPS as plain text.[^rfc9116]                      | Permanent, controlled by the IETF.[^iana-well-known]                                   |
| `/.well-known/change-password` | Redirects to the page where a customer changes their password, so a password manager can find it. It is a W3C draft.[^w3c-change-password]                             | Provisional, controlled by the W3C.[^iana-well-known]                                  |
| `/.well-known/agent-card.json` | The card an agent that speaks [A2A (agent-to-agent)](/glossary/a2a/) presents itself with, with its identity, capabilities and authentication requirements.[^a2a-spec] | Permanent, controlled by the Linux Foundation, since August 1, 2025.[^iana-well-known] |
| `/.well-known/ucp`             | The store's profile in the [UCP (Universal Commerce Protocol)](/glossary/ucp/): protocol version, services, capabilities and payment methods.[^ucp-overview]           | Not listed as of October 6, 2026.[^iana-well-known]                                    |

**Fictional example.** This is the minimal `security.txt` of an invented store, `example-store.com`, served at `https://example-store.com/.well-known/security.txt`:

```text
Contact: mailto:security@example-store.com
Expires: 2027-10-06T00:00:00.000Z
```

The `Expires` date says when the file stops being valid, and the standard asks for it to be served as `text/plain; charset=utf-8`.[^rfc9116] For the UCP profile the conditions are stricter, and worth reviewing if a platform or a CDN sits in the middle: **it is served over HTTPS, with no redirects**, and with a public `Cache-Control` header of at least 60 seconds, never `private`, `no-store` or `no-cache`.[^ucp-overview] A redirect from `http` to `https` or from the bare domain to the `www` one is common in a store, and on this path it is enough to break the specification if the agent arrives by the address that redirects.


Believing that every file for bots goes in `/.well-known/`. [robots.txt](/glossary/robots-txt/) goes at the root, at `/robots.txt`, and its own standard fixes that;[^rfc9309] RFC 8615 does not change it, because it only affects the mechanisms that choose to use it.[^rfc8615] The [llms.txt](/glossary/llms-txt/) file is also published at the root, at `/llms.txt`, or on a subpath.[^llmstxt] And the other way around: a `/.well-known/` inside a subfolder is not the reserved path.[^rfc8615]


## How to check it

1. **Request the paths from your own store.** Open `https://your-domain/.well-known/security.txt` and, if you sell through agents, `https://your-domain/.well-known/ucp`. A 404 on the first is not a site error, but it tells you that you do not have one.
2. **Look at the headers with `curl -I`.** The response code, whether there is a redirect and the `Content-Type`. For the UCP profile, also that it does not redirect and that the `Cache-Control` is public.[^ucp-overview]
3. **If you have a `security.txt`, check the date.** The `Expires` field says until when what it declares is valid.[^rfc9116]
4. **Look up in IANA's registry the name you are asked to publish.** If it is there, it links to the specification that defines it; if it is not, it is the convention of whoever is asking, not a registered standard.[^iana-well-known]
5. **Review who can write to that path**, on the server, on the CDN and in the installed applications. The standard asks that you not grant that permission without realizing it.[^rfc8615]

## Related concept: robots.txt

`robots.txt` and `/.well-known/` get confused because both are fixed addresses that a machine requests before anything else. But `robots.txt` is **a file with a single job**: telling [crawlers](/glossary/web-crawler/) what they may request, and always at the root.[^rfc9309] `/.well-known/` is **a namespace for many files**, each with its own protocol and its own specification.[^rfc8615] RFC 8615 cites the robots exclusion protocol as an example of the problem it came to tidy up, and makes clear it does not touch it.[^rfc8615]

To keep going, the [reading path](/learn/crawling-and-indexing/) for this topic orders the rest of the terms, and the [UCP](/glossary/ucp/) entry explains what an agent does with the profile it finds at `/.well-known/ucp`.