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.

Using Your API Key

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

Authorization: Bearer YOUR_API_KEY

Example Request

cURL

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

JavaScript

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

Python

import requests

headers = {
    'Authorization': 'Bearer mgma_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:

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:send`	Send emails to subscribers using templates
`template:read`	Read and use email templates
`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=mgma_sk_test_...

Production

MIGMA_API_KEY=mgma_sk_live_...

Test keys start with mgma_sk_test_ and production keys start with mgma_sk_live_

Security Best Practices

1. Store Keys Securely

Never hardcode API keys in your source code. Use environment variables:

JavaScript

// ❌ Don't do this
const apiKey = 'mgma_sk_live_1234567890abcdef';

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

2. Use Environment Variables

.env

MIGMA_API_KEY=mgma_sk_live_1234567890abcdef

JavaScript

require('dotenv').config();

const apiKey = process.env.MIGMA_API_KEY;

3. Rotate Keys Regularly

Create new API keys periodically and revoke old ones:

Create a new API key with the same permissions
Update your application to use the new key
Test thoroughly
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:

Find the Key

Go to Settings → API Integration → 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	Rate Limit
Free	10 requests/minute
Pro	100 requests/minute
Enterprise	Custom 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
  }
}

Getting Started

Integration Guides

API Endpoints

API Keys

Creating an API Key

Using Your API Key

Example Request

API Key Permissions

Environment-Specific Keys

Security Best Practices

1. Store Keys Securely

2. Use Environment Variables

3. Rotate Keys Regularly

4. Use Read-Only Keys When Possible

5. Monitor Key Usage

Key Management

Viewing Your Keys

Revoking a Key

Error Responses

401 Unauthorized

403 Forbidden

Rate Limiting

Testing Authentication

Need Help?

Quickstart Guide

API Reference

Getting Started

Integration Guides

API Endpoints

​API Keys

​Creating an API Key

​Using Your API Key

​Example Request

​API Key Permissions

​Environment-Specific Keys

​Security Best Practices

​1. Store Keys Securely

​2. Use Environment Variables

​3. Rotate Keys Regularly

​4. Use Read-Only Keys When Possible

​5. Monitor Key Usage

​Key Management

​Viewing Your Keys

​Revoking a Key

​Error Responses

​401 Unauthorized

​403 Forbidden

​Rate Limiting

​Testing Authentication

​Need Help?

Quickstart Guide

API Reference

API Keys

Creating an API Key

Using Your API Key

Example Request

API Key Permissions

Environment-Specific Keys

Security Best Practices

1. Store Keys Securely

2. Use Environment Variables

3. Rotate Keys Regularly

4. Use Read-Only Keys When Possible

5. Monitor Key Usage

Key Management

Viewing Your Keys

Revoking a Key

Error Responses

401 Unauthorized

403 Forbidden

Rate Limiting

Testing Authentication

Need Help?