API keys are the primary method for authenticating requests to the Send.dev API. This page provides detailed information about creating, managing, and securing your API keys.

API Key Structure

Send.dev API keys follow a specific format:

sk_live_xxxxxxxxxxxxxxxxxxxx
sk_test_xxxxxxxxxxxxxxxxxxxx

• sk - Indicates a secret key (server-side use only)
• live / test - Environment (production or test)
• xxxx... - 32-character unique identifier

Creating API Keys

Via Dashboard

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Configure options:
   • Name: Descriptive label for identification
   • Environment: Live or Test
   • Domain Restrictions: Optional—limit which domains this key can send from
   • Expiration: Optional—auto-expire the key after a date
4. Click Create

Via API

curl -X POST https://api.send.dev/v1/api-keys \
  -H "Authorization: Bearer sk_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "environment": "live",
    "domains": ["mail.yourdomain.com"],
    "expires_at": "2026-01-01T00:00:00Z"
  }'

{
"id": "key_01HXYZ123456789",
"name": "Production Server",
"key": "sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
"environment": "live",
"domains": ["mail.yourdomain.com"],
"created_at": "2025-01-13T10:00:00Z",
"expires_at": "2026-01-01T00:00:00Z",
"last_used_at": null
}

Listing API Keys

curl https://api.send.dev/v1/api-keys \
  -H "Authorization: Bearer sk_live_admin_key"

{
"data": [
  {
    "id": "key_01HXYZ123456789",
    "name": "Production Server",
    "environment": "live",
    "domains": ["mail.yourdomain.com"],
    "created_at": "2025-01-13T10:00:00Z",
    "expires_at": "2026-01-01T00:00:00Z",
    "last_used_at": "2025-01-13T12:30:00Z"
  },
  {
    "id": "key_01HABC987654321",
    "name": "Development",
    "environment": "test",
    "domains": null,
    "created_at": "2025-01-10T09:00:00Z",
    "expires_at": null,
    "last_used_at": "2025-01-12T15:45:00Z"
  }
],
"has_more": false
}

Note that the actual key value is never returned after creation for security reasons.

Revoking API Keys

curl -X DELETE https://api.send.dev/v1/api-keys/key_01HXYZ123456789 \
  -H "Authorization: Bearer sk_live_admin_key"

{
"id": "key_01HXYZ123456789",
"revoked": true,
"revoked_at": "2025-01-13T14:00:00Z"
}

Domain-Scoped Keys

For enhanced security, you can restrict API keys to specific sending domains:

Benefits

1. Blast Radius Reduction - If a key is compromised, attackers can only send from specific domains
2. Team Isolation - Give different teams keys for their domains only
3. Environment Separation - Use different domains for staging vs. production

Configuration

When creating a key, specify the domains array:

{
  "name": "Marketing Team",
  "domains": ["marketing.yourdomain.com", "promo.yourdomain.com"]
}

Attempts to send from unauthorized domains will return:

{
  "error": {
    "code": "domain_not_authorized",
    "message": "API key not authorized to send from 'other.domain.com'",
    "authorized_domains": ["marketing.yourdomain.com", "promo.yourdomain.com"]
  }
}

Key Rotation

Regular key rotation is a security best practice. Here's a recommended approach:

1. Create a new key with the same permissions
2. Update your application to use the new key
3. Deploy and verify the application works with the new key
4. Revoke the old key once you've confirmed the new key works
5. Repeat on a regular schedule (e.g., every 90 days)

Zero-Downtime Rotation

Send.dev supports overlapping keys, so you can:

1. Create a new key while the old one is still active
2. Both keys work simultaneously during the transition
3. Revoke the old key once migration is complete

Monitoring & Usage

Track API key usage in your dashboard:

• Last Used: When the key was last used
• Request Count: Number of requests made
• Success Rate: Percentage of successful requests
• Error Rate: Percentage of failed requests

Use this data to:

• Identify unused keys for cleanup
• Detect unusual activity patterns
• Debug integration issues

Security Checklist

• Never commit API keys to version control
• Use environment variables for key storage
• Restrict keys to specific domains when possible
• Set expiration dates for temporary keys
• Rotate keys regularly (every 90 days recommended)
• Revoke unused keys promptly
• Monitor key usage for anomalies
• Use test keys for development environments