Authentication

Pass your API key in the Authorization header as a Bearer token:

Authorization: Bearer rm_a1b2c3d4e5f6...

API keys are 68 characters long: the rm_ prefix followed by 64 hex characters (256 bits of entropy). Keys are stored as SHA-256 hashes — the raw key is returned only at creation time and cannot be retrieved later.

API keys come in two flavors:

• Full-access keys — Can perform all operations including creating mailboxes, managing domains, generating new API keys, and accessing billing.
• Mailbox-scoped keys — Restricted to specific mailboxes. Can only send/receive messages, manage webhooks, and update settings for those mailboxes. Ideal for giving an agent access to its own mailbox without exposing the full account.

Create a scoped key by passing mailboxIds when creating a key:

curl -X POST https://api.robotomail.com/v1/api-keys \
  -H "Authorization: Bearer $ROBOTOMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "agent-inbox", "mailboxIds": ["mbx_..."] }'

See API Keys reference for the full list of which operations require full access.

To rotate a key: create a new key, update your application to use it, then revoke the old key. You can have multiple active keys simultaneously.

# 1. Create new key
curl -X POST https://api.robotomail.com/v1/api-keys \
  -H "Authorization: Bearer $OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "rotated-key" }'

# 2. Update your app to use the new key

# 3. Revoke the old key
curl -X DELETE https://api.robotomail.com/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer $NEW_KEY"

You cannot revoke your last active key — at least one must remain active at all times.

The Robotomail dashboard uses session cookies managed by BetterAuth. Session-based authentication always has full access (no scoping). This is for the web dashboard only — agents should always use API keys.

• Never commit API keys to source control — use environment variables
• Use mailbox-scoped keys when an agent only needs access to its own mailbox
• Rotate keys regularly, especially if a key may have been exposed
• Use HTTPS for all API requests (HTTP is rejected)
• Monitor your account activity via GET /v1/account