Authentication
API keys, scopes, and session-based authentication
Authentication
API Keys
API keys authenticate programmatic access to the MisarMail API. They begin with msk_.
Create an API Key
- Go to Settings → API Keys at mail.misar.io/settings/api-keys
- Click New API Key
- Give it a name and select the required scopes
- Copy the key — it is shown only once
Using an API Key
Pass the key in the Authorization header of every request:
Authorization: Bearer msk_your_key_hereExample:
curl https://mail.misar.io/api/v1/send \
-H "Authorization: Bearer msk_your_key_here" \
-H "Content-Type: application/json" \
-d '{ ... }'Key Scopes
Each API key is granted specific scopes at creation. A request to an endpoint requiring a scope the key doesn't have returns 403.
| Scope | Grants Access To |
|---|---|
send | POST /v1/send — send transactional emails |
contacts | Read/write contacts and segments |
campaigns | Create, update, send campaigns |
templates | Create, update email templates |
automations | Create, update automation workflows |
analytics | Read analytics and reports |
API keys are per-user. A key can only access resources owned by the user who created it.
Key Restrictions
Optionally restrict a key to a single email account (allowed_account_id). When set, the from.email on send requests must match that account.
Revoking Keys
Keys can be revoked at any time from Settings → API Keys. Revoked keys return 401 immediately.
Session Authentication (Browser / Dashboard)
Dashboard routes (/api/accounts, /api/campaigns, etc.) accept the Supabase session cookie automatically set during login. These routes are for the UI only — use API key auth for programmatic access.
Session flow:
- User logs in via id.misar.io
- SSO JWT issued →
mail.misar.io/api/auth/ssoverifies and creates local session - Session cookie shared across
*.misar.iosubdomains
Security Best Practices
- Store API keys in environment variables — never hardcode in source code
- Use the minimum required scopes for each key
- Rotate keys periodically or after suspected compromise
- Use
idempotency_keyon send requests to avoid duplicate emails after retries