Authentication

Overview

Every request to the MisarMail API, MCP server, and SDKs is authenticated with an API key. MisarMail keys:

• are product-bound — a MisarMail key works only with MisarMail (api.misar.io/mail/*). It cannot be used with any other Misar product (Reach, Dev, Post, SEO, …), and their keys cannot be used with MisarMail.
• grant full access — a key can call every public MisarMail endpoint (send, contacts, campaigns, templates, analytics, validation, …). Keys are not feature-scoped; you never have to pick permissions when creating one.
• are plan-gated — the number of active keys you can hold is set by your active MisarMail subscription.

Creating a key

1. Sign in at misarmail.com and open the MisarMail dashboard.
2. Go to Settings → API Keys (mail.misar.io/settings/api-keys).
3. Click New API Key, give it a name (e.g. Production), and copy the secret.

The raw key is shown once at creation — store it somewhere safe. If you lose it, revoke the key and create a new one.

MisarMail keys always begin with the msk_ prefix, so they are easy to recognize in logs and secret scanners:

msk_your_key_here

The number of active keys you can hold is limited by your MisarMail subscription. If you hit the limit, revoke an unused key or upgrade your plan.

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. This is an optional deliverability guard — it does not narrow the key's full API access.

Using a 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 '{ ... }'

The same key works with the MisarMail SDKs and the MCP server.

Product binding

MisarMail validates every key against its own database. A key issued by another Misar product is not present there, so it is rejected — and vice-versa. This means:

• A MisarMail msk_ key returns 401 Unauthorized on api.misar.io/reach/*, …/dev/*, …/post/*, etc.
• A MisarReach mrk_ key (or any other product's key) returns 401 Unauthorized on api.misar.io/mail/*.

There is no way to "share" one key across products — issue a separate key from each product's dashboard for each product you integrate with.

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 → api.misar.io/mail/auth/sso verifies and creates local session
3. Session cookie shared across *.misar.io subdomains

Errors

Security Best Practices

• Store API keys in environment variables — never hardcode in source code
• Treat every key as full-access — issue one key per integration so you can rotate them independently
• Rotate keys periodically or after suspected compromise
• Use idempotency_key on send requests to avoid duplicate emails after retries