LiteSOC API Reference

Authentication

All API requests require authentication using an API key. Include your API key in theX-API-Keyheader with every request.

Base URL

All API requests should be made to the following base URL:

Browser Security (CORS)

For security reasons, LiteSOC restricts browser-side API requests to authorized domains only. This prevents unauthorized websites from making API calls using your API key.

Install our SDKs

The fastest way to integrate LiteSOC. Our official SDKs provide a unified interface for both the Event Collection API and Management API, with automatic batching, retries, and type-safe methods.

npm install litesoc

import { LiteSOC } from 'litesoc';

const litesoc = new LiteSOC('YOUR_API_KEY');

// Track events with the generic track() method
await litesoc.track('auth.login_failed', {
  actor: 'user_123',         // or { id: 'user_123', email: '...' }
  actorEmail: 'user@example.com',
  userIp: request.ip,        // Required for Behavioral AI
  metadata: { reason: 'invalid_password' }
});

// Or use convenience methods
await litesoc.trackLoginSuccess('user_123', { userIp: request.ip });
await litesoc.trackPrivilegeEscalation('admin_user');
await litesoc.trackSensitiveAccess('user_123', 'customer_pii_table');

// Events are automatically batched - flush before exit
await litesoc.flush();

// Fetch recent security events
const { data: events, metadata } = await litesoc.getEvents({
  limit: 50,
  severity: 'critical',
  eventName: 'auth.login_failed'
});
console.log(`Plan: ${metadata.plan}, Retention: ${metadata.retentionDays} days`);

// Get a single event by ID
const { data: event } = await litesoc.getEvent('evt_abc123');

// List active alerts (Pro+ only)
const { data: alerts } = await litesoc.getAlerts({
  status: 'open',
  severity: 'critical'
});

// Get a single alert by ID (Pro+ only)
const { data: alert, metadata } = await litesoc.getAlert('alt_abc123');
console.log(`Alert: ${alert.title} (${alert.status})`);

// Resolve an alert (alertId, resolutionType, notes?)
// resolutionType: 'blocked_ip' | 'reset_password' | 'contacted_user' | 'false_positive' | 'other'
await litesoc.resolveAlert('alt_abc123', 'blocked_ip', 'IP blocked in firewall');

// Mark alert as safe (false positive)
await litesoc.markAlertSafe('alt_def456', 'Expected behavior from CI/CD pipeline');

Quick Start

Send your first security event in under a minute:

POST https://api.litesoc.io/collect

Use this API to send authentication events, admin actions, data access logs, and security incidents from your application. LiteSOC will automatically normalize, enrich, and analyze each event for potential threats.

Event Collection Endpoint

All API requests should be made to the following base URL:

Error Responses

Example Responses

{
  "status": "queued",
  "quota": {
    "remaining": 4999,
    "limit": 5000
  }
}

POST /collectIngestion

Send a single security event to LiteSOC. Events are processed asynchronously and appear in your dashboard within seconds.

# Replace YOUR_API_KEY with your actual key from the dashboard
# This sends a test login event

curl -X POST https://api.litesoc.io/collect \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "event": "auth.login_success",
    "actor": {
      "id": "test_user_123",
      "email": "test@example.com"
    },
    "user_ip": "203.0.113.50",
    "metadata": {
      "method": "password",
      "test": true
    }
  }'

Request Headers

Batch Ingestionv2.5+

Send up to 100 events in a single HTTP request by wrapping them in an events array. The server uses Redis pipelining so the entire batch costs one Upstash request unit instead of N — dramatically reducing latency and ingestion costs for high-volume workloads.

Batch Body Schema

Batch Response (202)

{
  "status": "queued",
  "queued": 3,
  "quota": {
    "remaining": 49997,
    "limit": 50000
  }
}

SDK Examples

import { LiteSOC } from 'litesoc-node';

const litesoc = new LiteSOC({ apiKey: process.env.LITESOC_API_KEY! });

// Track up to 100 events in ONE HTTP request
const { queued } = await litesoc.trackBatch([
  {
    eventName: 'auth.login_success',
    actor: { id: user.id, email: user.email },
    userIp: clientIp,
  },
  {
    eventName: 'data.export',
    actor: user.id,
    userIp: clientIp,
    metadata: { rows: 500, table: 'orders' },
  },
  {
    eventName: 'admin.settings_changed',
    actor: adminId,
    userIp: adminIp,
    metadata: { field: 'mfa_required', old: false, new: true },
  },
]);

