Authentication

API Keys

Migma.ai uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, etc.

Creating an API Key

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.

Working with an AI agent? It can register itself and receive its own scoped key after you approve it with a code. See Agent registration.

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 and their verification status
`domain:write`	Add, verify, update, and remove sending domains
`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.

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

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

API Keys

Creating an 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

​API Keys

​Creating an 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

API Keys

Creating an 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?