Authentication

Learn how to authenticate with the SanctionSnap API using API keys

API Keys

API keys are used to authenticate requests to the SanctionSnap API

All API requests must include a valid API key in the request headers. API keys are tied to your account and determine your access level and rate limits.

Header Format

X-API-Key: your_api_key_here

Security Note: Keep your API keys secret. Never expose them in client-side code, public repositories, or logs.

Getting Your API Key

1. Sign Up

Create a free account to get started with 250 requests per month.

Create Account

2. Generate API Key

Once logged in, you can generate and manage API keys from your dashboard.

• View your current usage and limits
• Create multiple API keys for different applications
• Revoke keys when needed
• Monitor key usage

API Key Types & Tiers

Different API keys provide different levels of access

Free Tier

$0/month

Requests per month:250

Rate limit:60/minute

Support:None

Starter

$29/month

Requests per month:5,000

Rate limit:60/minute

Support:Email

Pro

$99/month

Requests per month:50,000

Rate limit:60/minute

Support:Priority email

Scale

$299/month

Requests per month:500,000

Rate limit:60/minute

Support:Dedicated support

Rate Limiting

Understanding rate limits and how to handle them

Rate Limit Types

Per-minute limit

60 requests/minute

Monthly quota

Based on plan

Rate Limit Headers

Every API response includes headers with rate limit information:

X-RateLimit-Limit: 60        # Total requests allowed per window
X-RateLimit-Remaining: 59    # Requests remaining in current window  
X-RateLimit-Reset: 1640995200 # Unix timestamp when window resets

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 status code:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Try again later.",
  "retry_after": 60
}

Best Practice: Implement exponential backoff and respect theretry_after header when rate limited.

Authentication Error Codes

Common authentication-related errors and how to fix them

401

Unauthorized

Your API key is missing, invalid, or has been revoked.

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}

Solution: Check that you're including the correct API key in the X-API-Key header.

429

Rate Limited

You've exceeded your rate limit or monthly quota.

{
  "error": "Rate limit exceeded",
  "message": "Monthly quota exceeded. Upgrade your plan or wait for reset.",
  "quota_reset": "2024-02-01T00:00:00Z"
}

Solution: Wait for the rate limit to reset or upgrade your plan.

Security Best Practices

Keep your API keys secure and your integration safe

✅ Do

• Store API keys in environment variables
• Use different keys for development and production
• Rotate keys regularly
• Monitor key usage for unusual activity
• Use HTTPS for all API requests
• Implement proper error handling
• Respect rate limits and implement backoff

❌ Don't

• Hardcode API keys in your source code
• Commit keys to version control
• Share keys in public forums or logs
• Use production keys for testing
• Make API calls from client-side JavaScript
• Ignore rate limit headers

Example: Environment Variables

# .env file
SANCTIONSNAP_API_KEY=sk_live_your_production_key_here

# In your application
const apiKey = process.env.SANCTIONSNAP_API_KEY;

Testing Your Authentication

Verify your API key is working correctly

2. Usage Check

Verify your quota and usage:

curl -H "X-API-Key: your_api_key_here" \
     https://sanctionsnap.com/api/usage

3. Expected Response

A successful authentication should return:

{
  "current_usage": 5,
  "limit": 250,
  "tier": "free",
  "remaining": 245
}