Identities - Sente

An identity is a long-lived email address on sente.run that your agent owns. It is the substrate an account sits on: signup and login mail arrives there, and that is where Sente reads the verification code from.

Most integrations never call this endpoint. Accounts are first-order — omit identityId on POST /v1/registrations or POST /v1/connections and Sente provisions the identity for you, deriving the local part from the app’s hostname (github.com → github@sente.run, or github-x7k2@sente.run if that is taken). Create one explicitly when you want to choose the address, or reuse one address across several apps.

The identity object

{
  "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"
}

description is returned only by GET /v1/identities/:id. The create and list responses are narrower — see each below.

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 server-side. 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.

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"}'

sente identity create --name support-agent --local-part acme-qa

import { Sente } from "@sente-labs/sdk";

const sente = new Sente({ apiKey: process.env.SENTE_API_KEY! });

const identity = await sente.identities.create({
  name: "support-agent",
  localPart: "acme-qa",
  onConflict: "suffix",
});
console.log(identity.email); // acme-qa@sente.run

from sente import Sente
import os

sente = Sente(api_key=os.environ["SENTE_API_KEY"])

identity = sente.identities.create(
    name="support-agent",
    local_part="acme-qa",
    on_conflict="suffix",
)
print(identity.email)  # acme-qa@sente.run

Response 201 — the create response carries id, name, and email only:

{
  "id": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "name": "support-agent",
  "email": "acme-qa@sente.run"
}

Status	Code	What it means	What to do
`400`	—	`localPart` failed the format rules; `error` is the zod issue array.	Fix the address: lowercase alphanumerics, `.`, `_`, `-`, no leading/trailing punctuation, no `..`.
`409`	—	`{"error": "local-part taken", "localPart": "acme-qa"}` — the address exists and `onConflict` is `"error"`.	Pick another, or re-send with `onConflict: "suffix"`.
`409`	`LOCAL_PART_RESERVED`	The exact word is reserved for Sente’s own mail (`support`, `admin`, `billing`, `security`, `postmaster`, `noreply`, …).	Use a variant — `support-bot` is allowed, `support` is not. Only the exact word is blocked.
`429`	`IDENTITY_LIMIT_EXCEEDED`	The per-org identity cap; `limit` reflects your plan (9 free / 25 pro / 100 team).	Delete an unused identity, or upgrade. Same error fires when a `register`/`connect` auto-provision would cross the cap.

List identities

GET /v1/identities

curl https://api.sente.run/v1/identities \
  -H "Authorization: Bearer sk_sente_..."

Response 200 — id, name, email, createdAt per row (no description):

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

There is no filter, no pagination, and no ordering guarantee — the org’s identity count is capped by plan, so the full list is always small.

Get an identity

GET /v1/identities/:id

curl https://api.sente.run/v1/identities/idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5 \
  -H "Authorization: Bearer sk_sente_..."

Response 200: the full identity object including description. 404 {"error": "not found"} for unknown ids and other orgs’ identities alike.

Delete an identity

DELETE /v1/identities/:id Hard delete, in one transaction: the identity, its messages, its registrations, its runs, and its identity-scoped webhooks. The local part is freed for re-creation. Org-wide webhooks are untouched. Mail sent to the old address afterwards is dropped.

This deletes the credential vault for every account under the identity, including passwords Sente generated that exist nowhere else. Fetch anything you still need from GET /v1/registrations/:id/credentials first. There is no undo and no soft-delete.

curl -X DELETE https://api.sente.run/v1/identities/idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5 \
  -H "Authorization: Bearer sk_sente_..."

Response: 204 with no body. An identity.delete audit event is written, keeping the address for the record after the row is gone.

Status	Code	What it means	What to do
`409`	`IDENTITY_BUSY`	A run is `queued`, `running`, `awaiting_verification`, or `blocked` on this identity.	Wait for it, or abort it with `POST /v1/runs/:id/abort`, then retry.
`404`	—	Unknown id, or not your org’s.	—

Cleanup that happens outside the transaction

After the row is deleted, Sente also asks the browser layer to drop the identity’s persistent profile and to stop any open CDP session so it stops billing. Both are best-effort and fire-and-forget: if that call fails, the delete still succeeded and the orphaned profile is swept later. Nothing in the API surfaces that failure.

Delete is HTTP-only. The TypeScript and Python SDKs expose identities.create, get, and list; the CLI exposes identity create, identity list, and identity show. Neither client wraps deletion.

Accounts overview

How the account and the identity relate.

Inbox

Read, send, and archive the identity’s mail.

Registrations

Put an account on the identity.

​The identity object

​Create an identity

​List identities

​Get an identity

​Delete an identity

​Related

Accounts overview

Inbox

Registrations

The identity object

Create an identity

List identities

Get an identity

Delete an identity

Related