console.log(`${queued} events accepted`);

Raw API Examples

For Go, Ruby, Rust, or other languages without an official SDK, use the raw HTTP API. All examples show how to properly extract and forward the end-user's IP address.

# ================================================
# LiteSOC API - cURL Example
# ================================================
# This example shows how to send a security event
# Replace YOUR_API_KEY with your actual API key
# ================================================

curl -X POST https://api.litesoc.io/collect \
  -H "Content-Type: application/json" \
  -H "x-api-key: lsoc_your_api_key_here" \
  -d '{
    "event": "auth.login_success",
    "actor": {
      "id": "user_123",
      "email": "user@example.com"
    },
    "user_ip": "203.0.113.50",
    "metadata": {
      "method": "password",
      "browser": "Chrome"
    }
  }'

Payload Schema

The request body must be a JSON object with the following structure:

Complete Example

{
  "event": "auth.login_success",
  "actor": {
    "id": "user_abc123",
    "email": "user@example.com"
  },
  "user_ip": "203.0.113.50",
  "metadata": {
    "method": "password",
    "mfa_used": true,
    "browser": "Chrome",
    "os": "macOS",
    "source": "main-website",
    "environment": "production"
  }
}

Standard Events

LiteSOC defines 26 standard security events organized into 5 categories. Events marked as criticaltrigger instant alerts on all plans.

IP Address Tracking

How to Extract User IP

Most web frameworks provide helpers, but behind a reverse proxy (nginx, Cloudflare, AWS ALB), you need to check headers in order of priority:

// Common pattern for extracting real user IP
function getUserIP(request) {
  return (
    // Standard proxy header (nginx, AWS ALB, most proxies)
    request.headers['x-forwarded-for']?.split(',')[0]?.trim() ||
    // Cloudflare-specific header
    request.headers['cf-connecting-ip'] ||
    // Alternative proxy header
    request.headers['x-real-ip'] ||
    // Direct connection (no proxy)
    request.connection?.remoteAddress ||
    '127.0.0.1'
  );
}

Server IP Auto-Detection

The server_ip field is automatically populated from request headers in this order:

Event Normalizer

LiteSOC accepts 60+ legacy event formats and automatically normalizes them to our 26 standard events. This means you can migrate from existing logging systems without changing your event names.

Use this API to programmatically read events and alerts, automate workflows, and integrate LiteSOC with tools like n8n, Zapier, or your own scripts. For n8n-specific setup and workflow examples, see the n8n Integration Guide.

Available Endpoints

The Management API provides the following endpoints for querying events and managing alerts. Endpoints marked with PRO+ require a Pro or Enterprise subscription.

Response Headers

Every Management API response includes these custom headers for transparency and debugging.

Error Responses

All Management API endpoints return consistent error responses. Understanding these error codes will help you build robust integrations and handle edge cases gracefully.

Error Response Format

All errors follow a standard JSON structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": { ... }  // Optional: additional context
  }
}

HTTP Status Codes

Common Error Examples

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

{
  "success": false,
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "Alerts API is blocked for Free tier",
    "details": {
      "required_plan": "pro",
      "current_plan": "free",
      "upgrade_url": "https://www.litesoc.io/pricing"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "RETENTION_EXPIRED",
    "message": "Event expired based on your plan retention.",
    "details": {
      "event_age_days": 15,
      "plan_retention_days": 7,
      "upgrade_url": "https://www.litesoc.io/pricing"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Maximum 60 requests per minute.",
    "retry_after": 45
  }
}

GET /events

Fetch security events from your organization. Access is tiered based on your subscription plan.

Query Parameters

Response Structure

The response includes the events array, pagination info, and metadata:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "event_name": "auth.login_success",
      "severity": "info",
      "actor_id": "user_abc123",
      "user_ip": "203.0.113.50",
      "server_ip": "10.0.0.1",
      "country_code": "US",
      "city": "San Francisco",
      "is_vpn": false,
      "is_tor": false,
      "is_proxy": false,
      "is_datacenter": false,
      "latitude": 37.7749,
      "longitude": -122.4194,
      "metadata": { ... },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "meta": {
    "plan": "pro",
    "retention_days": 30,
    "cutoff_date": "2024-01-01T00:00:00Z",
    "redacted": false,
    "max_limit": 100
  }
}

Event Object Fields

