Misar IO Docs

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

  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://api.misar.io/mail/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 — all email sending | | send:transactional | POST /v1/send — transactional sends only | | send:marketing | POST /v1/send — marketing sends only | | contacts | Read/write contacts, segments, scoring rules | | campaigns | Create, update, send campaigns | | templates | Create and update email templates | | automations | Create and update automation workflows | | analytics | Read analytics, reports, and tracking data | | validate | POST /v1/validate — email address validation | | read | Read-only access to all owned resources | | write | Write access to all owned resources | | sandbox | Send in sandbox mode — not delivered to real recipients | | ips | Manage dedicated IPs — Max plan |

Grant only the scopes a key needs. A key with send cannot read contacts or analytics. Scope separation limits exposure if a key is ever compromised.

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.

Managing Keys via API

API keys can also be created, listed, and revoked programmatically via session-authenticated requests. See API Keys for the full reference.

Revoking Keys

Keys can be revoked at any time from Settings → API Keys or via DELETE /api/v1/keys?id=<uuid>. 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