# LiteSOC — API Reference

> Complete API documentation for the LiteSOC Security Observability platform.

- **Base URL (Ingestion):** https://api.litesoc.io/collect
- **Base URL (Management):** https://api.litesoc.io
- **Authentication:** `X-API-Key: YOUR_API_KEY` header required on all requests
- **Website:** https://litesoc.io/docs/api

## Getting Started

### Authentication

All requests must include your API key in the `X-API-Key` header:

```bash
curl -X POST https://api.litesoc.io/collect \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "auth.login_success", "actor": {"id": "user_123"}}'
```

Find your API key in the LiteSOC Dashboard under Settings → API Keys.

### Quick Start (TypeScript)

```typescript
interface Actor {
  id: string;
  email?: string;
}

const LSOC_ENDPOINT = 'https://api.litesoc.io/collect';

export async function trackEvent(event: string, actor: Actor, userIP: string, metadata?: Record<string, unknown>) {
  const response = await fetch(LSOC_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.LSOC_API_KEY!,
    },
    body: JSON.stringify({ event, actor, user_ip: userIP, metadata }),
  });

  if (!response.ok) {
    throw new Error(`LiteSOC error: ${response.status}`);
  }
  return response.json();
}
```

## Event Collection API

### POST /collect — Ingest a Security Event

**Request body:**

```json
{
  "event": "auth.login_success",
  "actor": {
    "id": "user_123",
    "email": "user@example.com"
  },
  "user_ip": "203.0.113.50",
  "metadata": {
    "method": "oauth",
    "provider": "google"
  }
}
```

**Responses:**
- `202 Accepted` — Event queued successfully
- `401 Unauthorized` — Invalid or missing API key
- `403 Forbidden` — Quota exceeded or plan restriction
- `429 Too Many Requests` — Rate limited

### POST /collect — Batch Ingestion

Send up to 100 events in a single request:

```json
{
  "events": [
    { "event": "auth.login_success", "actor": { "id": "user_1" }, "user_ip": "203.0.113.1" },
    { "event": "auth.login_failed", "actor": { "id": "user_2" }, "user_ip": "203.0.113.2" }
  ]
}
```

## Management API

> All management endpoints require a **Pro** plan or above unless noted.

| Method | Endpoint | Plan | Description |
|---|---|---|---|
| GET | /events | Free | List security events with pagination and filtering |
| GET | /events/:id | Free | Get a single event with full forensic details |
| GET | /alerts | Pro+ | List behavioral AI detection alerts |
| GET | /alerts/:id | Pro+ | Get a single alert with full context |
| PATCH | /alerts/:id | Pro+ | Update alert status (resolve, mark as safe) |
| GET | /health | Free | API health and quota usage |

### GET /events

Query parameters:
- `limit` — Max results (default: 50, max: 200)
- `offset` — Pagination offset
- `event_type` — Filter by event name (e.g., `auth.login_failed`)
- `actor_id` — Filter by actor user ID
- `from` — ISO 8601 start date
- `to` — ISO 8601 end date

### PATCH /alerts/:id

```json
{ "status": "resolved" }
```

Valid status values: `open`, `resolved`, `safe`

## 26 Standard Security Events

All events are server-assigned a severity level. Client-supplied severity fields are ignored.

#### Authentication

| Event Name | Severity | Instant Alert |
|---|---|---|
| `auth.login_success` | low | — |
| `auth.login_failed` | medium | — |
| `auth.logout` | info | — |
| `auth.password_reset` | medium | — |
| `auth.mfa_enabled` | low | — |
| `auth.mfa_disabled` | medium | — |
| `auth.session_expired` | info | — |
| `auth.token_refreshed` | info | — |

#### Authorization

| Event Name | Severity | Instant Alert |
|---|---|---|
| `authz.access_denied` | critical | ⚡ Yes |
| `authz.role_changed` | critical | ⚡ Yes |
| `authz.permission_granted` | info | — |
| `authz.permission_revoked` | warning | — |

#### Admin Actions

| Event Name | Severity | Instant Alert |
|---|---|---|
| `admin.user_created` | low | — |
| `admin.user_deleted` | high | — |
| `admin.user_suspended` | high | — |
| `admin.privilege_escalation` | critical | ⚡ Yes |
| `admin.settings_changed` | medium | — |
| `admin.api_key_created` | medium | — |
| `admin.api_key_revoked` | medium | — |

#### Data Access

| Event Name | Severity | Instant Alert |
|---|---|---|
| `data.export` | medium | — |
| `data.bulk_delete` | critical | ⚡ Yes |
| `data.sensitive_access` | critical | ⚡ Yes |

#### Security

| Event Name | Severity | Instant Alert |
|---|---|---|
| `security.suspicious_activity` | critical | ⚡ Yes |
| `security.rate_limit_exceeded` | medium | — |
| `security.ip_blocked` | high | — |
| `security.brute_force_detected` | critical | ⚡ Yes |

## Infrastructure & Quotas

| Plan | Events/Month | Rate Limit | Retention |
|---|---|---|---|
| Free | 10,000 | 100 req/min | 7 days |
| Pro | 500,000 | 1,000 req/min | 30 days |
| Enterprise | Unlimited | Custom | 90 days |
| Custom | Custom | Custom | Custom |

## Security Intelligence (Automatic Enrichment)

Every ingested event is automatically enriched with:

- **GeoIP** — Country, city, region, coordinates, timezone
- **Network Intelligence** — VPN/Tor/proxy detection, datacenter flag, ASN, ISP
- **Threat Scoring** — Risk score (0–100) based on network signals
- **Behavioral AI** — Impossible Travel, Geo-Anomaly detection (Pro+)

> Network Intelligence and GeoIP data are **redacted** for Free plan API responses.

## Response Headers

Every API response includes plan metadata:

| Header | Description |
|---|---|
| `X-LiteSOC-Plan` | Your current plan (free, pro, enterprise) |
| `X-LiteSOC-Retention` | Retention period in days |
| `X-LiteSOC-Cutoff` | ISO 8601 date of oldest available data |