Each event object in the data array includes:

Pagination Object

GET /events/:id

Retrieve a single security event by its unique identifier. Useful for fetching detailed information about a specific event or for audit trail purposes.

Path Parameters

Example Request

curl -X GET "https://api.litesoc.io/events/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: YOUR_API_KEY"

Response Structure

Returns the event wrapped in a standard response object:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "event_name": "auth.login_success",
    "severity": "info",
    "actor_id": "user_abc123",
    "user_ip": "203.0.113.50",
    "server_ip": "10.0.0.1",
    "country_code": "US",
    "city": "San Francisco",
    "is_vpn": false,
    "is_tor": false,
    "is_proxy": false,
    "is_datacenter": false,
    "latitude": 37.7749,
    "longitude": -122.4194,
    "metadata": { ... },
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "plan": "pro",
    "retention_days": 30,
    "redacted": false
  }
}

GET /alertsPro+

Fetch security alerts with optional filters for status and severity.

Query Parameters

Response Fields

Each alert object in the response includes:

GET /alerts/:idPro+

Retrieve a single alert by its unique identifier. Useful for fetching detailed information about a specific alert or for audit trail purposes.

Path Parameters

Example Request

curl -X GET "https://api.litesoc.io/alerts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: YOUR_API_KEY"

Response

Returns the complete alert object with all fields.

PATCH /alerts/:idPro+

Update an alert's status. Use this to resolve alerts or mark them as safe (false positives).

Request Body

Response Fields

curl -X PATCH "https://api.litesoc.io/alerts/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: lsoc_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "resolve",
    "resolution_type": "contacted_user",
    "internal_notes": "Verified as legitimate user activity",
    "resolved_by": "user_abc123"
  }'

curl -X PATCH "https://api.litesoc.io/alerts/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: lsoc_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "mark_safe",
    "internal_notes": "Expected activity from automated deployment pipeline",
    "resolved_by": "user_abc123"
  }'

Enrichment DataPRO+

