> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentity.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Identities

> An identity is a bundle of real-world credentials tied to a single agent — email, phone, virtual card, and vault in one place.

An identity is a set of real-world credentials provisioned for a single AI agent. Each identity is keyed to an `agentId` string you define — a unique identifier for the agent within your account.

## What makes up an identity

When you call `create_agent_identity`, Agentity provisions the channels you request and returns their credentials in a single response.

| Channel          | Provider    | Returned fields                                | Required |
| ---------------- | ----------- | ---------------------------------------------- | -------- |
| **Email**        | AgentMail   | `emailAddress`, `emailId`                      | No       |
| **Phone**        | AgentPhone  | `phoneNumber, phoneNumberId`                   | No       |
| **Virtual card** | Privacy.com | `pan`, `cvv`, `exp_year`, `exp_month`, `token` | No       |
| Crypto Wallet    | Ethereum    | `cryptoAddress`<br />`network`                 | No       |

Each channel is optional. You can provision any combination — or none at all. Support for more providers is coming soon.

### Email

A real inbox provisioned by the chosen provider. Agentity stores the `emailAddress` and `emailId` so you can look them up later.

### Phone

An SMS-capable phone number. Agentity stores the `phoneNumber`.

### Virtual card

A virtual payment card. Agentity stores only the `token` — a stable reference to the card at the provider. Depending on provider, the full card details (`pan`, `cvv`, `exp_year`, `exp_month`) are only shared **once** at agent creation. You may want to have your agent immediately store the details in its vault.

### Crypto Wallet

A network-specific crypto wallet. Agentity stores the `address` and the private key (which is encrypted). The agent can get the wallet's balance and send crypto to different addresses on the same network.

## Shell identities

You can create an identity with no channels by omitting `email`, `phone`, `virtualCard` , and `cryptoWallet` from the request. This creates a "shell" identity that reserves the `agentId` and gives you a vault namespace to write to. You can provision channels for that agent later.

## agentId uniqueness

Each `agentId` is unique per account. Attempting to create a second identity with the same `agentId` returns an error.

## Response shape

A successful `create_agent_identity` call returns a JSON object. Fields are omitted if the corresponding channel was not provisioned or if provisioning failed.

```json theme={null}
{
  "emailAddress": "myagent@acme.agentmail.to",
  "emailId": "inbox_01abc",
  "phoneNumber": "+14155550123",
  "virtualCard": {
    "pan": "4111111111111111",
    "cvv": "123",
    "exp_year": "2027",
    "exp_month": "09",
    "token": "tok_01xyz"
  }
}
```

If a channel fails to provision, the response includes a corresponding error field (`emailErrorMessage`, `phoneErrorMessage`, `virtualCardErrorMessage`) alongside any channels that did succeed.

```json theme={null}
{
  "emailAddress": "myagent@acme.agentmail.to",
  "emailId": "inbox_01abc",
  "virtualCardErrorMessage": "Error creating virtual card: insufficient funds"
}
```