Authentication

Overview

All Artmail API requests require authentication using an API key. API keys provide secure access to your account and can be scoped with specific permissions and restrictions.

API Key Format

Artmail API keys follow this format:

art_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx art_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: art_live_ for production keys, art_test_ for test keys
• Length: 45 characters total (8-character prefix + 32-character random string)
• Characters: Alphanumeric (a-z, A-Z, 0-9)

Creating an API Key

You can create API keys from your Artmail dashboard:

Using Your API Key

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

Using Bearer Token (Recommended)

Direct Header (Also Supported)

You can also include the key directly without the "Bearer" prefix:

cURL Example

Permissions

API keys can be configured with specific permissions to limit what actions they can perform. Available permissions include:

When you create an API key, you can select which permissions to grant. If a request requires a permission that the key doesn't have, you'll receive a 403 Forbidden error.

Security Best Practices

Follow these guidelines to keep your API keys secure:

item Never Commit Keys to Version Control Use environment variables or secure secret management services. Add .env files to .gitignore. :::item Rotate Keys Regularly Create new keys and revoke old ones periodically, especially if a key may have been compromised. :::item Use IP Restrictions Limit API key usage to specific IP addresses when possible to prevent unauthorized access. :::item Use Domain Restrictions If your application runs on specific domains, restrict the key to those domains. :::item Set Expiration Dates Configure keys to expire automatically after a set period. :::item Use Test Keys for Development Always use art_test_ keys in development and staging environments. :::item Monitor Key Usage Regularly review API key usage in your dashboard to detect suspicious activity. :::endwarning

Key Restrictions

You can configure API keys with restrictions to enhance security:

IP Address Restrictions

Limit key usage to specific IP addresses:

If a request comes from an IP not in the allowed list, you'll receive a 403 Forbidden error with code IP_BLOCKED.

Domain Restrictions

Limit key usage to specific domains:

If a request comes from a domain not in the allowed list, you'll receive a 403 Forbidden error with code DOMAIN_BLOCKED.

Expiration

Set an expiration date for the key:

Expired keys will return a 401 Unauthorized error with code EXPIRED.

Managing API Keys

You can manage your API keys through the API or dashboard:

List All Keys

Get Key Details

Update Key

Revoke Key

Authentication Errors

If authentication fails, you'll receive one of these error responses:

Missing API Key

Status Code: 401 Unauthorized

Solution: Include the Authorization header in your request.

Invalid API Key

Status Code: 401 Unauthorized

Solution: Verify your API key is correct and hasn't been revoked.

Expired Key

Status Code: 401 Unauthorized

Solution: Create a new API key or update the expiration date.

IP Blocked

Status Code: 403 Forbidden

Solution: Add your IP address to the key's allowed IPs list, or remove IP restrictions.

Domain Blocked

Status Code: 403 Forbidden

Solution: Add your domain to the key's allowed domains list, or remove domain restrictions.

Insufficient Permissions

Status Code: 403 Forbidden

Solution: Update the key's permissions to include the required action.

Testing Authentication

You can test your API key authentication with a simple request:

If authentication is successful, you'll receive a response (even if it's an empty list). If authentication fails, you'll receive an error response.

Next Steps

Now that you understand authentication: