Authentication & Security

Overview

Spamidate uses a two-key authentication system (similar to Stripe) for maximum security and flexibility:

• Secret Keys (sk_live_...) - For server-side API calls (kept private)
• Publishable Keys (pk_live_...) - For client-side usage (can be public)

All keys are securely hashed using SHA-256 and validated on every request.

Two-Key System Explained

Secret Keys (sk_live_…)

Use for: Server-side API calls, backend integrations, automated workflows

Security:

• Stored as SHA-256 hash in database (irreversible)
• Shown ONCE at creation (cannot be retrieved later)
• Full access to all API operations
• Must be kept private and secure

Example: sk_live_r4nD0mStr1ngH3r3Th4tIsS3cur3AndL0ng

Publishable Keys (pk_live_…)

Use for: Client-side validations, public-facing forms, browser JavaScript

Security:

• Can be safely exposed in client-side code
• Stored in plaintext (can be viewed anytime in dashboard)
• Limited to read-only operations
• Cannot perform sensitive actions

Example: pk_live_another_random_string_for_public_use

When to use which key

• Secret Key: Backend API calls, cron jobs, server-to-server communication
• Publishable Key: Contact forms, email signup widgets, client-side validation

Getting Your API Keys

1. Log in to your Dashboard
2. Navigate to API Keys tab
3. Click Create New API Key
4. Enter a descriptive name (5-100 characters):
   • Good: “Production Web Server”, “Mobile App v2.1”
   • Bad: “key1”, “test”, “mykey”
5. Save both keys immediately:
   • ⚠️ Secret key shown ONCE (cannot be retrieved)
   • ✅ Publishable key always visible in dashboard

Critical Security Warning

Secret keys cannot be retrieved after creation. If lost, you must create a new key and update your applications. Store keys in environment variables or secret managers (AWS Secrets Manager, HashiCorp Vault, etc.).

Authentication Methods

1. X-API-Key Header (Recommended)

The most secure method for production applications.

cURL

curl -X POST https://api.spamidate.com/validate \
  -H "X-API-Key: sk_live_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

JavaScript

const response = await fetch('https://api.spamidate.com/validate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SPAMIDATE_SECRET_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email: 'user@example.com' })
});

const result = await response.json();

Python

import os
import requests

headers = {
    'X-API-Key': os.environ['SPAMIDATE_SECRET_KEY'],
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.spamidate.com/validate',
    headers=headers,
    json={'email': 'user@example.com'}
)

2. Authorization Bearer Token

Standard OAuth-style bearer token authentication.

curl -X POST https://api.spamidate.com/validate \
  -H "Authorization: Bearer sk_live_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

3. Query Parameter (DISABLED IN PRODUCTION)

Production Security Block

Query parameters are automatically disabled in production for security:

• Keys visible in server logs
• Exposed in browser history
• Leaked via analytics tools
• Sent in Referer headers

Status: Development only (for testing convenience)

# ❌ BLOCKED in production
# ✅ Works in development only
curl "https://api.spamidate.com/validate?api_key=sk_live_..." \
  -X POST \
  -d '{"email": "test@example.com"}'

Advanced Security Features

Scopes & Permissions (Granular Access Control)

Restrict API keys to specific operations using scope-based permissions:

Standard Scopes

Scope	Description	Example Use Case
validate:read	View validation results	Analytics dashboard
validate:write	Perform email validation	Contact forms
bulk:*	All bulk operations	Batch processing
webhooks:read	View webhook configs	Monitoring tools
webhooks:write	Create/update webhooks	Integration setup
analytics:read	View usage statistics	Reporting systems
keys:write	Create/rotate keys	Admin panels
*:*	Full access (admin scope)	Service accounts

Creating Scoped Keys

cURL

curl -X POST https://api.spamidate.com/api/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-Only Analytics Key",
    "scopes": ["validate:read", "analytics:read"]
  }'

JavaScript

const response = await fetch('https://api.spamidate.com/api/keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Bulk Processor',
    scopes: ['bulk:*']
  })
});

Error Response (insufficient permissions):

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This operation requires the 'validate:write' permission. Your API key does not have this scope.",
    "requiredScope": "validate:write",
    "grantedScopes": ["validate:read"]
  }
}

Backward Compatibility

Keys created without scopes default to null (full access) for backward compatibility.

IP Whitelisting (Network Access Control)

Restrict API keys to specific IP addresses or CIDR ranges:

Supported Formats

• Exact IP: 192.168.1.50
• IPv4 CIDR: 192.168.1.0/24 (matches 192.168.1.0 - 192.168.1.255)
• IPv6 CIDR: 2001:db8::/32
• Multiple IPs: Array of mixed formats

