Identities

An identity is a named persona an agent acts as, governed by the policy 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 guide for concepts.

The identity object

string

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

string

Human-readable name.

string | null

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

string[]

Inbox addresses on verified domains.

string[]

Provisioned numbers in E.164.

string[]

Web domains attached to the identity.

string[]

IDs of authorized third-party connections.

object

Arbitrary key/value pairs.

string

Creation timestamp.

string

When the persona was last changed.

Create an identity

POST /v1/identities

string

required

Human-readable name.

string

What the persona does. Defaults to null.

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, numbers and connections — and sending either list here is refused with validation_failed.

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

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

GET    /v1/identities            # list (cursor-paginated)
GET    /v1/identities/{id}       # retrieve
DELETE /v1/identities/{id}       # delete

See Pagination and Errors.

Update an identity

PATCH /v1/identities/{id}

string

New human-readable name.

string

New description. Send null to clear it.

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

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.

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

{
  "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 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 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
Inboxes, numbers, inbound feed	Email & SMS
Third-party accounts	Connections
Social accounts	Social
Write-only credentials	Vaults

Next: vaults

Write-only credentials injected at the network boundary.

Introduction

Core resources

Platform

Identity

The identity object

Create an identity

List, retrieve, delete

Update an identity

Binding identities to agents

Attach an identity

Detach an identity

List an agent’s identities

List an identity’s agents

Sub-resources

Next: vaults

​The identity object

​Create an identity

​List, retrieve, delete

​Update an identity

​Binding identities to agents

​Attach an identity

​Detach an identity

​List an agent’s identities

​List an identity’s agents

​Sub-resources

Next: vaults

The identity object

Create an identity

List, retrieve, delete

Update an identity

Binding identities to agents

Attach an identity

Detach an identity

List an agent’s identities

List an identity’s agents

Sub-resources