Authentication

Learn how to authenticate your API requests and manage API keys securely.

Quick Start

The MimeProtect API uses API keys to authenticate requests. Include your API key in theAuthorization header of every request.

curl -X GET "https://api.mimeprotect.com/v1/domains" \
  -H "Authorization: Bearer mp_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Getting an API Key

Create and manage your API keys in the dashboard

1
Sign in to MimeProtect
Log in to your account at mimeprotect.com/auth/login
2
Navigate to API Settings
Go to Settings → API Keys in your dashboard
3
Create a New API Key
Click "Create API Key", give it a name, and select the required permissions (scopes)
4
Copy Your Key
Copy the key immediately - you won't be able to see it again. Keys are prefixed with mp_

API Key Format

All MimeProtect API keys begin with the prefix mp_ followed by a unique identifier. Example: mp_a1b2c3d4e5f6...

Authentication Header

How to include your API key in requests

Include your API key in the Authorization header using the Bearer token scheme:

Authorization: Bearer mp_xxxxxxxxxxxxxxxxxxxxx

Important

Never include your API key in URLs, query parameters, or client-side JavaScript. Always use the Authorization header and make API calls from your server.

API Key Scopes

Control what each API key can access with fine-grained permissions

When creating an API key, you can select specific scopes to limit what the key can access. Follow the principle of least privilege - only grant the permissions your integration needs.

Scope	Type	Description
`domains:read`	Read	View domain list, domain details, and DNS configuration status
`domains:write`	Write	Add new domains, update domain settings, and delete domains
`reports:read`	Read	View DMARC aggregate reports, TLS-RPT reports, and report analytics
`alerts:read`	Read	View security alerts and alert history
`alerts:write`	Write	Acknowledge, dismiss, or update alert status
`scans:trigger`	Action	Initiate on-demand domain scans for DNS configuration checks

Rate Limiting

Understand API rate limits and how to handle them

To ensure fair usage and API stability, requests are rate limited per API key.

100

requests per minute

Per API Key

rate limit scope

Rate Limit Headers

All API responses include headers to help you track your rate limit status:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute (100)
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff and respect the Retry-After header.

Error Responses

Common authentication errors and how to handle them

401

Unauthorized

The API key is missing, invalid, or has been revoked.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

403

Forbidden

The API key is valid but doesn't have the required scope for this operation.

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions. Required scope: domains:write",
    "status": 403
  }
}

429

Rate Limit Exceeded

Too many requests have been made. Wait before retrying.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "status": 429,
    "retryAfter": 60
  }
}

Code Examples

Examples of authenticating with the MimeProtect API in different languages

curl -X GET "https://api.mimeprotect.com/v1/domains" \
  -H "Authorization: Bearer mp_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Security Best Practices

Keep your API keys secure and your integration safe

Never commit API keys to source control

Use environment variables or a secrets manager. Add .env to your .gitignore file.

Rotate keys regularly

Create new API keys periodically and revoke old ones. This limits the impact if a key is compromised.

Use minimal scopes

Only grant the permissions your integration actually needs. Create separate keys for different services with their own minimal scope sets.

Keep keys server-side

Never expose API keys in client-side code, mobile apps, or browser JavaScript. All API calls should be made from your backend server.

Revoke compromised keys immediately

If you suspect a key has been exposed, revoke it immediately in your API settings and create a new one.

Monitor API key usage

Regularly review your API key activity in the dashboard. Unusual patterns may indicate unauthorized access.

Ready to get started?

Create your first API key and explore the API reference to start integrating MimeProtect.

Create API Key View API Reference