Skip to main content

​
API Keys

API keys allow external systems to access CHAD’s REST API. They’re scoped to specific users and inherit role permissions.

​
Use Cases

  • SIEM integration - Pull alerts into your SIEM
  • Automation - Scripts that manage rules
  • Dashboards - External dashboards querying stats
  • CI/CD - Automated rule deployment

​
Creating API Keys

​
Via UI

  1. Go to Account > API Keys
  2. Click Create API Key
  3. Enter a name (e.g., “SIEM Integration”)
  4. Click Create
  5. Copy the key immediately - it won’t be shown again

​
Key Format

chad_ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Keys are 32+ character random strings with a chad_ak_ prefix.

​
Using API Keys

Include the key in the Authorization header: 
curl -H "Authorization: Bearer chad_ak_xxxxx..." \
  https://chad.example.com/api/alerts
Or via query parameter (less secure): 
curl "https://chad.example.com/api/alerts?api_key=chad_ak_xxxxx..."
Prefer headers over query parameters. Query strings may be logged by proxies.

​
Permissions

API keys inherit the creating user’s role:
User RoleAPI Key Can
AdminRead and write all resources
AnalystRead and write rules, alerts
ViewerRead-only access

​
Read-Only Mode

Force read-only regardless of role:
  1. When creating the key, enable Read-Only
  2. Key cannot make changes even if user is Admin

​
Key Management

​
List Keys

View all your API keys:
  1. Go to Account > API Keys
  2. See all keys with:
    • Name
    • Created date
    • Last used date
    • Status

​
Revoke Key

Immediately disable a key:
  1. Go to Account > API Keys
  2. Find the key
  3. Click Revoke
  4. Key stops working immediately
Revoking is immediate and permanent. Create a new key if needed.

​
Regenerate Key

Can’t regenerate - revoke and create new:
  1. Revoke the old key
  2. Create a new key
  3. Update your integrations

​
API Endpoints

See API Reference for full documentation.

​
Common Endpoints

# List alerts
GET /api/external/alerts

# Get single alert
GET /api/external/alerts/{id}

# List rules
GET /api/external/rules

# Get rule
GET /api/external/rules/{id}

# Dashboard stats
GET /api/external/stats

​
Rate Limits

API keys are rate-limited:
TierRequests/minute
Standard60
High300
Configure in Settings > API.

​
Security Considerations

​
Key Storage

  • Store keys securely (secrets manager, vault)
  • Never commit keys to source control
  • Use environment variables in applications

​
Key Rotation

Rotate keys periodically:
  1. Create new key
  2. Update applications
  3. Revoke old key

​
Monitoring

Monitor API key usage:
  1. Check Last Used date regularly
  2. Revoke unused keys
  3. Watch for unusual patterns in audit log

​
IP Allowlisting

Restrict API key usage by IP:
  1. Go to Settings > API
  2. Add IP allowlist per key
  3. Requests from other IPs rejected

​
Example Integrations

​
Python

import requests

API_KEY = "chad_ak_xxxxx..."
BASE_URL = "https://chad.example.com"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Get alerts
response = requests.get(
    f"{BASE_URL}/api/external/alerts",
    headers=headers,
    params={"status": "new", "limit": 100}
)

alerts = response.json()

​
JavaScript

const API_KEY = 'chad_ak_xxxxx...';
const BASE_URL = 'https://chad.example.com';

async function getAlerts() {
  const response = await fetch(
    `${BASE_URL}/api/external/alerts?status=new`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  return response.json();
}

​
cURL

# Get new alerts
curl -H "Authorization: Bearer chad_ak_xxxxx..." \
  "https://chad.example.com/api/external/alerts?status=new"

# Get specific rule
curl -H "Authorization: Bearer chad_ak_xxxxx..." \
  "https://chad.example.com/api/external/rules/abc-123"

​
Troubleshooting

​
401 Unauthorized

  1. Check key is correct (no typos, whitespace)
  2. Verify key hasn’t been revoked
  3. Check Authorization header format

​
403 Forbidden

  1. User role doesn’t permit this action
  2. API key is read-only
  3. Resource requires higher permissions

​
429 Too Many Requests

  1. You’ve hit rate limit
  2. Wait and retry
  3. Consider rate limit increase

​
Key not working

  1. Verify key hasn’t been revoked
  2. Check user account is enabled
  3. Test with a new key

​
Best Practices

Separate keys allow independent rotation and revocation.
“SIEM Integration - Splunk Prod” is better than “API Key 1”.
Use read-only keys when writes aren’t needed.
Rotate keys quarterly or after personnel changes.
Unusual API activity may indicate compromise.

​
Next Steps

API Reference

Full API documentation

User Management

Manage user accounts