Skip to main content
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.
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.

​
Steps

1

Initialize the vault

You must initialize the vault before creating an identity. The vault stores sensitive credentials that are returned during identity creation.
{
  "agentId": "agent-abc123",
  "intent": {
    "message": "Setting up vault for new agent",
    "subject": "VAULT",
    "action": "CREATE"
  }
}
2

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.
{
  "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"
  }
}
3

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.
{
  "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.
4

Retrieve the identity

Call get_agent_identity to verify the identity was created successfully.
{
  "agentId": "agent-abc123"
}

​
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. 
{
  "agentId": "agent-abc123",
  "intent": {
    "message": "Registering agent",
    "subject": "IDENTITY",
    "action": "CREATE"
  }
}
For full parameter reference, see create_agent_identity.