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 | No |
| Virtual card | Privacy.com | pan, cvv, exp_year, exp_month, token | No |
Email
A real inbox provisioned via AgentMail. Agentity stores the emailAddress and emailId so you can look them up later.
Phone
An SMS-capable phone number provisioned via AgentPhone. Agentity stores the phoneNumber.
Virtual card
A single-use payment card provisioned via Privacy.com. Agentity stores only the token — a stable reference to the card at the provider. The full card details (pan, cvv, exp_year, exp_month) are returned once at creation time and never stored.
Virtual card details (PAN, CVV, expiry) are returned only once at creation time. Store them in your agent’s vault immediately.
Shell identities
You can create an identity with no channels by omitting email, phone, and virtualCard 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.
{
"emailAddress": "myagent@acme.agentmail.to",
"emailId": "inbox_01abc",
"phoneNumber": "+14155550123",
"virtualCard": {
"pan": "4111111111111111",
"cvv": "123",
"exp_year": "2027",
"exp_month": "09",
"token": "tok_01xyz"
}
}
emailErrorMessage, phoneErrorMessage, virtualCardErrorMessage) alongside any channels that did succeed.
{
"emailAddress": "myagent@acme.agentmail.to",
"emailId": "inbox_01abc",
"virtualCardErrorMessage": "Error creating virtual card: insufficient funds"
}