Proving a domain

A card is only as good as the domain that signs it, so an agent can be issued only on a domain you have proved is yours. Proving it takes one TXT record; publishing its keys takes two more. None of them touches your mail: no MX, SPF or DKIM record changes, and whoever receives your mail keeps receiving it.

Add one

curl https://pidgeon.ai/api/v1/domains \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "domain": "acme.com" }'

The answer lists three records. Publish them at your DNS provider, or in the dashboard press Set up automatically where your provider offers Domain Connect or takes an API token.

The ownership record is also accepted at the domain itself, for a panel that will not take _pidgeon.

Wait for it

POST /v1/domains/{id}/verify checks again now; Pidgeon also checks on its own every few minutes. Each record in dns_records has a status and, when it is wrong, found: what is there instead. A domain is verified once the ownership record is found, and you can issue agents from then on.

curl -X POST https://pidgeon.ai/api/v1/domains/$DOMAIN_ID/verify \
-H "Authorization: Bearer $PIDGEON_API_KEY"

Somebody else runs the DNS

GET /v1/domains/{id}/setup-link answers a one-click link where the provider offers Domain Connect. In the dashboard, Send these to someone emails the records to whoever runs the zone, with a page that ticks each one as it goes live.

Removing one

DELETE /v1/domains/{id} removes the domain and its agents. Their cards stop answering, so a check of anything they sent fails. There is no undo. Any records you published stay in your zone for you to delete.