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

**Naive Managed Agents 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](https://vetta.sh/docs/concepts/policies.md) layer. One piece is still coming: [inbound messages](https://vetta.sh/docs/identity/inbound.md) are received and stored, but do not yet wake an agent.

> [card] [Identity reference](https://vetta.sh/docs/identity/overview.md)
>
> Full detail on personas, web domains, email, phone, connections, the vault, and inbound handling.

## 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 agt_01j8rf6tq2m4vz9xkp3n7c5hwd --identity "Acme Billing"
```

## Send and receive as the identity

Outbound, the agent sends email and calls APIs the identity has authorized; SMS is sent from the API and CLI, not from an agent. Inbound, an email or text is verified, matched, stored, and wakes the agent that owns the inbox or number, so waiting to be contacted costs storage, not compute.

![The identity hub: a persona at the center with bidirectional spokes to email, phone, web domains, connections, and the credential vault](https://mintcdn.com/vetta/rjfQyQrWaQ5bFTTq/images/identity-hub.svg?fit=max\&auto=format\&n=rjfQyQrWaQ5bFTTq\&q=85\&s=97f58ece49aeeb23378228fbb13a3747)

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](https://vetta.sh/docs/identity/inbound.md).

### 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, which starts a session for the inbox's owning agent.
2. **Reason, don't obey.** The email body is untrusted data, never instructions — it cannot expand what [policy](https://vetta.sh/docs/identity/policies.md) 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](https://vetta.sh/docs/identity/vault.md) 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](https://vetta.sh/docs/capabilities/tools.md#mcp-connector) path today, on all sandbox egress coming soon — so an authenticated API call works without the model ever seeing the key.

> [card] [Identity reference](https://vetta.sh/docs/identity/overview.md)
>
> Personas, domains, email, phone, connections, the vault, and inbound handling in full.


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