Metigan Logometigan
REST APIAuthentication

API Authentication

Learn how to authenticate your requests to the Metigan API using API keys.

Getting Your API Key

To get your API key:

  1. Log in to your Metigan Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give your key a descriptive name (e.g., "Production Server", "Development")
  5. Copy and securely store your API key
Keep Your API Key Secret

Your API key grants full access to your Metigan account. Never share it publicly, commit it to version control, or expose it in client-side code.

Using Your API Key

Include your API key in the x-api-key header with every API request:

cURL

curlTerminal
1
2
3
4
curl -X POST https://api.metigan.com/api/email/send \
  -H "x-api-key: mtg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"from": "hello@example.com", "recipients": ["user@example.com"], "subject": "Hello", "content": "<p>Hello World</p>"}'

JavaScript (fetch)

example.jsJavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
const response = await fetch('https://api.metigan.com/api/email/send', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.METIGAN_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: 'hello@example.com',
    recipients: ['user@example.com'],
    subject: 'Hello',
    content: '<p>Hello World</p>'
  })
});

Python (requests)

example.pyPython
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import os
import requests

response = requests.post(
    'https://api.metigan.com/api/email/send',
    headers={
        'x-api-key': os.environ['METIGAN_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'from': 'hello@example.com',
        'recipients': ['user@example.com'],
        'subject': 'Hello',
        'content': '<p>Hello World</p>'
    }
)

PHP

example.phpPhp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php
$ch = curl_init('https://api.metigan.com/api/email/send');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: ' . getenv('METIGAN_API_KEY'),
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'from' => 'hello@example.com',
        'recipients' => ['user@example.com'],
        'subject' => 'Hello',
        'content' => '<p>Hello World</p>'
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

API Key Types

Metigan supports different API key types for different environments:

PrefixEnvironmentDescription
mtg_live_ProductionFull access, sends real emails, counts against quota
mtg_test_Test/SandboxEmails are not sent, for development and testing
Development Tip

Use mtg_test_ keys during development to avoid sending real emails and consuming your email quota.

Environment Variables

Store your API key in environment variables to keep it secure:

.env file

.envTerminal
1
2
3
4
5
# Production
METIGAN_API_KEY=mtg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Development
METIGAN_API_KEY=mtg_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Never Commit .env Files

Add .env to your .gitignore file to prevent accidentally committing sensitive credentials.

Platform-specific Configuration

Vercel

Add to Settings → Environment Variables

Heroku

heroku config:set METIGAN_API_KEY=mtg_live_xxx

AWS

Use AWS Secrets Manager or Parameter Store

Docker

docker run -e METIGAN_API_KEY=mtg_live_xxx ...

Authentication Errors

Common authentication errors and how to resolve them:

401 Unauthorized

JSON
1
2
3
4
5
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Solution: Check that your API key is correct and included in thex-api-key header.

403 Forbidden

JSON
1
2
3
4
5
{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key does not have permission for this action"
}

Solution: Your API key may have restricted permissions or be disabled. Check your API key settings in the dashboard.

429 Rate Limited

JSON
1
2
3
4
5
6
{
  "success": false,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please retry after 60 seconds.",
  "retryAfter": 60
}

Solution: Implement exponential backoff and respect theretryAfter value.

Security Best Practices

✅ Do

  • • Store API keys in environment variables
  • • Use test keys during development
  • • Rotate keys periodically
  • • Use different keys for different environments
  • • Monitor API key usage in dashboard

❌ Don't

  • • Commit API keys to version control
  • • Expose keys in client-side JavaScript
  • • Share keys via email or chat
  • • Use production keys for testing
  • • Hard-code keys in your source code

Revoking API Keys

If you suspect your API key has been compromised:

  1. Go to Settings → API Keys in your dashboard
  2. Find the compromised key
  3. Click the Revoke button
  4. Create a new API key
  5. Update your application with the new key
Immediate Effect

Revoking an API key takes effect immediately. All requests using that key will start returning 401 errors.