For Agents

Sign up without a human in the loop. One API call returns a working Identity — inbox, vault, calendar, DID, USDC wallet on Base, and an API key.

Setting up Loomal manually in the Console? See For Humans instead.

What's an Identity?

A single agent persona with its own bundle of capabilities. When you create one with empty body, you get:

One agent can own multiple Identities under one Org — useful when an agent runs distinct personas (sales, support, research) each with its own inbox.

This page assumes you want an Identity (the default — full bundle of mail/vault/calendar/payments/wallet/DID). If you're shipping a paid endpoint instead, see For Sellers. Concept refresher: Introduction.

Flow

One API call and your agent is running. Sign up creates the User, Org, platform key, and your first Identity in the same response — no second round-trip before you can use mail / vault / payments.

1. Check for an existing identity

Before calling /v0/agent-signup, look for ~/.loomal/agent.json. If it exists, read the saved platform_key and call GET /v0/whoami with Authorization: Bearer <platform_key> — if that returns 200, you're already signed up; skip step 2 and use the credentials on disk.

2. Sign up

POST /v0/agent-signup
Content-Type: application/json

{}

Returns 201 with the full bundle inline:

{
  "user_id": "user_a3f91b00",
  "user_email": "bright-quiet-otter-k3f9a@mailgent.dev",
  "org_id": "org_xq2k9m",
  "platform_key": "lopk-a3f91b00...",
  "agent_card_url": "https://api.loomal.ai/.well-known/agents/org_xq2k9m",
  "identity": {
    "identityId": "id-a3f91b00c2d54e87",
    "name": "bright-quiet-otter",
    "emailAddress": "bright-quiet-otter-k3f9a@mailgent.dev",
    "scopes": ["mail:read", "mail:send", "vault:read", "vault:write", "payments:spend", "..."],
    "apiKeyPrefix": "loid-a3f91b00",
    "rawKey": "loid-a3f91b00..."
  }
}

Save the full response to ~/.loomal/agent.json immediately. Both keys are shown only once. Rate-limited to 10/min/IP.

The user_email is the first Identity's inbox — one working address, not two. If a human later takes over the org, they already have a real address to verify.

Use the identity.rawKey (loid-…) for every subsequent mail / vault / calendar / payment call. Hold on to the platform_key (lopk-…) only if you'll want to create additional Identities later (see below).

Need more Identities?

The signup response is enough for most agents — one Identity, one inbox, one wallet. Call POST /v0/platform/identities with your saved lopk-… whenever you want another (sales + support + research personas under the same Org, or a Seller project alongside your default Identity, etc.).

POST /v0/platform/identities
Authorization: Bearer lopk-...
Content-Type: application/json

{}

Returns another loid-… and a fresh <slug>@mailgent.dev inbox. Append it to ~/.loomal/agent.json under identities[]. Pass { "purpose": "SELLER" } to get the seller bundle instead.

Supporting endpoints

GET /v0/whoami

Accepts both loid-… (identity) and lopk-… (platform) keys. The response shape branches on what you authenticated with:

• Bearer loid-… → single-Identity detail (scopes, inbox, wallet, etc.).
• Bearer lopk-… → org-admin view: User + Org + list of all Identities under the org.

So the same endpoint lets agents (a) verify a saved platform key is still valid and (b) discover what identities they've already created — one URL for both keys.

Example (lopk-… response):

{
  "user": { "id": "user_...", "userType": "AGENT", "name": "bright-quiet-otter", "email": "bright-quiet-otter-k3f9a@mailgent.dev" },
  "org": { "id": "org_xq2k9m", "plan": "FREE" },
  "identities": [
    { "identityId": "id-...", "name": "bright-quiet-otter", "email": "bright-quiet-otter-k3f9a@mailgent.dev" }
  ]
}

GET /v0/identity-types

Returns descriptions of what each project type provides (Identity vs Seller) so the agent can pick rather than guess.

GET /v0/agent-signup/cli

Returns paste-ready install + login text:

Install the Loomal CLI:
  curl -fsSL https://loomal.ai/install | bash

Then log in:
  loomal login --api-key "loid-..." --org "org_..."

Pipe this into whatever shell or coding agent you're running.

Mail and other tools

After you have a loid-…, use the existing per-resource APIs:

• Mail — GET /v0/messages, POST /v0/messages/send, etc.
• Vault — store credentials and TOTP seeds.
• Calendar
• Payments — pay any x402-priced URL under your mandate cap.

Key types

Both are bearer tokens. Both are shown once at creation, hashed at rest, revocable.

Your email

Every Identity has an inbox at <slug>-<5char>@mailgent.dev (e.g. bright-quiet-otter-k3f9a@mailgent.dev). The slug is a 3-word kebab-case combination; the 5-char alphanumeric suffix is collision insurance. The email is permanent — it can't be changed after creation, but the display name can.

Use this address when signing up to third-party SaaS the agent later needs. Loomal's MX handles inbound mail; read it via mail_list_messages / mail_get_message. Seller projects skip the inbox.

Agent keys vs other Loomal keys

The lopk-… you get from /v0/agent-signup is the same key type Loomal already issues to human Org admins from the Console. There's no special "agent surface" — agents are users (userType: AGENT on the existing User table), so every existing route works for them unchanged.

The agent doesn't need any new SDK or special handshake. Pass Authorization: Bearer lopk-… to /v0/platform/identities/* for project management, or Authorization: Bearer loid-… to anything project-scoped (mail, vault, calendar, payments). That's the whole API surface.

Related

• Loomal MCP server — just-in-time tool calls from Cursor, Claude Code, etc.
• A2A Agent Card at https://api.loomal.ai/.well-known/agents/<org_id> so other agents can discover yours.