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

# Identity

> Named personas an agent acts as: web domains, email, phone, connections, and a credential vault.

<Info>**Available now.** The provisioning and communication tooling — domains, inboxes, numbers, connections, and the vault API — is live, gated by the [policy](/docs/concepts/policies) layer. The [inbound wake](/docs/identity/inbound) (a stored inbound message starting a session) is coming soon.</Info>

An **identity** is a named, described persona an agent acts as in the world. It is the difference between an anonymous script and a real participant that can hold an inbox, answer a text, authorize a third-party app, and use a secret it can never read.

An identity bundles what a persona needs to act in the world:

<CardGroup cols={2}>
  <Card title="Web domains" icon="globe">
    The verified domains an identity sends and receives on — auto-provisioned, brought-your-own, or purchased through Vetta.
  </Card>

  <Card title="Email" icon="mail">
    Real inboxes on a verified domain. Send and receive as a specific address.
  </Card>

  <Card title="Phone" icon="phone">
    Provisioned numbers with carrier-registered (A2P) messaging. Send and receive SMS.
  </Card>

  <Card title="Connections" icon="plug">
    Third-party apps the identity has authorized over OAuth ("Passport").
  </Card>

  <Card title="Credential vault" icon="lock" href="/docs/identity/vault">
    A write-only secret store. Values are injected at the network boundary — the agent never sees them.
  </Card>

  <Card title="Agent wallet" icon="wallet">
    <span>**Coming soon · Phase 5.**</span> A spend-limited wallet so the persona can pay for things in the world, gated by policy.
  </Card>
</CardGroup>

## Identities are concrete, and many-to-many

An identity has a `name` and a `description` so the agent knows *who it is being*. Crucially, its communication endpoints are **specific addresses and numbers**, not booleans:

* `billing@acme.com` is a **different identity** from `support@acme.com`.
* `+1 415 555 0142` belongs to one identity, not "the org".

The relationship between agents and identities is many-to-many:

* **One agent can hold multiple identities** — e.g. an inbound support persona and an outbound sales persona — and choose which to act as per task.
* **One identity can be shared by multiple agents** — e.g. a `billing@acme.com` persona handled by a triage agent and a refunds agent.

See [Personas](/docs/identity/personas) for the identity object itself and how it attaches to agents.

## Create an identity

<CodeGroup>
  ```bash CLI theme={"system"}
  vetta identity create \
    --name "Ava Sales" \
    --description "Outbound SDR persona for the growth team"

  # Give it endpoints
  vetta identity email provision --identity ava --address ava@acme-mail.com
  vetta identity phone provision --identity ava --tier sole-prop
  vetta identity connect         --identity ava --auth-config ac_...
  ```

  ```typescript TypeScript theme={"system"}
  import { randomUUID } from "node:crypto";
  import { createClient } from "@usenaive-sdk/vetta";

  const vetta = createClient({
    baseUrl: "https://api.vetta.sh",
    apiKey: process.env.VETTA_API_KEY!,
    fetch: globalThis.fetch,
    idempotencyKey: () => randomUUID(),
  });

  const identity = await vetta.identities.create({
    name: "Ava Sales",
    description: "Outbound SDR persona for the growth team",
  });
  ```

  ```bash cURL theme={"system"}
  curl https://api.vetta.sh/v1/identities \
    -H "Authorization: Bearer $VETTA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Ava Sales",
      "description": "Outbound SDR persona for the growth team"
    }'
  ```
</CodeGroup>

## Attach it to an agent

An agent references identities and picks one to act as. Manage the product at the agent level and the actor at the session level.

<CodeGroup>
  ```bash CLI theme={"system"}
  vetta agent create --name Refunder \
    --model zai-org/GLM-5.2-FP8 \
    --harness pi \
    --identity ava \
    --tools send_email,connection_call \
    --budget-usd 50 --max-task-usd 5 --budget-period month
  ```

  ```typescript TypeScript theme={"system"}
  const agent = await vetta.agents.create({
    name: "Refunder",
    model: "zai-org/GLM-5.2-FP8",
    harness: "pi",
    identities: ["ava"],
    tools: ["send_email", "connection_call"],
    budget: { capUsd: 50, maxTaskUsd: 5, period: "month" },
  });
  ```
</CodeGroup>

<Note>
  The `harness: "pi"` field selects the [harness](/docs/how-vetta-is-built#the-three-layers) — the agent loop; the [completion window](/docs/concepts/completion-window) (`immediate` · `priority` · `loose`) is the only latency knob. Neither affects which identity an agent acts as — that is chosen per session.
</Note>

## How the pieces fit

```
identity "Ava Sales"
   ├── web domains ......  acme-mail.com (verified: email + app tracks)
   ├── email .............  ava@acme-mail.com  (inbox, tied to an owning agent)
   ├── phone .............  +1 415 555 0142    (A2P campaign approved)
   ├── connections .......  gmail, slack       (OAuth, per-user scoped)
   ├── vault .............  STRIPE_API_KEY, ...  (write-only, egress-injected)
   └── wallet ............  $/txn + allowlist    (coming soon · Phase 5)
        ▲
        └── every action above is gated by the identity's policy (fails closed)
```

Everything an identity can do is enforced at the tool-call boundary by [policies](/docs/identity/policies), which resolve *before* any external request is made.

<Card title="Next: personas" icon="id-card" href="/docs/identity/personas">
  The identity object — its fields, the endpoints it owns, and attaching it to agents.
</Card>