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

# API key authentication for the SOC Defenders API

> Authenticate every SOC Defenders API request with an API key. Pass it as a Bearer token or X-API-Key header. Keys are managed in Settings → API Keys.

Every request to the SOC Defenders API must include a valid API key. You pass the key in an HTTP request header — either as a Bearer token in the `Authorization` header or directly in the `X-API-Key` header. Both methods are equivalent; use whichever fits your tooling or integration.

## Getting an API key

To generate an API key, sign in to SOC Defenders and go to **Settings → API Keys**. Click **Create key**, give it a name, and copy the value — it is shown only once.

* **Free tier**: create up to 3 API keys
* **Pro tier**: create up to 50 API keys

All keys follow the format `sk_live_...`.

## Passing your key in a request

### Authorization header (Bearer token)

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

### 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=10"
```

Both headers are accepted on every endpoint. You do not need to use both at the same time.

## Authentication errors

If your key is missing, malformed, or invalid, the API returns a `401 Unauthorized` response with a JSON error body.

**Missing key**

```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_..."
  }
}
```

### Error code reference

| Code              | Description                                            | 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 | Check for typos or extra whitespace; verify the key in **Settings → API Keys** |
| `expired_api_key` | The key has been deactivated or expired                | Generate a new key in **Settings → API Keys** and update your integration      |

## Security best practices

<Warning>
  Never include your API key in a URL query parameter. Query strings appear in server logs, browser history, and referrer headers, which exposes your key to unintended parties. Always pass the key in a request header.
</Warning>

* Store keys in environment variables or a secrets manager, not in source code.
* Use one key per integration so you can rotate or revoke individual keys without disrupting others.
* If a key is compromised, delete it immediately in **Settings → API Keys** and replace it with a new one.
* On the Pro tier, take advantage of your 50-key limit to scope keys by team, environment, or service.