identities.create
Create a new agent identity with an email inbox and API key
Key type: Platform (lopk-)
Create a new agent identity. This provisions an email inbox and generates an API key. The raw key is returned once — store it securely.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name (e.g. "Sales Agent") |
emailName | string | Yes | Email prefix (e.g. "salesagent") — a random suffix is appended |
scopes | string[] | Yes | Permission scopes to grant |
Available scopes: mail:read, mail:send, mail:manage, vault:read, vault:write, identity:sign, identity:verify, calendar:read, calendar:write, calendar:delete, calendar:public
Example
Orchestrator: "Create a new support agent"
-> identities.create({
name: "Support Agent",
emailName: "support",
scopes: ["mail:read", "mail:send", "mail:manage"]
})Returns
{
"identityId": "id-def456",
"name": "Support Agent",
"emailAddress": "support-f3x9w@mailgent.dev",
"apiKeyPrefix": "loid-b2c4d6e8",
"rawKey": "loid-b2c4d6e8...",
"scopes": ["mail:read", "mail:send", "mail:manage"],
"createdAt": "2026-04-06T12:00:00.000Z"
}The rawKey is only shown once. Store it immediately.
REST Equivalent
POST /v0/platform/identities