Skip to main content

​
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

1

Navigate to Settings

Log in to migma.ai and go to Settings → API Integration
2

Create New Key

Click Create API Key in the API Keys tab
3

Configure Permissions

Give your key a name and select the permissions it needs
4

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('sk_live_1234567890abcdef');
const { data, error } = await migma.projects.list();
cURL
curl https://api.migma.ai/v1/projects \
  -H "Authorization: Bearer sk_live_1234567890abcdef"
JavaScript
const response = await fetch('https://api.migma.ai/v1/projects', {
  headers: {
    'Authorization': 'Bearer sk_live_1234567890abcdef'
  }
});
Python
import requests

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

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:
PermissionDescription
audience:readView subscribers, tags, and audience segments
audience:writeAdd, update subscribers, manage tags, create segments
email:readView email templates and sending history
email:sendSend emails to subscribers using templates
email:validateTest email compatibility, check links, and analyze deliverability
email:previewGenerate email previews across multiple devices and email clients
template:readRead and use email templates
domain:readView sending domains and their verification status
domain:writeAdd, verify, update, and remove sending domains
project:writeImport projects and manage project resources
webhook:readList and view webhook configurations
webhook:writeCreate, 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

​
1. Store Keys Securely

Never hardcode API keys in your source code. Use environment variables:
Node.js SDK
// ❌ Don't do this
const migma = new Migma('sk_live_1234567890abcdef');

// ✅ Do this
const migma = new Migma(process.env.MIGMA_API_KEY);
JavaScript
// ❌ Don't do this
const apiKey = 'sk_live_1234567890abcdef';

// ✅ Do this
const apiKey = process.env.MIGMA_API_KEY;

​
2. Use Environment Variables

.env
MIGMA_API_KEY=sk_live_1234567890abcdef
Node.js SDK
import Migma from 'migma';

const migma = new Migma(process.env.MIGMA_API_KEY);
JavaScript
require('dotenv').config();

const apiKey = process.env.MIGMA_API_KEY;

​
3. Rotate Keys Regularly

Create new API keys periodically and revoke old ones:
  1. Create a new API key with the same permissions
  2. Update your application to use the new key
  3. Test thoroughly
  4. Revoke the old key

​
4. Use Read-Only Keys When Possible

If your application only needs to read data, create a key with only read permissions: 
// Key with only read permissions
const readOnlyHeaders = {
  'Authorization': `Bearer ${process.env.MIGMA_READONLY_KEY}`
};

​
5. Monitor Key Usage

Check your API key usage regularly in the Migma dashboard:
  • Go to Settings → API Integration → API Keys
  • View last used date for each key
  • Check for any unexpected usage patterns

​
Key Management

​
Viewing Your Keys

Navigate to Settings → API Integration → 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:
1

Find the Key

Go to Settings → API Integration → API Keys
2

Delete

Click the delete icon next to the key
3

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:
PlanRate Limit
Free10 requests/minute
Pro100 requests/minute
EnterpriseCustom limits
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.

​
Testing Authentication

Test your API key with a simple request:
cURL
curl https://api.migma.ai/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"
Expected response for valid key: 
{
  "success": true,
  "data": {
    "projects": [],
    "total": 0
  }
}

​
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