API Key Setup¶

API keys are your gateway to ReputeAPI. This guide covers everything you need to know about creating, managing, and securing your API keys for optimal performance and security.

🔑 Getting Your API Key¶

1. Create Your Account¶

# Sign up for a free account (no credit card required)
curl -X POST "https://api.reputeapi.com/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "secure_password_123",
    "company": "Your Company Name"
  }'

2. Verify Your Email¶

Check your email for a verification link and click it to activate your account.

3. Generate Your First API Key¶

# Get your authentication token
curl -X POST "https://api.reputeapi.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com", 
    "password": "secure_password_123"
  }'

# Create an API key
curl -X POST "https://api.reputeapi.com/auth/keys" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First API Key",
    "permissions": ["read"],
    "environment": "production"
  }'

Response:

{
  "key_id": "key_abc123xyz789",
  "api_key": "ra_live_1234567890abcdef...",
  "name": "My First API Key", 
  "permissions": ["read"],
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": null,
  "rate_limit": {
    "requests_per_hour": 1000,
    "burst_allowance": 10
  }
}

🔒 API Key Types & Permissions¶

Key Types¶

Type	Prefix	Use Case
Live	`ra_live_`	Production applications
Test	`ra_test_`	Development and testing
Restricted	`ra_rest_`	Limited scope applications

Permission Levels¶

{
  "permissions": [
    "read",        // Basic domain validation
    "write",       // Create webhooks, modify settings
    "admin",       // Manage API keys, billing
    "analytics"    // Access usage statistics
  ]
}

Environment-Specific Keys¶

# Development key (higher rate limits, test data)
curl -X POST "https://api.reputeapi.com/auth/keys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Development Key",
    "environment": "development",
    "permissions": ["read", "write"]
  }'

# Production key (production rate limits, real data)
curl -X POST "https://api.reputeapi.com/auth/keys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Production App",
    "environment": "production", 
    "permissions": ["read"],
    "ip_whitelist": ["203.0.113.1", "203.0.113.2"]
  }'

📊 Rate Limits by Tier¶

Free Tier¶

1,000 requests/month
60 requests/hour
10 requests/minute burst
1 concurrent request

Pro Tier ($49/month)¶

100,000 requests/month
10,000 requests/hour
100 requests/minute burst
10 concurrent requests

Enterprise Tier (Custom)¶

Unlimited requests/month
Custom rate limits
Custom burst allowance
Unlimited concurrent requests

Rate Limit Headers¶

Every API response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642694400
X-RateLimit-Burst: 10
X-RateLimit-Burst-Remaining: 9

🛡️ Security Best Practices¶

1. Environment Variables¶

✅ Do:

# .env file
REPUTEAPI_KEY=ra_live_1234567890abcdef...
REPUTEAPI_ENDPOINT=https://api.reputeapi.com

# Load in your application
export $(cat .env | xargs)

❌ Don't:

// Never hardcode API keys!
const apiKey = "ra_live_1234567890abcdef..."; // BAD!

2. Key Rotation¶

# Rotate keys regularly (recommended: every 90 days)
curl -X PUT "https://api.reputeapi.com/auth/keys/key_abc123/rotate" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. Principle of Least Privilege¶

# Create keys with minimal required permissions
curl -X POST "https://api.reputeapi.com/auth/keys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Domain Validator",
    "permissions": ["read"],           # Only read permission
    "scope": ["check", "score"],       # Only specific endpoints
    "ip_whitelist": ["203.0.113.1"]   # Restrict to specific IPs
  }'

4. Monitoring & Alerts¶

# Set up usage monitoring
curl -X POST "https://api.reputeapi.com/auth/keys/key_abc123/alerts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "threshold_percentage": 80,        # Alert at 80% of quota
    "webhook_url": "https://yourapp.com/alerts",
    "email_notifications": true
  }'

⚙️ Authentication Methods¶

1. Bearer Token (Recommended)¶

curl -X POST "https://api.reputeapi.com/v1/check" \
  -H "Authorization: Bearer ra_live_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

2. API Key Header¶

curl -X POST "https://api.reputeapi.com/v1/check" \
  -H "X-API-Key: ra_live_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

3. Request Signing (Enterprise)¶

import hmac
import hashlib
import time
import requests

