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

<Info>An identity is a named persona an agent acts as, governed by the [policy](/docs/concepts/policies) layer.</Info>

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](/docs/identity/overview) guide for concepts.

## The identity object

<ResponseField name="id" type="string">Unique id (e.g. `idn_01H...`).</ResponseField>
<ResponseField name="name" type="string">Human-readable name.</ResponseField>
<ResponseField name="description" type="string | null">What this persona is for; helps agents choose between multiple identities.</ResponseField>
<ResponseField name="emails" type="string[]">Inbox addresses on verified domains.</ResponseField>
<ResponseField name="phones" type="string[]">Provisioned numbers in E.164.</ResponseField>
<ResponseField name="domains" type="string[]">Web domains attached to the identity.</ResponseField>
<ResponseField name="connections" type="string[]">IDs of authorized third-party connections.</ResponseField>
<ResponseField name="metadata" type="object">Arbitrary key/value pairs.</ResponseField>
<ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">When the persona was last changed.</ResponseField>

## Create an identity

`POST /v1/identities`

<ParamField body="name" type="string" required>Human-readable name.</ParamField>
<ParamField body="description" type="string">What the persona does. Defaults to `null`.</ParamField>
<ParamField body="metadata" type="object">Arbitrary key/value pairs.</ParamField>

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

<CodeGroup>
  ```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"
    }'
  ```
</CodeGroup>

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>

## List, retrieve, delete

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

See [Pagination](/docs/api/pagination) and [Errors](/docs/api/errors).

## Update an identity

`PATCH /v1/identities/{id}`

<ParamField body="name" type="string">New human-readable name.</ParamField>
<ParamField body="description" type="string">New description. Send `null` to clear it.</ParamField>
<ParamField body="metadata" type="object">Replaces the metadata object wholesale.</ParamField>

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`

<ParamField body="identity" type="string" required>The `idn_` identity to grant.</ParamField>

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.

<CodeGroup>
  ```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..." }'
  ```
</CodeGroup>

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

**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](/docs/api/pagination) 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](/docs/api/pagination) 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](/docs/api/domains)         |
| Inboxes, numbers, inbound feed | [Email & SMS](/docs/api/messaging)   |
| Third-party accounts           | [Connections](/docs/api/connections) |
| Social accounts                | [Social](/docs/api/social)           |
| Write-only credentials         | [Vaults](/docs/api/vaults)           |

<Card title="Next: vaults" icon="lock" href="/docs/api/vaults">
  Write-only credentials injected at the network boundary.
</Card>