Agent identities
Agent identity
Give your agent an identity and it can sign in to sites as itself, and the mail from an address linked to it names you as its operator. Optional for email: an inbox works without it. The pieces are a verified operator (you), agent identities registered under you, and a key per agent identity in your key directory; in the dashboard they are under Agent identities. This page explains them and how you are verified.
The pieces
| Piece | What it is |
|---|---|
| Operator | Your account: a person (individual) or a company (business), with a verification level, a country and the date it joined. |
| Agent | A named agent under the operator, with what it does (its purpose). Websites see both. Registered in the dashboard, or from code, the CLI or the MCP server (Set an agent up from code). |
| Key | An Ed25519 key belonging to one agent. Its id (kid) is the key’s JWK thumbprint (RFC 7638). An agent can have several; each can be revoked alone. |
| Key directory | https://<your-slug>.agents.pidgeon.ai/.well-known/http-message-signatures-directory: every live key of your active agents, as a JWK Set. |
| Reputation | The operator’s band: unverified, new, good, flagged or suspended. It belongs to the operator, not the agent. See Reputation. |
Keys belong to agents; reputation belongs to the operator. Revoking one agent leaves the others working, and its record still counts against you, so a reported agent cannot be replaced with a fresh one.
Verification levels
| Level | Proves | Price | How |
|---|---|---|---|
none | Nothing yet | Free | Every new account starts here. |
domain | Control of a domain | Free | A TXT record at _pidgeon.<domain> holding pidgeon-verify=<token>. |
kyc | A real person stands behind it | €19, once | A document, liveness and face match, through Didit, after paying on Stripe. |
kyb | A registered company and a named person | €99 a month | A registry check of the company, with the Business subscription. |
A level only rises: a later check never lowers it. The one way down is removing the account’s last proved domain when the domain was all its level rested on: it is back to none. Sites your agents sign in to see the level as account.verification in sign-in tokens. They never see documents, addresses or who reported you.
Verify a domain
Agent identities → Verification, Add a domain, then publish the record it shows and press Check the record. Verification reads DNS only, asking your domain’s own nameservers first, so a record counts as soon as they serve it, with no wait for caches. Leave out www.. Names under the top-level names reserved for testing (.example, .test, .invalid, .localhost, .local) are refused: nobody can own one, so nobody can publish its record. Where your DNS host speaks Domain Connect and has switched Pidgeon’s template on, Set it up with <host> adds the record on your host’s own page, and Pidgeon holds no DNS credential. The account’s owner can remove a verified domain from its page, once no address is left at it.
_pidgeon.example.com. TXT "pidgeon-verify=<token>"Domains from the API
A platform adds its customers’ domains in code, each in the customer’s pod. Add one, hand its owner the records to publish at their DNS host, then ask Pidgeon to look. Looking finds nothing yet is not an error: verified stays false until the record is there, so ask again later. Once proved, turn mail on and the same domain answers mail’s records too.
# Add a domain in a customer's pod: answers the record to publish
curl https://pidgeon.ai/v1/domains \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "acme.com", "pod_id": "'$POD_ID'"}'
# Once it is published: is it proved?
curl -X POST https://pidgeon.ai/v1/domains/$DOMAIN_ID/verify \
-H "Authorization: Bearer $PIDGEON_API_KEY"| Call | Access | Answers |
|---|---|---|
GET /v1/domains | read | {data: [domain…]}: every domain in reach, waiting and proved. |
POST /v1/domains | admin | 201 and the domain. domain, and pod_id if you like. 409 if the account has it already. |
GET /v1/domains/{id} | read | One domain, with every record to publish: the ownership TXT, and mail’s once mail is on. |
POST /v1/domains/{id}/verify | read | Looks for the TXT record now; answers the domain. 409 if another account proved it first. |
DELETE /v1/domains/{id} | admin | 204. A proved domain goes too, its mail turned off first; 409 while an inbox is still at it. Removing the last proved domain of an account verified by domain alone takes its level back to none. |
A key of one pod lists, reads, verifies, adds and removes only its own pod’s domains: another pod’s is 404, and naming another pod when adding is 403. A key of the whole account reaches every pod and may add to any of them.
Agent identities and keys
- Register an agent identity under Agent identities: a name (1–80 characters) and what the agent does (up to 280).
- Make a key on the agent’s page (in your browser; the private key is shown once) or publish one from code. Pidgeon never sees a private key.
- Rename an agent, or say again what it does, on its page or with
PATCH /v1/agents/{id}. - Revoke a key on the agent’s page or with
DELETE /v1/agents/{id}/keys/{kid}, and it leaves your directory at once; a site that caches the directory drops it within 60 seconds. A key you publish reaches such a site within the same 60 seconds. - Revoke an agent, on its page or with
DELETE /v1/agents/{id}, and none of its keys verifies again. It cannot be undone.
The directory serves application/http-message-signatures-directory+json with Cache-Control: public, max-age=60. Pidgeon’s CDN does not keep it, so every fetch is current; a verifier may keep it the 60 seconds:
curl https://acme.agents.pidgeon.ai/.well-known/http-message-signatures-directoryReports against you
Agent identities → Reports lists every report a website filed against your agents, with its category and evidence, never who filed it. You can dispute each one once, with a statement of 10 to 4,000 characters; a person at Pidgeon reads it. A report.created webhook tells you when one arrives.
Next
- Sign requests: the headers, and the SDKs that write them.
- Reputation: the bands and what moves them.