def sign_request(api_key, secret_key, method, url, body):
    """Sign request with HMAC-SHA256"""
    timestamp = str(int(time.time()))

    # Create signature payload
    payload = f"{method}\n{url}\n{body}\n{timestamp}"

    # Generate signature
    signature = hmac.new(
        secret_key.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return {
        'Authorization': f'Bearer {api_key}',
        'X-Timestamp': timestamp,
        'X-Signature': signature
    }

# Example usage
headers = sign_request(
    api_key='ra_live_1234567890abcdef...',
    secret_key='your_secret_key',
    method='POST',
    url='/v1/check',
    body='{"domain": "example.com"}'
)

response = requests.post(
    'https://api.reputeapi.com/v1/check',
    headers=headers,
    json={'domain': 'example.com'}
)

🚀 SDK Setup Examples¶

Python¶

# Install the SDK
pip install reputeapi

# Configure authentication
import os
from reputeapi import Client

# Option 1: Environment variable
os.environ['REPUTEAPI_KEY'] = 'ra_live_1234567890abcdef...'
client = Client()

# Option 2: Direct instantiation
client = Client(api_key='ra_live_1234567890abcdef...')

# Option 3: Configuration file
client = Client.from_config('/path/to/config.json')

Node.js¶

// Install the SDK
npm install @reputeapi/node

// Configure authentication
const ReputeAPI = require('@reputeapi/node');

// Option 1: Environment variable
process.env.REPUTEAPI_KEY = 'ra_live_1234567890abcdef...';
const client = new ReputeAPI();

// Option 2: Direct instantiation
const client = new ReputeAPI('ra_live_1234567890abcdef...');

// Option 3: Configuration object
const client = new ReputeAPI({
  apiKey: 'ra_live_1234567890abcdef...',
  endpoint: 'https://api.reputeapi.com',
  timeout: 30000
});

JavaScript (Browser)¶

// Install via CDN
<script src="https://cdn.jsdelivr.net/npm/@reputeapi/js@latest/dist/reputeapi.min.js"></script>

// Configure client
const client = new ReputeAPI({
  apiKey: 'ra_test_1234567890abcdef...', // Use test keys in browser!
  environment: 'test'
});

// Note: Never use live API keys in browser JavaScript!

🔧 API Key Management¶

List All Keys¶

curl -X GET "https://api.reputeapi.com/auth/keys" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Update Key Permissions¶

curl -X PUT "https://api.reputeapi.com/auth/keys/key_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Updated Key Name",
    "permissions": ["read", "analytics"],
    "ip_whitelist": ["203.0.113.1", "203.0.113.2"]
  }'

Set Expiration Date¶

curl -X PUT "https://api.reputeapi.com/auth/keys/key_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Revoke API Key¶

curl -X DELETE "https://api.reputeapi.com/auth/keys/key_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

📈 Usage Monitoring¶

Real-Time Usage¶

# Get current usage statistics
curl -X GET "https://api.reputeapi.com/auth/keys/key_abc123/usage" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "current_period": {
    "requests_made": 2547,
    "requests_limit": 100000,
    "percentage_used": 2.5,
    "reset_date": "2025-02-01T00:00:00Z"
  },
  "rate_limits": {
    "hourly": {
      "requests_made": 45,
      "requests_limit": 10000,
      "reset_time": "2025-01-15T11:00:00Z"
    }
  },
  "last_24_hours": {
    "total_requests": 156,
    "unique_domains": 78,
    "average_response_time": "89ms",
    "error_rate": 0.02
  }
}

Usage Alerts¶

# Configure usage alerts
curl -X POST "https://api.reputeapi.com/auth/keys/key_abc123/alerts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "monthly_threshold": 80,     # Alert at 80% of monthly quota
    "hourly_threshold": 90,      # Alert at 90% of hourly limit
    "webhook_url": "https://yourapp.com/webhook/reputeapi-alert",
    "email_enabled": true,
    "slack_webhook": "https://hooks.slack.com/services/..."
  }'

🚨 Troubleshooting¶

Common Issues¶

1. Invalid API Key¶

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or expired",
  "code": 401
}

Solutions: - Verify the API key is copied correctly - Check if the key has been revoked or expired - Ensure you're using the correct environment (test vs live)

2. Rate Limit Exceeded¶

{
  "error": "rate_limit_exceeded", 
  "message": "Rate limit exceeded. Try again in 3600 seconds",
  "code": 429,
  "retry_after": 3600
}

Solutions: - Implement exponential backoff retry logic - Upgrade to a higher tier for increased limits - Distribute requests across multiple API keys

3. Insufficient Permissions¶

{
  "error": "insufficient_permissions",
  "message": "API key does not have permission for this endpoint",
  "code": 403
}

Solutions: - Update API key permissions to include required scopes - Use a different API key with appropriate permissions - Contact support for permission clarification

Error Handling Best Practices¶

import requests
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def safe_api_call(domain, api_key):
    """Make API call with proper error handling"""

    headers = {'Authorization': f'Bearer {api_key}'}

    try:
        response = requests.post(
            'https://api.reputeapi.com/v1/check',
            headers=headers,
            json={'domain': domain},
            timeout=30
        )

        # Handle rate limiting
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            raise Exception("Rate limited")

        # Handle authentication errors
        if response.status_code == 401:
            raise Exception("Invalid API key")

        # Handle permission errors
        if response.status_code == 403:
            raise Exception("Insufficient permissions")

        response.raise_for_status()
        return response.json()

    except requests.exceptions.RequestException as e:
        print(f"API request failed: {e}")
        raise

📞 Support & Next Steps¶

Getting Help¶

📖 API Reference - Complete endpoint documentation
💬 Discord Community - Developer community
📧 Email Support - Direct support
🐛 GitHub Issues - Bug reports

Next Steps¶

Make Your First API Call - Test your setup
Explore Use Cases - Find your implementation pattern
Integration Patterns - Best practices
Code Examples - Working code samples

Your API key is ready! Start validating domains with our Quick Start Guide.