> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sente.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Identities

> Create, list, and delete the managed email identities your agent uses.

An identity is a long-lived email address on `sente.run` that your agent owns. It is the communication layer: one identity can hold zero or many [registrations](/api-reference/registrations) at different apps. See [Identities and registrations](/concepts/identities-and-registrations).

## The identity object

```json theme={null}
{
  "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "name": "support-agent",
  "description": "Handles signup flows for the QA bot",
  "email": "swift-otter-4821@sente.run",
  "createdAt": "2026-07-20T09:14:03.201Z"
}
```

## Create an identity

`POST /v1/identities`

| Field         | Type                    | Required | Description                                                                                                                                                                               |
| ------------- | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string ≤ 200            | no       | Display name.                                                                                                                                                                             |
| `description` | string ≤ 2000           | no       | Free-text note.                                                                                                                                                                           |
| `localPart`   | string                  | no       | Requested address local part: 1–64 chars of `a-z0-9._-`, must start and end alphanumeric, no consecutive dots. Lowercased. Omitted → a random readable address (e.g. `swift-otter-4821`). |
| `onConflict`  | `"error"` \| `"suffix"` | no       | What to do if `localPart` is taken. `"error"` (default) → `409`; `"suffix"` → append a random suffix until free.                                                                          |

```bash theme={null}
curl -X POST https://api.sente.run/v1/identities \
  -H "Authorization: Bearer sk_sente_..." \
  -H "content-type: application/json" \
  -d '{"name": "support-agent", "localPart": "acme-qa"}'
```

Response `201`:

```json theme={null}
{
  "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "name": "support-agent",
  "email": "acme-qa@sente.run"
}
```

Errors:

| Status | Body                                                                                               | When                                                                                                                               |
| ------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `409`  | `{"error": "local-part taken", "localPart": "acme-qa"}`                                            | Requested `localPart` is in use and `onConflict` is `"error"`.                                                                     |
| `409`  | `{"error": "local-part reserved", "code": "LOCAL_PART_RESERVED", "localPart": "support"}`          | Exact reserved words (`support`, `admin`, `billing`, `postmaster`, …) can't be allocated. `support-bot` is fine; `support` is not. |
| `429`  | `{"error": "identity limit reached (25 per org)", "code": "IDENTITY_LIMIT_EXCEEDED", "limit": 25}` | Per-org identity cap — plan-dependent (9 free / 25 pro / 100 team); `limit` reflects your plan.                                    |

## List identities

`GET /v1/identities`

```bash theme={null}
curl https://api.sente.run/v1/identities \
  -H "Authorization: Bearer sk_sente_..."
```

Response `200`:

```json theme={null}
[
  {
    "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
    "name": "support-agent",
    "email": "acme-qa@sente.run",
    "createdAt": "2026-07-20T09:14:03.201Z"
  }
]
```

## Get an identity

`GET /v1/identities/:id`

```bash theme={null}
curl https://api.sente.run/v1/identities/idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5 \
  -H "Authorization: Bearer sk_sente_..."
```

Response `200`:

```json theme={null}
{
  "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "name": "support-agent",
  "description": "Handles signup flows for the QA bot",
  "email": "acme-qa@sente.run",
  "createdAt": "2026-07-20T09:14:03.201Z"
}
```

`404 {"error": "not found"}` for unknown ids and other orgs' identities.

## Delete an identity

`DELETE /v1/identities/:id`

Hard delete. Removes the identity and everything under it — messages, registrations, runs, and identity-scoped webhooks — and frees the local part for re-creation. Org-wide webhooks are untouched. Mail sent to the old address afterwards is dropped.

<Warning>
  This is not reversible, and it deletes the credential vault for every registration under the identity. If the identity has Sente-created accounts you still need, fetch their credentials first.
</Warning>

```bash theme={null}
curl -X DELETE https://api.sente.run/v1/identities/idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5 \
  -H "Authorization: Bearer sk_sente_..."
```

Response: `204` with no body.

Errors:

| Status | Body                                                            | When                                                                                                                   |
| ------ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `409`  | `{"error": "identity has a live run", "code": "IDENTITY_BUSY"}` | A run is queued, running, awaiting verification, or blocked. Wait for it to finish or [abort it](/api-reference/runs). |
| `404`  | `{"error": "not found"}`                                        | Unknown id.                                                                                                            |