livedash-node/docs/api-reference.md

LiveDash-Node API Reference

This document provides a comprehensive reference for all API endpoints in the LiveDash-Node application, including authentication, security monitoring, audit logging, and administrative functions.

Base URL

Local Development: http://localhost:3000
Production: https://your-domain.com

Authentication

All API endpoints (except public endpoints) require authentication via NextAuth.js session cookies.

Authentication Headers

Cookie: next-auth.session-token=<session-token>

CSRF Protection

State-changing endpoints require CSRF tokens:

X-CSRF-Token: <csrf-token>

Get CSRF token:

GET /api/csrf-token

API Endpoints Overview

Public Endpoints

• POST /api/csp-report - CSP violation reporting (no auth required)
• OPTIONS /api/csp-report - CORS preflight

Authentication Endpoints

• POST /api/auth/[...nextauth] - NextAuth.js authentication
• GET /api/csrf-token - Get CSRF token
• POST /api/register - User registration
• POST /api/forgot-password - Password reset request
• POST /api/reset-password - Password reset completion

Admin Endpoints (ADMIN role required)

• GET /api/admin/audit-logs - Retrieve audit logs
• POST /api/admin/audit-logs/retention - Manage audit log retention
• GET /api/admin/batch-monitoring - Batch processing monitoring
• POST /api/admin/batch-monitoring/{id}/retry - Retry failed batch job

Platform Admin Endpoints (Platform admin only)

• GET /api/admin/security-monitoring - Security monitoring metrics
• POST /api/admin/security-monitoring - Update security configuration
• GET /api/admin/security-monitoring/alerts - Alert management
• POST /api/admin/security-monitoring/alerts - Acknowledge alerts
• GET /api/admin/security-monitoring/export - Export security data
• POST /api/admin/security-monitoring/threat-analysis - Threat analysis

Security Monitoring Endpoints

• GET /api/csp-metrics - CSP violation metrics
• POST /api/csp-report - CSP violation reporting

Dashboard Endpoints

• GET /api/dashboard/sessions - Session data
• GET /api/dashboard/session/{id} - Individual session details
• GET /api/dashboard/metrics - Dashboard metrics
• GET /api/dashboard/config - Dashboard configuration

Platform Management

• GET /api/platform/companies - Company management
• POST /api/platform/companies - Create company
• GET /api/platform/companies/{id} - Company details
• GET /api/platform/companies/{id}/users - Company users
• POST /api/platform/companies/{id}/users - Add company user

tRPC Endpoints

• POST /api/trpc/[trpc] - tRPC procedure calls

Detailed Endpoint Documentation

Admin Audit Logs

Get Audit Logs

GET /api/admin/audit-logs

Authorization: ADMIN role required

Query Parameters:

• page (number, optional): Page number (default: 1)
• limit (number, optional): Records per page, max 100 (default: 50)
• eventType (string, optional): Filter by event type
• outcome (string, optional): Filter by outcome (SUCCESS, FAILURE, BLOCKED, etc.)
• severity (string, optional): Filter by severity (LOW, MEDIUM, HIGH, CRITICAL)
• userId (string, optional): Filter by user ID
• startDate (string, optional): Start date (ISO 8601)
• endDate (string, optional): End date (ISO 8601)

Response:

