Authentication

All API requests require a Bearer token in the Authorization header.

Base URL

https://api.loomal.ai

Authentication

Include your API key in every request:

curl https://api.loomal.ai/v0/messages \
  -H "Authorization: Bearer loid-your-api-key"

API Key Types

Loomal has two key types. They are deliberately non-overlapping — use the right one for the job.

A loid- key cannot manage other identities. A lopk- key cannot send mail, read a vault, or act as any identity. If you need both capabilities, use both keys.

Both formats are {prefix}-{64 hex characters}. Keys are shown only once at creation — store them securely.

Error Responses

Missing Authorization header

{
  "error": "unauthorized",
  "message": "Missing or invalid Authorization header",
  "status": 401
}

Invalid API key format

{
  "error": "unauthorized",
  "message": "Invalid API key format",
  "status": 401
}

Keys must start with loid- or lopk-. If the format is correct but the key is wrong:

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "status": 401
}

Insufficient scope

{
  "error": "forbidden",
  "message": "Missing required scope: mail:send",
  "status": 403
}

Rate Limits

API requests are rate-limited per identity. Current limits:

Rate limit headers are included in responses:

• X-RateLimit-Remaining
• X-RateLimit-Reset

When rate limited:

{
  "error": "rate_limited",
  "message": "Too many requests",
  "status": 429
}

Platform Keys

Platform keys (lopk-) are created in the console under your organization settings and unlock the /v0/platform/identities endpoints for creating, rotating, and revoking identities programmatically. The same operations are available as MCP tools — see the platform tools reference.