Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.socdefenders.ai/llms.txt

Use this file to discover all available pages before exploring further.

SOC Defenders uses API key authentication for all REST API requests. Every request you make must include a valid API key — requests without a key, or with an invalid or expired key, are rejected before reaching any endpoint. There are no session cookies or OAuth flows; the API key is the only credential you need.

​
Getting your API key

Sign in at socdefenders.ai, then navigate to Settings → API Keys. Click Create key, give it a name, and copy the key value immediately — it is only shown once. You can also reach the API Keys section from the export page.
TierAPI keys allowed
FreeUp to 3
ProUp to 50
If you need to revoke a key, return to Settings → API Keys and delete it. The key stops working immediately.

​
Passing your key

The SOC Defenders API accepts your key in two request headers. Use whichever fits your tooling or integration. Option 1: Authorization header with Bearer scheme 
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/iocs?type=ipv4&limit=100"
Option 2: X-API-Key header 
curl -H "X-API-Key: sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/iocs?type=ipv4&limit=100"
Both headers are equivalent. The Authorization: Bearer form is the standard HTTP convention and is the recommended default. Use X-API-Key if your infrastructure strips or rewrites the Authorization header.

​
API key security

Keep your API key secret. Do not commit it to source control, paste it into chat tools, or include it in client-side code or public repositories. If a key is exposed, rotate it immediately by deleting it in Settings → API Keys and creating a new one.
Treat your API key like a password. Recommended practices:
  • Store keys in environment variables or a secrets manager, not in code.
  • Use separate keys for different environments (development, staging, production).
  • Rotate keys periodically and immediately after any suspected exposure.
  • Grant keys only the access level your integration actually needs — use Free-tier keys for testing rather than production Pro keys.
If you believe a key has been compromised, contact security@socdefenders.ai in addition to rotating the key.

​
Authentication errors

When a request fails authentication, the API returns a 401 Unauthorized response with a JSON error body. For example, a request with a missing key returns: 
{
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Include it in the Authorization header as \"Bearer sk_live_...\" or in the X-API-Key header.",
    "request_id": "req_..."
  }
}
Use the code field to identify the problem programmatically. The request_id is useful when contacting support.
Error codeCauseFix
missing_api_keyNo API key was included in the request.Add the Authorization: Bearer sk_live_... or X-API-Key header.
invalid_api_keyThe key was provided but does not match any active key on your account.Check for typos or extra whitespace. Verify the key exists in Settings → API Keys.
expired_api_keyThe key existed but has been deleted or has expired.Create a new key in Settings → API Keys and update your integration.