API Token Management

API tokens allow you to access the MailShield REST API programmatically. This guide covers how to create, manage, and secure your API tokens.

Organization owners and admins manage tokens under Settings > API. Members can't see or create tokens.

Creating a Token

1. Navigate to Settings > API
2. Click Create Token
3. Enter a descriptive name (e.g., "CI/CD Pipeline" or "Monitoring Script")
4. Optionally add a description
5. Configure security settings (see below)
6. Click Create Token

Important

The full token is only shown once, right after you create it. Copy it and store it somewhere safe, such as a secrets manager. The dialog stays open until you click Done.

Token Security Settings

Read-only

A read-only token can only call GET endpoints: it can read domains, customers, scores, reports and alerts, but can't change anything. Any other request (POST, PATCH, DELETE) returns 403 with the message "This token is read-only."

Use read-only tokens for dashboards, reporting scripts and other integrations that only read data. You choose this when you create the token; to change it later, create a new token.

IP Allowlist

Restrict which IP addresses can use this token. Leave empty to allow any IP.

Enter one entry per line:

• A single IPv4 or IPv6 address: 203.0.113.50, 2001:db8::1
• A CIDR range: 203.0.113.0/24, 2001:db8::/32

Entries are checked when you save, so a typo is reported instead of silently locking the token out. IPv6 addresses match whatever their case or notation.

TIP

Use IP allowlists for production tokens to add an extra layer of security.

Expiration Date

Set an optional expiration date for the token. The token works until 23:59 UTC on that date, then stops working. The token list shows the exact expiry time in UTC.

Recommended for:

• Temporary access for contractors
• Time-limited integrations
• Compliance requirements

Token Visibility

For security, tokens are stored as SHA-256 hashes. In the dashboard, you'll see:

• Token name and description
• Whether the token is read-only
• Last 4 characters (e.g., ...a1b2)
• Last used timestamp and IP
• Status and expiration

Managing Tokens

Viewing Token Activity

Click the activity icon next to a token to see its recent API requests, including:

• Request timestamps
• Endpoints and methods
• Response status codes and times
• IP addresses and user agents
• The first 4 KB of each request and response body

The activity view shows the last 100 requests from the past 30 days. It stays available after a token is revoked or expires.

Updating Settings

Click the edit icon to change a token's:

• Name and description
• IP allowlist
• Expiration date

The token value and the read-only setting can't be changed. Create a new token instead.

Revoking Tokens

To revoke a token:

1. Go to Settings > API
2. Click the revoke icon next to the token
3. Confirm the action

DANGER

Revoking a token is immediate and permanent. Any integrations using this token will stop working.

Best Practices

Use Descriptive Names

Name tokens after their purpose:

• GitHub Actions - Deploy
• Datadog Integration
• Weekly Report Script

Principle of Least Privilege

Create separate tokens for different integrations rather than sharing one token across multiple systems. Make a token read-only unless the integration needs to change something.

Regular Rotation

Periodically rotate tokens, especially for long-running integrations:

1. Create a new token
2. Update your integration
3. Verify it works
4. Revoke the old token

Monitor Usage

Regularly review token activity to:

• Detect unusual activity
• Identify unused tokens
• Verify integrations are working

Plan Requirements

API access is included in Pro and Enterprise. The Free plan does not include API access. See Plans and Billing.

Plan	API Access
Free	No
Pro	Yes
Enterprise	Yes

If your organization moves to the Free plan, or a failed payment isn't fixed within the grace period, the API refuses requests and existing tokens are paused. Owners and admins can still see the tokens, view their activity and revoke them. Paused tokens work again once API access is back, so revoke any you no longer need.