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

# Create an Identity

> Provision a full online identity for an agent, including email, phone, and virtual card.

Agentity can provision a complete online identity for an agent in two steps: initialize the agent's encrypted vault, then call `create_agent_identity` to provision the channels you need.

<Warning>
  For some providers, virtual card details (PAN, CVV, expiry) are only returned once. If you don't save them immediately, you cannot retrieve them again.
</Warning>

## Steps

<Steps>
  <Step title="Initialize the vault">
    You must initialize the vault before creating an identity. The vault stores sensitive credentials that are returned during identity creation.

    ```json theme={null}
    {
      "agentId": "agent-abc123",
      "intent": {
        "message": "Setting up vault for new agent",
        "subject": "VAULT",
        "action": "CREATE"
      }
    }
    ```
  </Step>

  <Step title="Create the identity">
    Call `create_agent_identity` with the channels you want to provision. All three channels are optional — include only the ones you need.

    ```json theme={null}
    {
      "agentId": "agent-abc123",
      "intent": {
        "message": "Provisioning identity for web automation agent",
        "subject": "IDENTITY",
        "action": "CREATE"
      },
      "email": {
        "issuer": "agentmail",
        "username": "myagent",
        "domain": "agentmail.to",
        "displayName": "My Agent"
      },
      "phone": {
        "issuer": "agentphone"
      },
      "virtualCard": {
        "issuer": "privacy",
        "type": "SINGLE_USE"
      }
    }
    ```
  </Step>

  <Step title="Store the card details">
    The response includes the virtual card's PAN, CVV, and expiry. Save them to the vault immediately using `save_secret_to_vault` before the response is discarded.

    ```json theme={null}
    {
      "agentId": "agent-abc123",
      "secretKey": "card_pan",
      "secretValue": "4111111111111111",
      "intent": {
        "message": "Storing card PAN after identity creation",
        "subject": "VAULT",
        "action": "CREATE"
      }
    }
    ```

    Repeat the call for `card_cvv` and any other fields you want to persist.
  </Step>

  <Step title="Retrieve the identity">
    Call `get_agent_identity` to verify the identity was created successfully.

    ```json theme={null}
    {
      "agentId": "agent-abc123"
    }
    ```
  </Step>
</Steps>

## Minimal identity

All channels are optional. You can create a shell identity with just `agentId` and `intent` — useful when you want to register an agent before deciding which channels it needs.

```json theme={null}
{
  "agentId": "agent-abc123",
  "intent": {
    "message": "Registering agent",
    "subject": "IDENTITY",
    "action": "CREATE"
  }
}
```