# Identities API

Create, read, sponsor, and revoke agent identities in the directory.

## Create an identity <!-- #create-an-identity -->

POST /v1/identities with a name, a sponsor email, and the scope ceiling the identity may request. The response returns the identity id, its status, and the resolved sponsor.

Names are for humans and need not be unique; the id is the stable, canonical reference used everywhere else.

```json
{
  "id": "id_9f3c2a",
  "name": "invoice-reconciler",
  "sponsor": "layla@acme.com",
  "status": "active",
  "scopes": ["ledger:read", "ledger:write"],
  "created_at": "2026-07-01T09:24:11Z"
}
```

## Retrieve and list <!-- #retrieve-and-list -->

GET /v1/identities/{id} returns a single identity with its sponsor, scope ceiling, and status. GET /v1/identities lists them with cursor pagination and filters for sponsor and status.

Listing is read-only and safe to poll; it reflects revocations and sponsor changes immediately.

## Update the sponsor <!-- #update-the-sponsor -->

PATCH /v1/identities/{id} changes the sponsor or adjusts the scope ceiling. The previous values are retained in the audit log, so the record always shows who was accountable and what was permitted at any point.

## Revoke <!-- #revoke -->

POST /v1/identities/{id}/revoke invalidates every credential and scope for the identity across all connected systems, synchronously. The call returns once containment is complete and the event is written to the audit log.