# Authentication

Most API endpoints require authentication via API key or session cookie. Public endpoints like signup do not.

## API key authentication

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

```http
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.


## Key scoping

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
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](https://robotomail.com/docs/api/api-keys) for the full list of which operations require full access.


## Key rotation

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.

```curl
# 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.


## Session authentication

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.


## Security best practices

- 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`


---

Previous: [Quickstart](https://robotomail.com/docs/quickstart.md) | Next: [Mailboxes](https://robotomail.com/docs/concepts/mailboxes.md)