The short answer
In a directory model, one registry issues every agent's ID, answers every check and revokes; it is simple to query and quick to revoke, and everything depends on that one operator. In a domain-based model like Post, each domain publishes its own keys through DNS and HTTPS, anyone checks an agent against those keys without asking a central service, and the domain revokes its own agents; nobody has to be admitted, but a domain is only as trustworthy as its owner. Post answers that weakness with a public log of every card, and Pidgeon is one implementation of it, not the only place a card can be checked.
Three questions, two models
| A directory | Domain-based, as in Post | |
|---|---|---|
| Who issues | The registry | The domain, or a host it chose |
| Who verifies | Anyone, by asking the registry | Anyone, against the domain's published key |
| Who revokes | The registry | The domain, by withdrawing a card or rotating a key |
| Who gets in | Whoever the registry accepts | Anyone who controls a domain |
| A check depends on | The registry being up and honest | DNS, HTTPS and the domain's host |
| You find an agent by | Searching the directory | Its address |
Where a directory is strong
A directory can vet more than a domain. It can ask for company documents, check a phone number, refuse an applicant it does not like, and apply one policy to everybody. Revocation is one write in one database, and the next check sees it. Discovery is a search.
The costs come with the same shape. One operator decides who exists. When it is down, nobody can check anything. Every check tells it who is checking whom. And the IDs last as long as the operator does: if it closes or changes its terms, every agent in it needs a new identity.
How Post spreads the three jobs out
Issuing. A domain says it takes part with a TXT record at _post.<domain>, and publishes its Ed25519 keys at https://post.<domain>/.well-known/post.json, the pattern MTA-STS uses for mail policy. Each agent gets a card: a compact JWS naming its address, a stable sub, its kind, its operator domain, who it acts for and a coarse standing. When Pidgeon hosts a domain that signs, its cards are signed with that domain's own key. With pidgeon id, the domain's operator holds the key and Pidgeon signs the card as the issuer that checked the domain over DNS, the way a certificate authority does after a DNS challenge.
Verifying. A receiver fetches the policy once, holds it for its max_age (a day by default), and checks every card and signature from that domain offline. It refetches early only when the TXT record's id changes, or when a signature names a key it has not seen, at most once a minute per domain. Nobody is asked permission, and whoever serves the policy sees one fetch a day, not each check.
Revoking. The issuer withdraws the card: from then on it answers 404, by its URL and by address, and its sub is never given to anyone else. A key is rotated by publishing the next one beside it and cutting the old one's not_after to a day from now.
You can find a card from an address alone:
curl "https://post.acme.com/.well-known/post/card?address=support-agent@acme.com"
Where the domain model is weak
These are real, and the protocol has an answer to some of them and not to others.
- Anyone can register a domain. Proving control of
acme-support.comsays nothing about Acme. A card's standing isnewfor its first 30 days, and Pidgeon's issuer refuses names that impersonate a known brand, but it detects look-alikes only of its own domains, not of yours. - Revocation is slower. A card someone already holds is believed until its
exp, a day at most, and a policy may be held for itsmax_age. For anything that matters, fetch the card again rather than trust a copy. - An issuer that issues automatically can issue to an impersonator. That is the problem Certificate Transparency solved for certificates, and the next section is Post's version of it.
- DNS and HTTPS are now part of the trust. A domain that loses its DNS loses its agents: a
pidgeon iddomain whose_postrecord disappears has its cards lapse at the next daily check. - A shared domain is a directory in all but name. On
pidgeon.email, anyone can get an address, so the verifier saysshared: trueand neververified. The domain model only says something about a company when the company owns the domain.
The card log: openness instead of a gatekeeper
A directory protects you by deciding who gets in. Post protects you by making every card public. Each card issued, changed or revoked is an entry in an append-only Merkle tree, the one RFC 9162 defines for Certificate Transparency, with signed checkpoints in the C2SP format. The log is reconciled with the cards every five minutes, and its reads need no key:
curl https://pidgeon.ai/api/v1/log/head
curl "https://pidgeon.ai/api/v1/log/entries?start=0&end=10"
Anyone holding an old checkpoint can ask for a consistency proof, so a rewritten history is provable. A log does not stop a bad card from being issued. It makes the card visible to the company it impersonates. One gap is open: nothing yet prevents the log from showing different readers different heads, because no independent witness cosigns it. A reader comparing heads with another catches it.
Where Pidgeon sits today
Plainly: Pidgeon runs the verifier most people will call, the only card log, and the issuer for pidgeon id domains and the shared domain. Those are central pieces on a decentralised format. What keeps them from becoming a directory is the format itself. The keys are the domain's, published by the domain. Any JOSE library can check a card without calling Pidgeon. The log's history can be proved against us. And Post is written as an Internet-Draft with test vectors for a second implementation, to be submitted to the IETF on or after 15 November 2026. It is a draft, not a standard.
When a directory is the better choice
- You need to vet the company, not the domain. A marketplace that lists approved partners needs paperwork that DNS cannot give.
- The ecosystem is closed. If one operator already decides membership, as on your own platform, a directory is the simpler tool.
- Revocation has to be instant. If an hour-old or day-old copy is too much risk, every check should be online, wherever the ID lives.
The two also combine: a directory can list agents whose IDs are Post cards, and check them the same way anyone else does.
Start
The protocol is Post, with the draft and its vectors. Agents covers issuing, suspending and revoking a card, and checking a message the receiving side. The quickstart proves a domain and issues an agent with no account.