Creating IP-Restricted Keys

curl -X POST https://api.spamidate.com/api/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type": application/json" \
  -d '{
    "name": "Production Server",
    "allowedIps": ["10.0.1.50", "10.0.1.51", "192.168.1.0/24"]
  }'

Error Response (IP not allowed):

{
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Access denied. Your IP address (203.0.113.45) is not in the API key's allowlist.",
    "clientIp": "203.0.113.45",
    "allowedIps": ["10.0.1.50", "192.168.1.0/24"]
  }
}

Cloudflare Integration

IP extraction uses Cloudflare headers (CF-Connecting-IP, X-Forwarded-For) for accurate detection behind CDNs.

Automated Key Rotation (PCI-DSS Compliance)

90-day rotation policy enforced automatically for compliance:

Rotation Lifecycle

Day	Event
Day 0	Key created
Day 83	First warning email (7 days before)
Day 86	Second warning email (4 days before)
Day 89	Final warning email (1 day before)
Day 90	Auto-rotate (if enabled) or enter grace period
Day 97	Deactivated (if not rotated during grace period)

Manual Rotation

curl -X POST https://api.spamidate.com/api/keys/:id/refresh \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response:

{
  "success": true,
  "message": "API key refreshed successfully. Old key is now invalid.",
  "key": {
    "id": 123,
    "secretKey": "sk_live_NEW_KEY_SHOWN_ONCE",
    "publishableKey": "pk_live_SAME_AS_BEFORE",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "warning": "Save this new key securely. You will not be able to see it again."
}

Emergency Revoke All

For security incidents, instantly deactivate all keys:

curl -X POST https://api.spamidate.com/api/keys/revoke-all \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response:

{
  "success": true,
  "message": "Successfully revoked 5 API key(s). All keys are now inactive.",
  "revokedCount": 5,
  "warning": "Create new API keys to restore access. Previous keys cannot be recovered."
}

Compliance

PCI-DSS v4.0 Requirement 8.3.9: Credentials must be changed at least every 90 days.

Rate Limiting

Rate limits enforce fair usage and prevent abuse:

Limits by Tier

Tier	Requests/Minute	Requests/Day	Monthly Volume	Key Limit	Price
Growth	10	167	5K	2 keys	$19/mo
Pro	23	333	10K	3 keys	$49/mo
Business	93	1,333	40K	5 keys	$149/mo
Scale	289	4,167	125K	8 keys	$399/mo
Enterprise	2,000	60,000	1.8M	20 keys	$799/mo
Enterprise Plus	5,000	150,000	4.5M	Unlimited	$2,499/mo

Enterprise Tier Upgrades (2025)

• Enterprise: Increased 3x to 2,000 req/min (120K/hour, 1.8M/month) - beats all competitors
• Enterprise Plus: New white-label tier at 5,000 req/min (300K/hour, 4.5M/month) - 3x faster than ZeroBounce

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9542
X-RateLimit-Reset: 2025-01-16T00:00:00Z

Hybrid Overage Model

Unique 20% grace buffer for burst traffic:

• 0-100%: ✅ Normal operation
• 100-120%: ⚠️ Grace period (requests allowed with warning)
• 120%+: ❌ Hard block until reset

Example (1,000 req/day quota):

• 0-1,000 requests: All processed normally
• 1,001-1,200 requests: Processed with overage warning
• 1,201+ requests: Blocked until next day

429 Response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Hard limit reached (120% of plan). Usage: 1250/1000. Overage will be billed at period end.",
    "retryAfter": 45
  }
}

Security Best Practices

✅ Do This

• Store keys in environment variables (never hardcode)
• Use secret managers (AWS Secrets Manager, Vault, Doppler)
• Separate keys per environment (dev, staging, production)
• Enable IP whitelisting for production keys
• Use scoped keys for least-privilege access
• Monitor key usage in dashboard analytics
• Rotate keys every 90 days (automated)
• Revoke compromised keys immediately

❌ Never Do This

• ❌ Commit keys to Git/version control
• ❌ Expose secret keys in client-side code
• ❌ Share keys via email/Slack/unencrypted channels
• ❌ Use query parameters in production
• ❌ Log API keys in application logs
• ❌ Reuse keys across multiple applications
• ❌ Ignore rotation warnings

Audit Logging

All security-sensitive actions are logged:

• API key creation, deletion, rotation
• Failed authentication attempts
• Permission violations (scope errors)
• IP whitelist rejections
• Rate limit violations
• Emergency revocations

View audit logs: Dashboard → Security → Audit Trail

