Do you need an agent identity provider?

The short answer

Probably not a new one. Your identity provider already authenticates your people and your services, and your authorisation system already decides what software may do; what neither gives an agent is an ID that somebody outside your company can check on a message or a request. Pidgeon is that format and that check, not another identity provider: today pidgeon id gives your agents signed cards on your own domain with no account, and an issuer you run yourself, connected to the identity provider you already have, is planned.

Three jobs under one name

"Agent identity provider" usually means three different jobs:

1. Letting the agent into your own systems. A service account, a client credential, a workload identity. Your identity provider does this today.
2. Deciding what the agent may do. Which records it can read, which actions it can take, up to what amount. That is your authorisation system, and it is shaped by your own data.
3. Proving to somebody outside who the agent is. A customer reading its email, a vendor whose API it calls, a site it signs up to. They do not trust your identity provider and cannot query it.

The first two are solved, and moving them to a new vendor means copying your people, your groups and your offboarding somewhere else. Some companies are not allowed to hand authentication to a third party at all. The third job is the one that is missing.

What the third job needs

Somebody outside your company needs three things to check your agent without calling you:

• A format they can read. Post's agent card is a compact JWS, typ: agent-card+jwt, naming the agent's address and stable sub, its kind, the operator domain, who it acts for in on_behalf_of, and a coarse standing.
• Keys they can find. A TXT record at _post.<domain> says the domain signs, and https://post.<domain>/.well-known/post.json lists its Ed25519 keys, in the way MTA-STS publishes a mail policy.
• A check anyone can run. POST /v1/verify takes a message or a signed HTTP request, needs no key and keeps nothing it is sent.

None of this replaces a login. It sits beside it, the way a TLS certificate sits beside the accounts your people sign in to.

What pidgeon id does today, with no account

npm install -g @pidgeon-ai/cli
pidgeon id init acme.com
pidgeon id issue support-agent --on-behalf-of "Acme Ltd"

• init makes an Ed25519 key on your machine, in ~/.config/pidgeon/id/acme.com.json, readable by you only. Pidgeon stores only the public half. It then prints two DNS records: a TXT at _post that proves the domain and names your key, and a CNAME at post that lets anyone else fetch your keys and cards. Where your DNS provider offers Domain Connect, it prints a link that adds both.
• issue gives support-agent@acme.com a card. Pidgeon signs it as the issuer that checked your domain, the way a certificate authority signs after a DNS challenge. Its operator is acme.com, verified, and its keys name your key, which is the one that signs the agent's mail and requests.
• It renews itself. A card is signed for a day each time it is read, for as long as the _post record stands. Take the record down and the cards stop.
• list, revoke <name> and rotate do what they say. A revoked card is gone at once, and a copy somebody already fetched lapses within a day. After rotate, the old key still verifies for a day.

On a server, PIDGEON_ID_KEY holds the key instead of the file. Issuing is free. A domain can issue 100 agents a day, and 5 a day while it is newly registered or a subdomain. A domain already verified on a Pidgeon account is refused here, so one domain has one key authority.

Why Pidgeon signs the card, and what it checked

When Pidgeon signs a pidgeon id card, it is vouching for one fact: whoever holds this key controls the DNS for acme.com. It has not checked that Acme Ltd is a real company, that the agent behaves, or that on_behalf_of is true beyond the domain. Names that impersonate a known brand are refused, for the domain and for on_behalf_of, but a look-alike of your own domain is not detected.

That is also why every card Pidgeon issues is written to a public, append-only log, in the way Certificate Transparency logs every certificate. If somebody proves acme-support.com and issues an agent that claims to act for Acme, the entry is public, and a log monitor set from a Pidgeon workspace, on the term acme, emails that workspace's owners when one appears.

The planned issuer you run yourself

pidgeon id puts Pidgeon in the issuer's seat. The planned self-hosted issuer moves that seat into your own network: it connects to your existing identity provider, so your identity provider issues the IDs and Pidgeon stays the format and the check: the same card, checked the same way by anyone. It is planned, not built.

When you need none of this

• Your agents never leave your network. Workload identity and service accounts already answer who called.
• You need to decide what an agent may do. That is authorisation, and Pidgeon does not do it.
• You need single sign-on for your people. That is your identity provider's job, and it stays there.

Start

Quickstart proves a domain and issues an agent, from the terminal or the API. Agents shows the card, and checking a message shows the receiving side. The protocol is Post, the draft that defines the card, the keys and the log.