> ## 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.

# Authenticate with the SOC Defenders API

> Generate SOC Defenders API keys in Settings, pass them via Authorization: Bearer or X-API-Key headers, and handle 401 authentication error responses.

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](https://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](https://socdefenders.ai/export#keys).

| Tier | API keys allowed |
| ---- | ---------------- |
| Free | Up to 3          |
| Pro  | Up 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**

```bash theme={null}
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://socdefenders.ai/api/v1/iocs?type=ipv4&limit=100"
```

**Option 2: `X-API-Key` header**

```bash theme={null}
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

<Warning>
  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.
</Warning>

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](mailto: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:

```json theme={null}
{
  "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 code        | Cause                                                                   | Fix                                                                                    |
| ----------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `missing_api_key` | No API key was included in the request.                                 | Add the `Authorization: Bearer sk_live_...` or `X-API-Key` header.                     |
| `invalid_api_key` | The 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_key` | The key existed but has been deleted or has expired.                    | Create a new key in **Settings → API Keys** and update your integration.               |