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

# identities

> Personas, their endpoints, and the agent grant — client.identities.

An identity is a named persona an agent acts as. Fourteen methods: five on the persona itself, three on the agent↔identity grant, and six reads of the endpoints a persona owns. API detail: [Identities](/docs/api/identities).

Wherever a parameter is called `ref`, it takes an `idn_` id **or** the persona's name — the API resolves both.

## The persona

```ts theme={"system"}
client.identities.create(body: IdentityCreate): Promise<Identity>
client.identities.list(query?: ListQuery): Promise<Page<Identity>>
client.identities.get(ref: string): Promise<Identity>
client.identities.update(ref: string, body: IdentityPatch): Promise<Identity>
client.identities.delete(ref: string): Promise<Deleted>
```

* `create` — `POST /v1/identities`. `IdentityCreate` is `{ name, description?, metadata? }`. A persona is created empty; its endpoints are minted through their own routes.
* `list` — `GET /v1/identities`, cursor-paginated.
* `get` — `GET /v1/identities/{ref}`.
* `update` — `PATCH /v1/identities/{ref}`. `IdentityPatch` is every create field optional. The denormalised `emails`/`phones`/`domains`/`connections` arrays are read-only here.
* `delete` — `DELETE /v1/identities/{ref}`. Check [`agents`](#agents) first.

## The grant

The agent↔identity edge hangs off the **agent** — it answers which personas *that agent* may act as.

```ts theme={"system"}
client.identities.attach(agentId: string, identity: string): Promise<Grant>
client.identities.detach(agentId: string, identityId: string): Promise<Grant>
client.identities.held(agentId: string): Promise<Page<Identity>>
```

* `attach` — `POST /v1/agents/{id}/identities`. Idempotent: re-attaching answers `attached: true, created: false`, so a provisioning script can re-run safely.
* `detach` — `DELETE /v1/agents/{id}/identities/{identity_id}`. The identity itself is untouched; running sessions are not interrupted.
* `held` — `GET /v1/agents/{id}/identities`: which personas may this agent wear.

## agents

```ts theme={"system"}
client.identities.agents(ref: string): Promise<Page<AgentRef>>
```

`GET /v1/identities/{ref}/agents` — who may wear this persona. The reverse direction of the same edge, and the read to do before deleting an identity.

## Endpoint reads

The addressable objects behind the persona's denormalised arrays — what a screen needs to show status or delete a row:

```ts theme={"system"}
client.identities.inboxes(ref: string): Promise<Page<EmailInbox>>
client.identities.deleteInbox(ref: string, inboxId: string): Promise<Deleted>
client.identities.phones(ref: string): Promise<Page<PhoneNumber>>
client.identities.releasePhone(ref: string, phoneId: string): Promise<Deleted>
client.identities.messages(ref: string, query?: { channel?: "email" | "sms" }): Promise<Page<InboundMessage>>
```

* `inboxes` — `GET /v1/identities/{ref}/emails`.
* `deleteInbox` — `DELETE /v1/identities/{ref}/emails/{inbox_id}`.
* `phones` — `GET /v1/identities/{ref}/phones`.
* `releasePhone` — `DELETE /v1/identities/{ref}/phones/{phone_id}`. **Irreversible at the carrier**: the number goes back to the pool and cannot be reclaimed.
* `messages` — `GET /v1/identities/{ref}/messages`: everything that arrived for this persona, both channels unless `channel` names one.

Creating and sending on those endpoints lives in [`emails`](/docs/sdk/emails) and [`phones`](/docs/sdk/phones); these are the identity-side reads.