API Key Management
Generate, rotate, and manage API keys for programmatic access to your domain monitoring data. API keys enable secure integration with external tools, automation scripts, and third-party services.
📋 Table of Contents
🔑 What are API Keys?
API keys are secure authentication tokens that allow you to access your ElasticDomain data programmatically. They act as credentials for making API requests without requiring interactive login.
💡 Use Case: Perfect for CI/CD pipelines, monitoring dashboards, Slack bots, automation scripts, and integrating domain data into your own applications.
🚀 Creating Your First API Key
Step 1: Navigate to API Keys
Go to Domain Tracker → Click the Portfolio dropdown → Select API Keys
Step 2: Click "Create New API Key"
In the API Keys page, click the blue "Create New API Key" button at the top.
Step 3: Configure Key Details
- Name: Give your key a descriptive name (e.g., "Production CI/CD Pipeline")
- Scope: Select permissions (read_domains, write_domains, read_reports, etc.)
- Expiration: Choose when the key should expire (30, 90, 365 days, or custom)
- IP Restrictions (Optional): Limit key usage to specific IP addresses
Step 4: Copy Your Key
After creation, your key will be displayed once. Copy it immediately and store it securely.
⚠️ Warning: You will not be able to see this key again. If you lose it, you must regenerate a new one.
🔐 Permission Scopes
API keys use a granular permission system. Always grant the minimum permissions needed (principle of least privilege).
| Scope | Description | Use Case |
|---|---|---|
| read_domains | Read domain data, WHOIS, DNS, SSL info | Monitoring dashboards |
| write_domains | Add, update, delete domains | Bulk import scripts |
| read_reports | Access scheduled reports and exports | Report aggregation |
| write_reports | Create/modify scheduled reports | Automation tools |
| read_alerts | View alert rules and history | Alert dashboards |
| write_alerts | Create/modify alert rules | Dynamic alerting |
| admin | Full access to all resources | Administrative tools |
💻 Using API Keys
Include your API key in the Authorization header of your HTTP requests:
Authorization: Bearer elastic_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
🔄 Rotating API Keys
Regular key rotation is a critical security practice. We recommend rotating keys every 90 days.
Generate a new API key with the same permissions
Replace the old key in all services and scripts
Verify the old key is no longer being used (check last used timestamp)
Revoke the old key once migration is complete
✅ Security Best Practices
✓ DO
- Store keys in environment variables or secret management systems
- Use IP restrictions when possible
- Set expiration dates on all keys
- Grant minimum required permissions
- Rotate keys regularly (every 90 days recommended)
- Delete unused keys immediately
- Monitor key usage via the dashboard
✗ DON'T
- Commit API keys to version control (Git, SVN, etc.)
- Share keys via email, Slack, or messaging apps
- Hardcode keys in application source code
- Use the same key across multiple applications
- Grant
adminscope unless absolutely necessary - Create keys without expiration dates
📝 Code Examples
Example 1: List All Domains (cURL)
curl -X GET https://elasticdomain.com/api/tools/domain-tracker \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Example 2: Add Domain (JavaScript/Node.js)
const response = await fetch('https://elasticdomain.com/api/tools/domain-tracker', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ELASTIC_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
domain: 'example.com',
domainType: 'owned',
tags: ['production', 'critical'],
folder: 'Main Sites',
}),
});
const data = await response.json();
console.log('Domain added:', data);Example 3: Fetch Domain Data (Python)
import os
import requests
API_KEY = os.environ['ELASTIC_API_KEY']
BASE_URL = 'https://elasticdomain.com/api/tools/domain-tracker'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
}
response = requests.get(BASE_URL, headers=headers)
domains = response.json()
for domain in domains:
print(f"{domain['domain']} - Health: {domain['healthScore']}/100")Example 4: Trigger Full Scan (TypeScript)
import axios from 'axios';
interface ScanResult {
domainId: string;
whois: any;
dns: any;
ssl: any;
security: any;
}
async function triggerFullScan(domainId: string): Promise<ScanResult> {
const response = await axios.post<ScanResult>(
`https://elasticdomain.com/api/tools/domain-tracker/${domainId}/scan`,
{ action: 'full_scan' },
{
headers: {
'Authorization': `Bearer ${process.env.ELASTIC_API_KEY}`,
'Content-Type': 'application/json',
},
}
);
return response.data;
}
// Usage
const result = await triggerFullScan('domain-123');
console.log('Scan complete:', result);🔧 Troubleshooting
Error: "Invalid API key"
- Verify the key is correctly copied (52 characters starting with
elastic_sk_) - Check if the key has been deleted or revoked
- Ensure you're using the
Authorization: Bearerheader format - Verify the key hasn't expired
Error: "Insufficient permissions"
- Check the key's scope in the API Keys dashboard
- Regenerate the key with additional required permissions
- Ensure you're not trying to write with a read-only key
Error: "IP address not allowed"
- Check IP restrictions in the API Keys settings
- Verify your server's public IP address matches the allowed list
- Consider removing IP restrictions for development keys
Error: "Rate limit exceeded"
- Default rate limit: 1000 requests per hour per key
- Implement exponential backoff in your code
- Check the
X-RateLimit-Remainingresponse header - Contact support for higher limits if needed