Authentication
API keys, scopes, and how to keep your credentials safe.
Every request is authenticated with a secret API key, sent as a bearer token.
Keys begin with m123_ and are created from your dashboard under Settings →
API. Pass your key in the Authorization header on every request:
Authorization: Bearer m123_your_api_keyYour key is shown only once, at creation. Store it in a secret manager or environment variable — never commit it to source control or ship it in client-side code.
Scopes
Each key carries a scope that limits what it can do. Pick the narrowest scope that fits the job.
| Scope | Can do | Use it for |
|---|---|---|
sending | Send transactional email (/v1/emails) only. | Embedding in an app that just fires email — it can't read your audience. |
full | Everything: email, contacts, groups, campaigns, templates, and viewing domains. | Server-side integrations that manage your audience and campaigns. |
Projects
A key is authorized for one or more projects (workspaces). When you create a key you choose its reach:
- All projects — works for every project you own, including ones you create later.
- Specific projects — limited to the projects you select.
Each request acts on a single project. When a key covers exactly one project (the
common case), that project is used automatically and you don't need to do
anything. When a key covers several, name the target project with the
X-Project-Id header:
curl https://your-app.com/api/v1/contacts \
-H "Authorization: Bearer m123_your_api_key" \
-H "X-Project-Id: 665f0c2a9b1e4d3a2c1f0e9d"Omitting the header on a multi-project key returns 400 validation_error asking
you to specify one; passing a project the key isn't authorized for returns
403 forbidden. List the projects a key can act on:
curl https://your-app.com/api/v1/projects \
-H "Authorization: Bearer m123_your_api_key"Rotating & revoking
Create separate keys per environment (production, staging) so you can rotate one
without disrupting the others. If a key leaks, revoke it from Settings → API —
revocation takes effect immediately and is irreversible. A revoked or unknown
key returns 401 unauthorized.
Errors
Missing, malformed, invalid, or revoked keys return 401. Using a sending key
on a full-access endpoint returns 403 insufficient_scope. See the
error reference for the full list.