Identities
How agent identities work in Loomal
An Identity is an agent's presence on a channel. Each identity gets an email address, an identity API key (loid-), and scoped permissions.
What You Get
{name}-{random}@mailgent.dev | |
| API key | loid-xxxxxxxx... — acts as this identity |
| Scopes | mail:read, mail:send, vault:read, etc. |
Two Kinds of Keys
Loomal has two, non-overlapping key types:
| Prefix | Acts as or on | Use for |
|---|---|---|
loid- | As a single identity | What the agent does as itself — send mail, vault, calendar, sign/verify |
lopk- | On the platform | Manage identities at the org level — create, list, rotate keys, update scopes, delete |
A loid- key cannot manage other identities. A lopk- key cannot act as any identity. If you're building an orchestrator that both provisions identities and also operates one of them, you'll carry both keys.
One Identity = One Key = One Inbox
Each loid- key is scoped to a single inbox. sales@mailgent.dev cannot access support@mailgent.dev. Least privilege by default.
Multiple Identities
For multi-inbox agents, create one identity per inbox and configure separate MCP servers:
{
"loomal-sales": { "command": "npx", "args": ["-y", "@loomal/mcp"], "env": { "LOOMAL_API_KEY": "loid-sales-key" } },
"loomal-support": { "command": "npx", "args": ["-y", "@loomal/mcp"], "env": { "LOOMAL_API_KEY": "loid-support-key" } }
}Each gets namespaced tools: loomal-sales:mail.send, loomal-support:mail.send.
Capabilities
Every identity is a capability hub. Toggle capabilities on/off via scopes when creating the identity (or update later in Settings).
| Capability | Scopes | Status |
|---|---|---|
| Inbox | mail:read, mail:send, mail:manage | Available |
| Vault | vault:read, vault:write | Available |
| Calendar | calendar:read, calendar:write, calendar:delete, calendar:public | Available |
| Identity (sign/verify) | identity:sign, identity:verify | Available |
| Payments (x402) | payments:accept | Beta |