API Access & Authentication

Integrate ElasticDomain with your apps using our REST API. Available on Pro+ plans.

API Overview

Base URL: https://api.elasticdomain.com/v1
Format: JSON (request and response)
Authentication: API key via Bearer token
Rate Limits: 1,000 requests/hour (Pro), 10,000/hour (Business+)

Generating an API Key

Go to Dashboard → Settings → API Keys
Click "Generate New Key"
Name your key (e.g., "Production App", "CI/CD Pipeline")
Select scopes:
- read:domains — View domain data
- write:domains — Add/update/delete domains
- read:scans — View scan results
- write:scans — Trigger new scans
- read:alerts — View alerts
- write:alerts — Create/update alert rules
Click "Generate"
⚠️ IMPORTANT: Copy key immediately (shown only once)

API Key Example

ed_live_1a2b3c4d5e6f7g8h9i0j

Authentication

Include API key in Authorization header:

curl -H "Authorization: Bearer ed_live_1a2b3c4d5e6f7g8h9i0j" \
     https://api.elasticdomain.com/v1/domains

Core API Endpoints

List Domains

GET /domains

Query params:

type: Filter by owned, competitor, client, watchlist
folder: Filter by folder name
limit: Results per page (default 50, max 100)
offset: Pagination offset

Example request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.elasticdomain.com/v1/domains?type=owned&limit=10"

Response:

{
  "data": [
    {
      "id": "dom_abc123",
      "domain": "example.com",
      "type": "owned",
      "healthScore": 92,
      "riskScore": 15,
      "sslExpiry": "2025-06-15",
      "domainExpiry": "2026-01-20",
      "lastChecked": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

Get Domain Details

GET /domains/:id

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.elasticdomain.com/v1/domains/dom_abc123

Add Domain

POST /domains

Body:

{
  "domain": "example.com",
  "type": "owned",
  "folder": "Production",
  "tags": ["WordPress", "Cloudflare"],
  "checkInterval": 24
}

Trigger Scan

POST /domains/:id/scan

Body:

{
  "scanType": "full"
}

Scan types: quick, standard, full

Get Scan Results

GET /domains/:id/scans/:scanId

Response:

{
  "id": "scan_xyz789",
  "domainId": "dom_abc123",
  "status": "completed",
  "scanType": "full",
  "results": {
    "whois": { "registrar": "Namecheap", "expiryDate": "2026-01-20" },
    "ssl": { "issuer": "Let's Encrypt", "expiryDate": "2025-06-15", "grade": "A+" },
    "dns": { "aRecords": ["1.2.3.4"], "mxRecords": ["mail.example.com"] },
    "security": { "hsts": true, "blacklisted": false }
  },
  "creditsCost": 5,
  "completedAt": "2024-01-15T10:31:42Z"
}

Create Alert Rule

POST /domains/:id/alerts

{
  "alertType": "ssl_expiry",
  "threshold": 30,
  "notifyVia": "email",
  "enabled": true
}

Rate Limits

Plan	Requests/Hour	Burst
Pro	1,000	50
Business	10,000	500
Enterprise	100,000	5,000

Rate Limit Headers

Every response includes:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1705324800

Exceeded Rate Limit

HTTP 429: Too Many Requests

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 1,000 requests/hour exceeded",
  "retryAfter": 3600
}

Error Handling

Status Code	Meaning
200	Success
201	Created (new resource)
400	Bad Request (invalid input)
401	Unauthorized (invalid/missing API key)
403	Forbidden (insufficient scopes)
404	Not Found
429	Rate Limit Exceeded
500	Server Error (contact support)

Error Response Format

{
  "error": "invalid_domain",
  "message": "Domain 'example' is not a valid domain name",
  "details": {
    "field": "domain",
    "reason": "missing_tld"
  }
}

Code Examples

JavaScript (Node.js)

const API_KEY = 'ed_live_1a2b3c4d5e6f7g8h9i0j';
const BASE_URL = 'https://api.elasticdomain.com/v1';

async function getDomains() {
  const res = await fetch(`${BASE_URL}/domains`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  const data = await res.json();
  console.log(data);
}

getDomains();

Python

import requests

API_KEY = 'ed_live_1a2b3c4d5e6f7g8h9i0j'
BASE_URL = 'https://api.elasticdomain.com/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# List domains
response = requests.get(f'{BASE_URL}/domains', headers=headers)
domains = response.json()

print(domains)

PHP

<?php
$apiKey = 'ed_live_1a2b3c4d5e6f7g8h9i0j';
$baseUrl = 'https://api.elasticdomain.com/v1';

$ch = curl_init("$baseUrl/domains");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$domains = json_decode($response, true);

print_r($domains);
curl_close($ch);
?>

Webhooks

Receive real-time notifications when events occur:

Go to Settings → API Keys → Webhooks
Add webhook URL (e.g., https://your-app.com/webhooks/elasticdomain)
Select events:
- domain.scan_completed
- alert.triggered
- ssl.expiring_soon
- whois.changed
Save webhook

Webhook Payload Example

{
  "event": "alert.triggered",
  "timestamp": "2024-01-15T10:45:00Z",
  "data": {
    "alertId": "alert_xyz123",
    "domainId": "dom_abc123",
    "domain": "example.com",
    "alertType": "ssl_expiry",
    "message": "SSL certificate expires in 29 days",
    "severity": "warning"
  }
}

Security Best Practices

✅ Store API keys in environment variables (not in code)
✅ Use separate keys for dev/staging/prod
✅ Rotate keys quarterly
✅ Use minimal scopes (don't request write:* if you only read)
✅ Verify webhook signatures (SHA256 HMAC)
❌ Never commit API keys to Git
❌ Don't share keys between team members (generate per-user keys)
❌ Don't use API keys in client-side JavaScript (visible to users)

Managing API Keys

Revoking Keys

Settings → API Keys
Find key to revoke
Click "Revoke"
Key stops working immediately

Viewing Usage

See which keys are being used:

Last used timestamp
Total requests this month
Requests per endpoint

Common Integration Scenarios

CI/CD Pipeline

Trigger scan after deployment:

# .github/workflows/deploy.yml
- name: Scan domain after deploy
  run: |
    curl -X POST \
      -H "Authorization: Bearer ${{ secrets.ELASTICDOMAIN_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"scanType": "full"}' \
      https://api.elasticdomain.com/v1/domains/dom_abc123/scan

Monitoring Dashboard

Build custom dashboard pulling data from API:

Fetch domains with healthScore < 70
Display SSL expiry countdowns
Show recent alerts

Automated Alerting

Use webhooks to trigger Slack/PagerDuty/OpsGenie notifications.

Generate Your First API Key

API Keys Settings →