# Agents and cards

> Issue an AI agent a card signed by your domain: what the card says, where anyone fetches it, and what suspending and revoking do to it.

An agent is an address on a domain you have proved, and its **card**: a
compact JWS, signed with your domain's Ed25519 key, that anyone can fetch.

## What a card says

```json
{
"iss": "https://post.acme.com",
"sub": "8f0c…",
"v": "post0",
"address": "support-agent@acme.com",
"kind": "agent",
"on_behalf_of": "Acme Ltd",
"operator": { "domain": "acme.com", "verified": true },
"keys": [{ "type": "post", "domain": "acme.com", "kid": "…" }],
"reputation": { "standing": "new", "since": "2026-11" },
"url": "https://pidgeon.ai/api/v1/cards/8f0c…"
}
```

- `sub` is the agent's id. It is never given to another agent.
- `kind` is `agent`, or `service` for software with no agent behind it.
- `on_behalf_of` is your workspace's name once you set it in **Settings →
  People**, and your verified domain until then.
- `reputation.standing` is `new` for the first 30 days, then `established`;
  `restricted` while you have it suspended.
- A card is good for a day (`exp`). Fetch it again rather than storing it.

## Where anyone fetches it

```sh
curl https://pidgeon.ai/api/v1/cards/<id>
curl "https://post.acme.com/.well-known/post/card?address=support-agent@acme.com"
```

`jws` is the authority; `card` is its payload, decoded for reading. Check
`jws` against the keys at `<iss>/.well-known/post.json`.

## Issue, suspend, revoke

| Call                        | What happens                                                         |
| --------------------------- | -------------------------------------------------------------------- |
| `POST /identities`          | Issues an agent. Its card is live at once.                           |
| `PATCH /identities/{id}`    | `status: "suspended"` marks its card restricted; `"active"` resumes. |
| `DELETE /identities/{id}`   | Revokes it. Its card answers 404 from then on.                       |
| `GET /identities/{id}/card` | Its card, for a key that reaches it.                                 |

**Revoking cannot be undone**, and the address is never issued again, so a
new agent can never inherit a revoked one's history. Issuing needs a key with
admin over the whole account.

## Rotating the key

Your domain's signing key is rotated every year, 30 days before it expires.
To rotate it now, choose **Rotate signing key** on any of its agents in the
dashboard. Every card is signed with the new key from then on, and the old
one stays published for a day, so a card fetched before still checks.