Security events include enrichment data in the metadata object for Pro and Enterprise plans. This includes network intelligence (VPN/Tor/proxy detection) and geolocation data.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event_name": "auth.login_success",
  "actor_id": "user_abc123",
  "user_ip": "203.0.113.50",
  "country_code": "US",
  "city": "San Francisco",
  "is_vpn": false,
  "is_tor": false,
  "is_proxy": false,
  "is_datacenter": false,
  "latitude": 37.7749,
  "longitude": -122.4194,
  "metadata": {
    "actor_email": "user@example.com",
    "method": "password",
    "geolocation": {
      "country": "US",
      "city": "San Francisco",
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    "network_intelligence": {
      "is_vpn": false,
      "is_tor": false,
      "is_proxy": false,
      "is_datacenter": false,
      "isp": "Comcast Cable Communications"
    }
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Top-Level Enrichment Fields

These fields are available directly on event objects:

Metadata Enrichment Objects

Additional enrichment data is also available in the metadata object:

Outgoing WebhooksPro+

LiteSOC sends real-time JSON alerts to your server when security threats are detected. Configure a webhook endpoint to receive instant notifications for brute force attacks, impossible travel, geo-anomalies, and critical security events.

Security & Signature Verification

To ensure the integrity and authenticity of webhook requests, LiteSOC includes a signature in each request. This section explains how to verify these signatures and secure your webhook endpoints.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Recreate the signed message: timestamp.payload
  const message = `${timestamp}.${payload}`;
  
  // Generate expected signature
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  
  // Constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Usage in your webhook handler:
const isValid = verifyWebhookSignature(
  JSON.stringify(req.body),
  req.headers['x-litesoc-signature'],
  req.headers['x-litesoc-timestamp'],
  process.env.LITESOC_WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Standard Payload Schema

All LiteSOC webhooks follow a standardized JSON schema, regardless of the specific event type.

{
  "version": "2.0",
  "event": "security.alert",
  "timestamp": "2026-03-01T14:32:00.000Z",
  "data": {
    "alert_id": "550e8400-e29b-41d4-a716-446655440000",
    "trigger_event_id": "660e8400-e29b-41d4-a716-446655440001",
    "org_id": "org_abc123",
    "event_name": "security.brute_force_detected",
    "severity": "high",
    "actor": {
      "id": "user_12345",
      "email": "user@example.com"
    },
    "user_ip": "203.0.113.50",
    "country_code": "RU",
    "timestamp": "2026-03-01T14:32:00.000Z",
    "forensics": {
      "network": {
        "is_vpn": true,
        "is_tor": false,
        "is_proxy": false,
        "is_datacenter": false,
        "isp": "Example ISP"
      },
      "location": {
        "city": "Moscow",
        "country_code": "RU",
        "latitude": 55.7558,
        "longitude": 37.6173
      }
    },
    "metadata": {
      "failed_attempts": 15,
      "unique_actors": 3,
      "time_window_minutes": 5
    }
  }
}

Event Triggers

LiteSOC supports a wide range of security event triggers that can fire webhooks. Each event has a severity level and may be restricted to certain subscription plans. Below is a reference table of common events that can trigger outgoing webhooks.

Implementation Example

// app/api/webhooks/litesoc/route.ts
import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.LITESOC_WEBHOOK_SECRET!;

function verifySignature(payload: string, signature: string, timestamp: string): boolean {
  const message = `${timestamp}.${payload}`;
  const expected = 'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(message).digest('hex');
  
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false;
  }
}

export async function POST(request: NextRequest) {
  const signature = request.headers.get('x-litesoc-signature');
  const timestamp = request.headers.get('x-litesoc-timestamp');
  
  if (!signature || !timestamp) {
    return NextResponse.json({ error: 'Missing headers' }, { status: 400 });
  }
  
  // Get raw body for signature verification
  const payload = await request.text();
  
  // Verify signature
  if (!verifySignature(payload, signature, timestamp)) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }
  
  // Parse the verified payload
  const webhook = JSON.parse(payload);
  const alert = webhook.data;
  
  console.log(`[LiteSOC] Received alert: ${alert.event_name}`);
  console.log(`[LiteSOC] Alert ID: ${alert.alert_id}`);
  console.log(`[LiteSOC] Severity: ${alert.severity}`);
  
  // Process based on event type
  switch (alert.event_name) {
    case 'security.brute_force_detected':
      // Block the IP, notify security team, etc.
      await handleBruteForce(alert);
      break;
    case 'security.impossible_travel':
      // Force re-authentication, notify user
      await handleImpossibleTravel(alert);
      break;
    case 'admin.privilege_escalation':
      // High priority: investigate immediately
      await handlePrivilegeEscalation(alert);
      break;
    default:
      console.log(`[LiteSOC] Unhandled event: ${alert.event_name}`);
  }
  
  // Always return 200 to acknowledge receipt
  return NextResponse.json({ received: true });
}

async function handleBruteForce(alert: any) {
  // Example: Add IP to blocklist
  console.log(`Blocking IP: ${alert.user_ip}`);
  // await blockIP(alert.user_ip);
}

async function handleImpossibleTravel(alert: any) {
  // Example: Revoke user sessions
  console.log(`Suspicious travel for actor: ${alert.actor.id}`);
  // await revokeUserSessions(alert.actor.id);
}

async function handlePrivilegeEscalation(alert: any) {
  // Example: Alert security team via Slack
  console.log(`CRITICAL: Privilege escalation by ${alert.actor.id}`);
  // await sendSlackAlert(alert);
}

Best Practices

To build a robust integration with LiteSOC webhooks, follow these best practices for security, reliability, and performance.

This section covers the technical infrastructure details you need to know: rate limits for both APIs, data retention policies, and the custom headers returned in API responses.

Rate Limits

LiteSOC has two types of rate limits: Event Collection API (for sending security logs) and Management API (for reading data via n8n or custom integrations).

Event Collection API

Optimized for high-volume ingestion when sending security events from your application.

Management API

Designed for stable polling when reading events and alerts via n8n or custom integrations.

Retention Policy

Data retention determines how long your security events and alerts are stored. Results from the Management API are strictly filtered by your plan's retention window.

{
  "success": false,
  "error": {
    "code": "RETENTION_EXPIRED",
    "message": "Event expired based on your plan retention.",
    "retention_days": 7
  }
}

Security Intelligence

LiteSOC automatically enriches every security event with powerful forensic data. When you provide the user_ip field, we unlock a comprehensive suite of security intelligence features.

Geolocation Enrichment

Every event with a valid user_ip is automatically enriched with geolocation data. This data is stored in the database and displayed in the Event Forensics view.

Network Intelligence

LiteSOC analyzes every IP address against comprehensive databases of known VPN providers, Tor exit nodes, proxy services, and cloud/datacenter IP ranges. This helps you identify potentially suspicious traffic sources.

Event Forensics UI

View comprehensive forensic data for any security event directly in your dashboard. Simply click any row in the Activity Feed table to open the Event Detail Sheet.

Enrichment Pipeline

When you submit an event to LiteSOC, it returns HTTP 202 Accepted immediately, meaning your data has been queued for processing. Behind the scenes, LiteSOC runs a powerful enrichment pipeline to transform raw events into actionable security intelligence.

Pipeline Stages

Enriched Event Example

After processing, your raw event is enriched with security intelligence data:

{
  "event": "auth.login_success",
  "actor_id": "user_123",
  "actor_email": "user@example.com",
  "user_ip": "185.220.101.42",
  
  // Geo-Mapping (auto-enriched)
  "country": "DE",
  "city": "Frankfurt",
  "latitude": 50.1109,
  "longitude": 8.6821,
  
  // IP Reputation (auto-enriched)
  "is_vpn": false,
  "is_tor": true,
  "is_proxy": false,
  "is_datacenter": false,
  "network_type": "tor",
  "network_provider": "Tor Exit Node",
  
  // Threat Scoring (auto-enriched)
  "severity": "critical",
  "risk_signals": ["tor_exit_node", "high_risk_country"]
}

Plan Features

LiteSOC offers three tiers with progressively more powerful threat detection capabilities.

Threat Detection

LiteSOC automatically analyzes your security events to detect threats in real-time.

Remediation WebhooksPro+

Automatically receive webhook notifications when admins resolve security alerts. Use this to trigger automated remediation in your application—like blocking users, resetting passwords, or revoking sessions.

{
  "event_type": "alert.resolved",
  "timestamp": "2024-01-15T14:32:00Z",
  "alert": {
    "id": "alert_abc123",
    "type": "impossible_travel",
    "status": "resolved",
    "severity": "high"
  },
  "resolution": {
    "type": "blocked_ip",        // or: reset_password, contacted_user, false_positive, other
    "notes": "User confirmed they weren't traveling. Blocking suspicious IP.",
    "resolved_by": "admin@company.com",
    "resolved_at": "2024-01-15T14:32:00Z"
  },
  "actor": {
    "id": "user_12345",          // The affected user's ID
    "ip": "203.0.113.50"         // The suspicious IP address
  },
  "organization": {
    "id": "org_xyz789"
  }
}

// POST /api/security-callback
app.post('/api/security-callback', async (req, res) => {
  const { event_type, resolution, actor } = req.body;

  if (event_type !== 'alert.resolved') {
    return res.status(200).json({ received: true });
  }

  // Handle different resolution types
  switch (resolution.type) {
    case 'blocked_ip':
      // Add IP to your blocklist
      await firewall.blockIP(actor.ip);
      break;

    case 'reset_password':
      // Force password reset for the user
      await db.users.update({
        where: { id: actor.id },
        data: { 
          password_reset_required: true,
          sessions: { deleteMany: {} }  // Invalidate all sessions
        }
      });
      break;

    case 'contacted_user':
      // Log the interaction
      await db.audit_log.create({
        data: {
          user_id: actor.id,
          action: 'security_contact',
          notes: resolution.notes,
          admin: resolution.resolved_by
        }
      });
      break;

    case 'false_positive':
      // Maybe whitelist this pattern
      console.log('False positive logged:', actor.id, actor.ip);
      break;
  }

  res.json({ success: true });
});

signature = HMAC-SHA256(
  key: signing_secret,
  message: timestamp + "." + JSON.stringify(payload)
)

const crypto = require('crypto');

function verifyLiteSOCWebhook(payload, signature, timestamp, secret) {
  // Signature is computed over: timestamp.payload
  // This prevents replay attacks
  const signedPayload = timestamp + '.' + JSON.stringify(payload);
  
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/api/security-callback', (req, res) => {
  const signature = req.headers['x-litesoc-signature'];
  const timestamp = req.headers['x-litesoc-timestamp'];
  
  // Optional: Reject requests older than 5 minutes (anti-replay)
  const requestTime = new Date(timestamp).getTime();
  const now = Date.now();
  if (Math.abs(now - requestTime) > 5 * 60 * 1000) {
    return res.status(401).json({ error: 'Request too old' });
  }
  
  if (!signature || !verifyLiteSOCWebhook(req.body, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process the webhook...
});