Glossary · Keys and discovery

Well-known URI

Updated 2026-09-23

RFC 8615 reserves the path prefix /.well-known/ in HTTP, HTTPS and some other URI schemes so that applications can discover information about an origin without guessing where it lives. IANA keeps a registry of well-known names, and each name is defined by its own specification.

AgenID uses the pattern for key discovery. An operator can publish the public keys it controls at https://<operator_domain>/.well-known/agenid/keys.json, so a verifier has a copy of the operator key that comes from the operator's own domain rather than from the registry.

Definition

A well-known URI is a URI whose path begins with /.well-known/, a prefix defined by RFC 8615 so that clients can find metadata about an origin at a predictable location before making other requests.

Also known as: /.well-known/ path, RFC 8615 well-known location

How it relates to AgenID

The spec defines one document per domain listing every key that domain vouches for, not one file per key. It is the second half of two-path key discovery: the registry serves the same key at GET https://www.agenid.com/v1/keys/<key-ulid>, and a verifier compares the two copies.

The operator publishes the .well-known file, not AgenID. The domain check reports it as published only when it parses as a valid keys document for that domain.

Why it matters

A key that appears in two independent places is harder to substitute than a key that appears in one. If an attacker altered the registry's copy, the operator's own domain would still serve the original, and the mismatch is detectable by anyone.

What it does not mean

A file at a well-known path proves only that someone who controls that web origin put it there. It does not say the operator is reputable, and it says nothing about what an agent is allowed to do. If the operator publishes no copy, a verifier has one source, not two. The spec also defines /.well-known/agenid/authorities.json on agenid.com for authority keys; it is deliberately not published, because no root authority key exists.

Frequently asked questions

Is the agenid well-known name registered with IANA?

This page makes no claim about registration status. The path and document format are defined by the AgenID spec, published at github.com/AgenID-protocol/spec.

Do I have to publish a keys.json file to register an agent?

No. Registration at /issue works without it. Publishing the file gives verifiers a second, independent source for your key.

Does a verifier have to fetch it?

A careful one should. The resolution envelope names both discovery paths so the comparison can be made without extra configuration.

What agenid.com issues today

The reference deployment at agenid.com issues DECLARED and L1_REGISTERED only. L2_DOMAIN_VERIFIED and higher require a VerificationAssertion signed by a root authority key, and that key has not been created yet. L5 is reserved by the specification and is not issuable at all.

Identity is not permission

Which agent is acting and who declared it is one question. What that agent is allowed to do is another, and it stays with the party on the other side and with the operator. Protocol v1.1.1 defines no signed authorization object.

Sources

learn

How to verify an AI agent, step by step

verify

Prove domain control

glossary

Two-path key discovery