{
  "success": true,
  "data": {
    "auditLogs": ["// Array of audit log entries"],
    "pagination": {
      "page": 1,
      "limit": 50,
      "totalCount": 150,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Rate Limit: Inherits from auth rate limiting

Manage Audit Log Retention

POST /api/admin/audit-logs/retention

Authorization: ADMIN role required

Request Body:

{
  "action": "cleanup" | "configure" | "status",
  "retentionDays": 90,
  "dryRun": true
}

Response:

{
  "success": true,
  "data": {
    "action": "cleanup",
    "recordsAffected": 1250,
    "retentionDays": 90,
    "dryRun": true
  }
}

Security Monitoring

Get Security Metrics

GET /api/admin/security-monitoring

Authorization: Platform admin required

Query Parameters:

• startDate (string, optional): Start date (ISO 8601)
• endDate (string, optional): End date (ISO 8601)
• companyId (string, optional): Filter by company
• severity (string, optional): Filter by severity

Response:

{
  "metrics": {
    "securityScore": 85,
    "threatLevel": "LOW",
    "eventCounts": {
      "// Event count statistics": null
    },
    "anomalies": ["// Array of security anomalies"]
  },
  "alerts": ["// Array of security alerts"],
  "config": {
    "// Security configuration": null
  },
  "timeRange": {
    "// Time range for the data": null
  }
}

Update Security Configuration

POST /api/admin/security-monitoring

Authorization: Platform admin required

Request Body:

{
  "thresholds": {
    "failedLoginsPerMinute": 5,
    "rateLimitViolationsPerMinute": 10
  },
  "alerting": {
    "enabled": true,
    "channels": ["EMAIL", "WEBHOOK"]
  }
}

CSP Monitoring

CSP Violation Reporting

POST /api/csp-report

Authorization: None (public endpoint)

Headers:

• Content-Type: application/csp-report or application/json

Request Body (automatic from browser):

{
  "csp-report": {
    "document-uri": "https://example.com/page",
    "violated-directive": "script-src 'self'",
    "blocked-uri": "https://malicious.com/script.js",
    "source-file": "https://example.com/page",
    "line-number": 42
  }
}

Rate Limit: 10 reports per minute per IP

Response: 204 No Content

Get CSP Metrics

GET /api/csp-metrics

Authorization: Admin role required

Query Parameters:

• timeRange (string, optional): Time range (1h, 6h, 24h, 7d, 30d)
• format (string, optional): Response format (json, csv)
• groupBy (string, optional): Group by field (hour, directive, etc.)
• includeDetails (boolean, optional): Include violation details

Response:

{
  "success": true,
  "data": {
    "summary": {
      "totalViolations": 45,
      "uniqueViolations": 12,
      "highRiskViolations": 3,
      "bypassAttempts": 1
    },
    "trends": {
      "// CSP trend data": null
    },
    "topViolations": ["// Array of top CSP violations"],
    "riskAnalysis": {
      "// CSP risk analysis data": null
    },
    "violations": ["// Array of CSP violations"]
  }
}

Batch Monitoring

Get Batch Monitoring Data

GET /api/admin/batch-monitoring

Authorization: ADMIN role required

Query Parameters:

• timeRange (string, optional): Time range (1h, 6h, 24h, 7d, 30d)
• status (string, optional): Filter by status (pending, completed, failed)
• jobType (string, optional): Filter by job type
• includeDetails (boolean, optional): Include detailed job information
• page (number, optional): Page number
• limit (number, optional): Records per page

Response:

{
  "success": true,
  "data": {
    "summary": {
      "totalJobs": 156,
      "completedJobs": 142,
      "failedJobs": 8,
      "costSavings": {}
    },
    "queues": {
      "// Queue statistics": null
    },
    "performance": {
      "// Performance metrics": null
    },
    "jobs": ["// Array of batch jobs"]
  }
}

Retry Batch Job

POST /api/admin/batch-monitoring/{jobId}/retry

Authorization: ADMIN role required

Response:

{
  "success": true,
  "data": {
    "jobId": "batch-job-123",
    "status": "retrying",
    "message": "Job queued for retry"
  }
}

CSRF Token

Get CSRF Token

GET /api/csrf-token

Authorization: None

Response:

{
  "csrfToken": "abc123..."
}

Headers Set:

• Set-Cookie: HTTP-only CSRF token cookie

Authentication

User Registration

POST /api/register

Authorization: None

Headers Required:

• X-CSRF-Token: CSRF token

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "name": "John Doe",
  "companyName": "Acme Corp"
}

Rate Limit: 3 attempts per hour per IP

Response:

{
  "success": true,
  "message": "User registered successfully",
  "userId": "user-123"
}

Password Reset Request

POST /api/forgot-password

Authorization: None

Headers Required:

• X-CSRF-Token: CSRF token

Request Body:

{
  "email": "user@example.com"
}

Rate Limit: 5 attempts per 15 minutes per IP

Response:

{
  "success": true,
  "message": "Password reset email sent"
}

Password Reset Completion

POST /api/reset-password

Authorization: None

Headers Required:

• X-CSRF-Token: CSRF token

Request Body:

{
  "token": "reset-token-123",
  "password": "NewSecurePassword123!"
}

Response:

{
  "success": true,
  "message": "Password reset successfully"
}

Error Responses

Standard Error Format

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

Common HTTP Status Codes

Status	Description	Common Causes
200	OK	Successful request
201	Created	Resource created successfully
204	No Content	Successful request with no response body
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Authentication required or invalid
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Resource already exists or conflict
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Codes

Code	Description	Resolution
UNAUTHORIZED	No valid session	Login required
FORBIDDEN	Insufficient permissions	Check user role
VALIDATION_ERROR	Invalid input data	Check request format
RATE_LIMITED	Too many requests	Wait and retry
CSRF_INVALID	Invalid CSRF token	Get new token
NOT_FOUND	Resource not found	Check resource ID
CONFLICT	Resource conflict	Check existing data

Rate Limiting

Authentication Endpoints

• Login: 5 attempts per 15 minutes per IP
• Registration: 3 attempts per hour per IP
• Password Reset: 5 attempts per 15 minutes per IP

Security Endpoints

• CSP Reports: 10 reports per minute per IP
• Admin Endpoints: 60 requests per minute per user
• Security Monitoring: 30 requests per minute per user

General API

• Dashboard Endpoints: 120 requests per minute per user
• Platform Management: 60 requests per minute per user

Security Headers

All API responses include security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: [CSP directives]

CORS Configuration

Allowed Origins

• Development: http://localhost:3000
• Production: https://your-domain.com

Allowed Methods

• GET, POST, PUT, DELETE, PATCH, OPTIONS

Allowed Headers

• Content-Type, Authorization, X-CSRF-Token, X-Requested-With

Pagination

Standard Pagination Format

{
  "data": ["// Array of response data"],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 150,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Pagination Parameters

• page: Page number (1-based, default: 1)
• limit: Records per page (default: 50, max: 100)

Filtering and Sorting

Common Filter Parameters

• startDate / endDate: Date range filtering (ISO 8601)
• status: Status filtering
• userId / companyId: Entity filtering
• eventType: Event type filtering
• severity: Severity level filtering

Sorting Parameters

• sortBy: Field to sort by
• sortOrder: asc or desc (default: desc)

Response Caching

Cache Headers

Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0

Cache Strategy

• Security data: Never cached
• Static data: Browser cache for 5 minutes
• User data: No cache for security

API Versioning

Current Version

• Version: v1 (implied, no version prefix required)
• Introduced: January 2025

Future Versioning

• Breaking changes will introduce new versions
• Format: /api/v2/endpoint
• Backward compatibility maintained for 12 months

SDK and Client Libraries

JavaScript/TypeScript Client

// Initialize client
const client = new LiveDashClient({
  baseURL: "https://your-domain.com",
  apiKey: "your-api-key", // For future API key auth
});

// Get audit logs
const auditLogs = await client.admin.getAuditLogs({
  page: 1,
  limit: 50,
  eventType: "login_attempt",
});

// Get security metrics
const metrics = await client.security.getMetrics({
  timeRange: "24h",
});

tRPC Client

import { createTRPCNext } from "@trpc/next";

const trpc = createTRPCNext({
  config() {
    return {
      url: "/api/trpc",
    };
  },
});

// Use tRPC procedures
const { data: user } = trpc.auth.getUser.useQuery();
const updateProfile = trpc.user.updateProfile.useMutation();

Testing

API Testing Tools

# Test with curl
curl -X GET "http://localhost:3000/api/admin/audit-logs" \
  -H "Cookie: next-auth.session-token=..." \
  -H "X-CSRF-Token: ..."

# Test with HTTPie
http GET localhost:3000/api/csp-metrics \
  timeRange==24h \
  Cookie:next-auth.session-token=...

Integration Tests

// Example test
describe("Admin Audit Logs API", () => {
  test("should return paginated audit logs", async () => {
    const response = await request(app)
      .get("/api/admin/audit-logs?page=1&limit=10")
      .set("Cookie", "next-auth.session-token=...")
      .expect(200);

    expect(response.body.success).toBe(true);
    expect(response.body.data.auditLogs).toHaveLength(10);
    expect(response.body.data.pagination.page).toBe(1);
  });
});

Related Documentation

• Admin Audit Logs API
• CSP Metrics API
• Security Monitoring
• CSRF Protection
• Batch Monitoring Dashboard

This API reference provides comprehensive documentation for all endpoints in the LiveDash-Node application. For specific implementation details, refer to the individual documentation files for each feature area.