Authentication

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

Authorization: Bearer rm_a1b2c3d4e5f6...

API keys are 67 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": ["a1b2c3d4-5678-4def-abcd-111111111111"] }'

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"

When using API key authentication, you cannot revoke the key you're currently using if it's your only active key. Dashboard (session) users can revoke any key.

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 (HSTS headers enforce this in browsers)
• Monitor your account activity via GET /v1/account