Compliance: SOC 2, PCI-DSS, GDPR Article 30

Troubleshooting

Error: Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or inactive API key"
  }
}

Solutions:

• Verify key copied correctly (no extra spaces)
• Check key not revoked in dashboard
• Ensure using correct environment’s key
• Confirm key not expired

Error: Missing API Key

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Provide via X-API-Key header or Authorization Bearer token."
  }
}

Solutions:

• Add X-API-Key or Authorization header
• Verify header name spelling (case-sensitive)
• Remove query parameter (disabled in production)

Error: Insufficient Permissions

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This operation requires the 'validate:write' permission."
  }
}

Solutions:

• Check key scopes in dashboard
• Create new key with required scopes
• Use admin key (*:* scope) if appropriate

Error: IP Not Allowed

{
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Your IP address is not in the API key's allowlist."
  }
}

Solutions:

• Add your IP to key’s allowlist
• Use CIDR range for dynamic IPs
• Temporarily remove IP restriction for testing
• Verify using correct network/VPN

White-Label & Reseller Features (Enterprise Plus)

The Enterprise Plus tier ($2,499/month) includes comprehensive white-label and reseller capabilities for agencies, SaaS platforms, and partners.

Custom Domain Setup

Use your own branded domain for the API:

Example: validation.yourcompany.com instead of api.spamidate.com

Setup Steps:

1. Contact sales to enable white-label features
2. Add CNAME record: validation.yourcompany.com → api.spamidate.com
3. SSL automatically provisioned via Cloudflare
4. Test endpoint: https://validation.yourcompany.com/validate

Branded API Responses

Customize all API responses with your branding:

{
  "isValid": true,
  "email": "user@example.com",
  "score": 95,
  "metadata": {
    "provider": "YourCompany",           // Your company name
    "support": "support@yourcompany.com", // Your support email
    "documentation": "https://docs.yourcompany.com"  // Your docs URL
    // "Powered by Spamidate" removed
  }
}

Reseller Sub-User Management

Create and manage end-customers from your dashboard:

Create Sub-User:

curl -X POST https://api.spamidate.com/api/sub-users \
  -H "Authorization: Bearer YOUR_ENTERPRISE_PLUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "name": "Customer Company",
    "tier": "pro"
  }'

Features:

• Unlimited sub-users (or configure max limit)
• Isolated API keys per customer
• Usage tracking and analytics per customer
• Commission tracking (default 20%)
• Bulk customer onboarding

Commission Tracking

Automatically track revenue sharing:

curl -X GET https://api.spamidate.com/api/commissions \
  -H "Authorization: Bearer YOUR_ENTERPRISE_PLUS_KEY"

Response:

{
  "period": "2025-01",
  "totalRevenue": 4500.00,
  "commissionRate": 20.0,
  "commissionEarned": 900.00,
  "subUsers": [
    {
      "id": "sub_123",
      "email": "customer1@example.com",
      "requests": 15000,
      "revenue": 1500.00,
      "commission": 300.00
    }
  ]
}

White-Label Documentation

Branded documentation portal with your:

• Company logo and colors
• Custom domain (docs.yourcompany.com)
• Support links and contact info
• All Spamidate branding removed

Access: Contact sales for custom documentation setup

Enterprise Plus Benefits Summary

Feature	Included	Description
Custom Domain	✅	Your own API endpoint domain
Branded Responses	✅	Company name, support email, docs URL
Remove Branding	✅	Hide “Powered by Spamidate”
Unlimited Keys	✅	No limit on API keys
Sub-Users	✅	Create customers, track usage
Commission Tracking	✅	Automated revenue sharing (20%)
White-Label Docs	✅	Branded documentation portal
Dedicated Manager	✅	Personal account manager
99.99% SLA	✅	Credits for downtime
Priority Support	✅	1-hour response time

Perfect For

• Marketing Agencies: Resell to clients under your brand
• SaaS Platforms: Embed validation as native feature
• Email Service Providers: Offer validation to customers
• Dev Tools: Package validation in your product

Pricing Model

Enterprise Plus: $2,499/month

• 4.5M validations/month (150K/day, 5,000/min)
• Cost at capacity: $0.00055 per email
• vs. Competitors: 86-94% cheaper at high volume
• No setup fees: Custom domain and white-label included

Contact Sales: support@spamidate.com

Next Steps

• Quick Start Guide - Make your first API call
• API Reference - Complete endpoint documentation
• Integration Examples - Code samples
• Dashboard Guide - Key management UI

Need Help?

• Email: support@spamidate.com
• Discord: Join our community
• Documentation: Browse troubleshooting
• Status: status.spamidate.com