> ## 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

> Create and manage the personas an agent acts as — email, phone, web domains, and connections.

> [!NOTE]
>
> An identity is a named persona an agent acts as, governed by the [policy](https://vetta.sh/docs/concepts/policies.md) layer.

An identity is a named persona that owns communication endpoints and connections. One agent can hold several identities; one identity can be shared by several agents. See the [Identity](https://vetta.sh/docs/identity/overview.md) guide for concepts.

## The identity object

**id** `string`

Unique id (e.g. `idn_01H...`).

**name** `string`

Human-readable name.

**description** `string | null`

What this persona is for; helps agents choose between multiple identities.

**emails** `string[]`

Inbox addresses on verified domains.

**phones** `string[]`

Provisioned numbers in E.164.

**domains** `string[]`

Web domains attached to the identity.

**connections** `string[]`

IDs of authorized third-party connections.

**metadata** `object`

Arbitrary key/value pairs.

**created\_at** `string`

Creation timestamp.

**updated\_at** `string`

When the persona was last changed.

## Create an identity

`POST /v1/identities`

**name** `string` *required*

Human-readable name.

**description** `string`

What the persona does. Defaults to `null`.

**metadata** `object`

Arbitrary key/value pairs.

A persona is created empty. Its `emails`, `phones`, `domains` and `connections` are reads of sub-resources minted through their own routes — [inboxes](https://vetta.sh/docs/api/messaging.md#create-an-inbox), [numbers](https://vetta.sh/docs/api/messaging.md#provision-a-number) and [connections](https://vetta.sh/docs/api/connections.md) — and sending either list here is refused with `validation_failed`.

```bash cURL theme={"system"}
curl -fsSL https://api.vetta.sh/v1/identities \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "name": "Acme Billing",
    "description": "Handles invoices and refunds for Acme"
  }'
```

```json Response theme={"system"}
{
  "id": "idn_01H9AB...",
  "object": "identity",
  "name": "Acme Billing",
  "description": "Handles invoices and refunds for Acme",
  "emails": [],
  "phones": [],
  "domains": [],
  "connections": [],
  "metadata": {},
  "created_at": "2026-08-20T17:00:00Z",
  "updated_at": "2026-08-20T17:00:00Z"
}
```

## List, retrieve, delete

```bash theme={"system"}
GET    /v1/identities            # list (cursor-paginated)
GET    /v1/identities/{id}       # retrieve
DELETE /v1/identities/{id}       # delete
```

See [Pagination](https://vetta.sh/docs/api/pagination.md) and [Errors](https://vetta.sh/docs/api/errors.md).

## Update an identity

`PATCH /v1/identities/{id}`

**name** `string`

New human-readable name.

**description** `string`

New description. Send `null` to clear it.

**metadata** `object`

Replaces the metadata object wholesale.

All fields are optional; omitted fields are left unchanged. The read-only lists — `emails`, `phones`, `domains`, `connections` — cannot be patched here; manage them through their own routes.

## Binding identities to agents

The grant is a **many-to-many** edge, and it hangs off the **agent** — the question it answers is which personas *that agent* may act as. Four routes, read from either side.

### Attach an identity

`POST /v1/agents/{id}/identities` — scope `agents:write`

**identity** `string` *required*

The `idn_` identity to grant.

Returns the grant, echoed back. It is **idempotent**: attaching a persona that is already attached succeeds with `attached: true` and `created: false`, so a re-run of a provisioning script is safe.

```bash cURL theme={"system"}
curl -fsSL https://api.vetta.sh/v1/agents/agt_01H.../identities \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "identity": "idn_01H9AB..." }'
```

```json Response theme={"system"}
{
  "object": "identity_grant",
  "agent_id": "agt_01H...",
  "identity_id": "idn_01H9AB...",
  "attached": true,
  "created": false
}
```

**Errors** — `not_found` (404) for an unknown agent or identity; `insufficient_scope` (403) without `agents:write`.

### Detach an identity

`DELETE /v1/agents/{id}/identities/{identity_id}` — scope `agents:write`

Removes the grant. The identity itself is untouched and stays available to any other agent that holds it. Sessions already running under the persona are not interrupted; the next session cannot select it.

### List an agent's identities

`GET /v1/agents/{id}/identities` — scope `agents:read`. A [paginated list](https://vetta.sh/docs/api/pagination.md) of full identity objects — *which personas may this agent wear.*

### List an identity's agents

`GET /v1/identities/{id}/agents` — scope `agents:read`. A [paginated list](https://vetta.sh/docs/api/pagination.md) of agent references — *who may wear this persona.* The reverse direction of the same edge, and the one to check before deleting an identity.

## Sub-resources

| Resource | Reference |
| - | - |
| Sending and receiving domains | [Domains](https://vetta.sh/docs/api/domains.md) |
| Inboxes, numbers, inbound feed | [Email & SMS](https://vetta.sh/docs/api/messaging.md) |
| Third-party accounts | [Connections](https://vetta.sh/docs/api/connections.md) |
| Social accounts | [Social](https://vetta.sh/docs/api/social.md) |
| Write-only credentials | [Vaults](https://vetta.sh/docs/api/vaults.md) |

> [card] [Next: vaults](https://vetta.sh/docs/api/vaults.md)
>
> Write-only credentials injected at the network boundary.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.