Authenticate Migma API Requests

Start here

Hosted MCP: add https://migma.ai/mcp and approve in the browser. See MCP Server. IT reviewers: MCP for IT admins.
CLI: run migma login. Same browser sign-in; the key is stored locally.
Direct agents without a working OAuth callback: fetch https://api.migma.ai/auth.md and approve the claim code. They must be able to call the API, poll, and securely store the returned credential. See Agent registration.
CI and servers: set MIGMA_API_KEY. Create a Settings key only for this case.

API Keys

Migma.ai uses API keys to authenticate requests. Browser OAuth and claim-code both mint a key for you. Keep keys out of client-side code and git.

Creating a CI API Key

Use this only for CI, cron, or server automation. Agents and the CLI should not start here.

Navigate to Settings

Create New Key

Click Create API Key in the API Keys tab

Configure Permissions

Give your key a name and select the permissions it needs

Save Securely

Copy the key immediately - it won’t be shown again!

API keys are shown only once at creation. Store them securely in a password manager or environment variables.

Using Your API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Example Request

Node.js SDK

import Migma from 'migma';

// The SDK handles the Authorization header automatically
const migma = new Migma('YOUR_MIGMA_API_KEY');
const { data, error } = await migma.projects.list();

cURL

curl https://api.migma.ai/v1/projects \
  -H "Authorization: Bearer YOUR_MIGMA_API_KEY"

JavaScript

const response = await fetch('https://api.migma.ai/v1/projects', {
  headers: {
    'Authorization': 'Bearer YOUR_MIGMA_API_KEY'
  }
});

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_MIGMA_API_KEY'
}

response = requests.get(
    'https://api.migma.ai/v1/projects',
    headers=headers
)

API Key Permissions

When creating an API key, you can grant specific permissions to limit what the key can access.

Audience Permissions

Permission	Description
`audience:read`	View subscribers, tags, and audience segments
`audience:write`	Add, update subscribers, manage tags, create segments
`email:read`	View email templates and sending history
`email:write`	Create and edit generated emails
`email:send`	Send test and live emails
`email:validate`	Test email compatibility, check links, and analyze deliverability
`email:preview`	Generate email previews across multiple devices and email clients
`domain:read`	View sending domains, verification and purchase status, and custom DNS on domains bought in Migma
`domain:write`	Add, verify, update, and remove sending domains; buy a domain (Stripe checkout the account owner opens); manage custom DNS on domains bought in Migma
`billing:read`	View plan and credits
`billing:write`	Create Stripe checkout or billing portal links the account owner opens and approves
`campaign:read`	View campaigns, stats, and delivery logs
`campaign:write`	Create, send, schedule, cancel, archive, and unarchive campaigns
`project:write`	Import projects and manage project resources
`webhook:read`	List and view webhook configurations
`webhook:write`	Create, update, and delete webhooks for real-time notifications

Follow the principle of least privilege: only grant the permissions your application needs.

email:send allows test and direct email. campaign:write allows campaign creation, send, and schedule. Omitting scope grants the full permission set — the approval page shows every permission and marks send as destructive. Pass an explicit scope to narrow access.

Environment-Specific Keys

Use different API keys for different environments:

Development

MIGMA_API_KEY=sk_test_...

Production

MIGMA_API_KEY=sk_live_...

Test keys start with sk_test_ and production keys start with sk_live_

Security best practices

Never hardcode keys — use environment variables: const migma = new Migma(process.env.MIGMA_API_KEY)
Least privilege — only grant the permissions your integration actually needs
Rotate periodically — create a new key, update your app, then revoke the old one
Monitor usage — check last-used dates in Settings → Developers → API Keys and revoke anything unexpected
Remote agents — keep claim tokens and returned keys out of chat, logs, shell history, and shared remote-computer files

Key Management

Viewing Your Keys

Navigate to Settings → Developers → API Keys to see:

Key name and ID (first 8 characters)
Permissions granted
Creation date
Last used date
Usage statistics

Revoking a Key

If a key is compromised or no longer needed:

Find the Key

Go to Settings → Developers → API Keys

Delete

Click the delete icon next to the key

Confirm

Confirm the deletion - this action cannot be undone

Revoking a key will immediately invalidate it. Any applications using that key will receive 401 Unauthorized errors.

Error Responses

401 Unauthorized

Your API key is invalid or missing:

{
  "success": false,
  "error": "Invalid or missing API key"
}

Common causes:

API key not included in Authorization header
Wrong format (must be Bearer YOUR_KEY)
Key has been revoked
Using test key in production environment

403 Forbidden

Your API key doesn’t have permission for this action:

{
  "success": false,
  "error": "Insufficient permissions"
}

Solution: Create a new key with the required permissions or update the existing key’s permissions.

Rate Limiting

API keys are subject to rate limits based on your plan:

Plan	Requests / minute	Requests / day
Standard	500	10,000
Enterprise	1,000	50,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Implement exponential backoff when you receive 429 responses to avoid further rate limiting.

Need help?

Quickstart

Get started with your first API call

Node.js SDK

SDK handles authentication automatically

CLI

migma login to authenticate the CLI

API Reference

Full endpoint documentation

Overview

Developer Tools

Guides

API endpoints

Authenticate Migma API Requests

Start here

API Keys

Creating a CI API Key

Using Your API Key

Example Request

API Key Permissions

Audience Permissions

Environment-Specific Keys

Security best practices

Key Management

Viewing Your Keys

Revoking a Key

Error Responses

401 Unauthorized

403 Forbidden

Rate Limiting

Need help?

Quickstart

Node.js SDK

CLI

API Reference

​Start here

​API Keys

​Creating a CI API Key

​Using Your API Key

​Example Request

​API Key Permissions

​Audience Permissions

​Environment-Specific Keys

​Security best practices

​Key Management

​Viewing Your Keys

​Revoking a Key

​Error Responses

​401 Unauthorized

​403 Forbidden

​Rate Limiting

​Need help?

Quickstart

Node.js SDK

CLI

API Reference

Start here

API Keys

Creating a CI API Key

Using Your API Key

Example Request

API Key Permissions

Audience Permissions

Environment-Specific Keys

Security best practices

Key Management

Viewing Your Keys

Revoking a Key

Error Responses

401 Unauthorized

403 Forbidden

Rate Limiting

Need help?