Authentication

MailShield API uses Bearer token authentication combined with optional IP allowlisting.

Creating an API Token

1. Navigate to Settings > API in your MailShield dashboard
2. Click Create Token
3. Enter a descriptive name (e.g., "Production Monitoring")
4. Optionally set an expiration date
5. Optionally add allowed IP addresses or CIDR ranges
6. Click Create

Important

Your API token will only be displayed once. Copy it immediately and store it securely.

Using Your Token

Include your token in the Authorization header of every request:

curl -H "Authorization: Bearer ms_your_token_here" \
  https://app.mailshield.app/api/v1/domains

Python Example

import requests

headers = {
    "Authorization": "Bearer ms_your_token_here"
}

response = requests.get(
    "https://app.mailshield.app/api/v1/domains",
    headers=headers
)

data = response.json()
print(data["data"])

Node.js Example

const response = await fetch('https://app.mailshield.app/api/v1/domains', {
  headers: {
    'Authorization': 'Bearer ms_your_token_here'
  }
});

const { data } = await response.json();
console.log(data);

Token Format

MailShield tokens follow this format:

• Prefix: ms_
• Body: 32 bytes of cryptographically random data (base64url encoded)
• Example: ms_Abc123XyzDefGhi456JklMnoP789QrsT

The ms_ prefix helps identify MailShield tokens and prevents accidentally using tokens from other services.

IP Allowlisting

For enhanced security, you can restrict token usage to specific IP addresses:

• Single IP: 192.168.1.100
• CIDR range: 10.0.0.0/8
• Multiple entries: One per line in the settings UI

When an IP allowlist is configured:

• Requests from allowed IPs proceed normally
• Requests from non-allowed IPs receive a 403 Forbidden response

Best Practice

For production integrations, always configure an IP allowlist to limit the blast radius if a token is compromised.

Token Expiration

Tokens can be configured to expire on a specific date:

• Never (default) - Token remains valid until revoked
• Custom date - Token expires at midnight UTC on the specified date

After expiration, the token returns 401 Unauthorized on all requests.

Revoking Tokens

To revoke a token:

1. Go to Settings > API
2. Find the token in the list
3. Click the revoke button
4. Confirm the action

Revoked tokens:

• Cannot be restored
• Return 401 Unauthorized on subsequent requests
• Usage history is preserved for audit purposes

Security Best Practices

1. Never commit tokens to version control - Use environment variables
2. Rotate tokens periodically - Create new tokens and revoke old ones
3. Use IP allowlisting - Restrict where tokens can be used from
4. Set expiration dates - Especially for temporary integrations
5. Use descriptive names - Know which token is used where
6. Monitor usage - Check "Last Used" to detect anomalies

Authentication Errors

Code	Status	Description
unauthorized	401	Missing or invalid Authorization header
unauthorized	401	Invalid or expired API token
forbidden	403	IP address not allowed for this token
forbidden	403	API access not enabled (upgrade required)