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_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:

User logs in via id.misar.io
SSO JWT issued → api.misar.io/mail/auth/sso verifies and creates local session
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