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

> An addressable persona an agent acts as: email, phone, social accounts, web domains, third-party connections, and a credential vault.

export const Levers = ({items, cols}) => <div style={{
  display: "grid",
  gridTemplateColumns: `repeat(${cols || 2}, minmax(0,1fr))`,
  gap: "12px",
  margin: "1.5rem 0"
}}>
    {items.map((it, i) => <div key={i} style={{
  border: "1px solid rgba(0,0,0,0.10)",
  padding: "16px 18px",
  background: "#ffffff"
}}>
        <div style={{
  fontSize: "13px",
  fontWeight: 500,
  color: "#777777"
}}>{it.k}</div>
        <div style={{
  fontSize: "15px",
  fontWeight: 500,
  margin: "6px 0 4px",
  letterSpacing: "-0.02em",
  color: "#000000"
}}>{it.v}</div>
        <div style={{
  fontSize: "14px",
  color: "#555555",
  lineHeight: 1.5
}}>{it.d}</div>
      </div>)}
  </div>;

**Vetta Identity** gives an agent a named persona it *acts as* in the world — a real participant with an address, a number, and its own authorized accounts. One agent can hold several identities; one identity can be shared by several agents.

<Note>**Available now.** Identity provisioning — domains, inboxes, numbers, connections, and the vault API — is live, governed by the [policy](/docs/concepts/policies) layer. One piece is still coming: [inbound messages](/docs/identity/inbound) are received and stored, but do not yet wake an agent.</Note>

<Card title="Identity reference" icon="id-card" href="/docs/identity/overview">
  Full detail on personas, web domains, email, phone, connections, the vault, and inbound handling.
</Card>

## Create one

An identity owns real addresses and numbers — `billing@acme.com` is a different identity from `support@acme.com`. Create it, then attach it to any agent:

```bash CLI theme={"system"}
vetta identity create --name "Acme Billing" \
  --description "Handles invoices and refunds for Acme" \
  --domain acme.com --email billing@acme.com --phone +1...
vetta identity attach --agent Refunder --identity "Acme Billing"
```

## Send and receive as the identity

Outbound, the agent sends email and SMS and calls APIs the identity has authorized. Inbound, an email or text is verified, matched, and stored — and, coming soon, will wake a sleeping agent, so waiting to be contacted costs storage, not compute.

<img src="https://mintcdn.com/vetta/rjfQyQrWaQ5bFTTq/images/identity-hub.svg?fit=max&auto=format&n=rjfQyQrWaQ5bFTTq&q=85&s=97f58ece49aeeb23378228fbb13a3747" alt="The identity hub: a persona at the center with bidirectional spokes to email, phone, web domains, connections, and the credential vault" width="900" height="440" data-path="images/identity-hub.svg" />

Inbound is guarded before it wakes anything: email must pass SPF/DKIM/DMARC, SMS is carrier-verified, webhooks must carry a valid signature. Spoofed mail cannot summon your persona. See [Inbound events](/docs/identity/inbound).

### A refund request, end to end

1. **Get reached.** A customer emails `billing@acme.com`. The mail passes SPF/DKIM/DMARC and lands in the identity's message feed — today you start the session from the stored message; the automatic wake is coming soon.
2. **Reason, don't obey.** The email body is untrusted data, never instructions — it cannot expand what [policy](/docs/identity/policies) allows.
3. **Act through a connection.** The agent calls the payments API with a vault credential it references by name and never sees.
4. **Reach out.** It replies as `billing@acme.com`, commits its turn, and sleeps at storage cost.

## Store credentials in the vault

The [vault](/docs/identity/vault) is write-only credential storage: no API returns a raw value, and the agent references a credential by name, never by value. On egress the placeholder is swapped for the real secret only for the credential's bound host — live on the [MCP connector](/docs/capabilities/tools#mcp-connector) path today, on all sandbox egress coming soon — so an authenticated API call works without the model ever seeing the key.

<Card title="Identity reference" icon="id-card" href="/docs/identity/overview">
  Personas, domains, email, phone, connections, the vault, and inbound handling in full.
</Card>