Authentication

API Keys

API keys authenticate programmatic access to the MisarMail API. They begin with msk_.

Create an API Key

1. Go to Settings → API Keys at mail.misar.io/settings/api-keys
2. Click New API Key
3. Give it a name and select the required scopes
4. 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_here

Example:

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.

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:

1. User logs in via id.misar.io
2. SSO JWT issued → mail.misar.io/api/auth/sso verifies and creates local session
3. Session cookie shared across *.misar.io subdomains

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_key on send requests to avoid duplicate emails after retries