Skip to content

API Keys

Generating a Key

  1. Navigate to Integrations in the left sidebar
  2. Select API Keys
  3. Click Generate New Key
  4. Enter a name (e.g. "Production SIEM Integration")
  5. Select scopes: read | write | alerts
  6. Set expiry if required
  7. Copy the key - it is shown only once

Keys use the format: bs_live_ followed by 64 hex characters.

Using a Key

# curl
curl -H "Authorization: Bearer bs_live_your_key_here" \
  https://breachspider.com/api/v1/cves

# Python
import requests
headers = {"Authorization": "Bearer bs_live_your_key_here"}
response = requests.get("https://breachspider.com/api/v1/cves", headers=headers)

// JavaScript
const response = await fetch("https://breachspider.com/api/v1/cves", {
  headers: { "Authorization": "Bearer bs_live_your_key_here" }
});

Listing Keys

GET /api/v1/integrations/keys

Returns key name, prefix (first 16 characters), scopes, created date, last used date. The raw key is never returned after generation.

Revoking a Key

DELETE /api/v1/integrations/keys/{key_id}

Revocation is immediate. Any request using a revoked key returns 401 AUTH_REQUIRED.

Key Security Best Practices

  • Store keys in environment variables, never in source code
  • Use separate keys per integration (SIEM, webhook consumer, custom app)
  • Set expiry dates on keys used by third-party services
  • Rotate keys quarterly or immediately after any suspected exposure
  • Monitor last_used_at in the key list to detect unused or unexpected usage