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

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

### CSRF Protection

State-changing endpoints require CSRF tokens:

```http
X-CSRF-Token: <csrf-token>
```

Get CSRF token:

```http
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

```http
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**:

```json
{
  "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

```http
POST /api/admin/audit-logs/retention
```

**Authorization**: ADMIN role required

**Request Body**:

<!-- prettier-ignore -->
```json
{
  "action": "cleanup" | "configure" | "status",
  "retentionDays": 90,
  "dryRun": true
}
```

**Response**:

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

### Security Monitoring

#### Get Security Metrics

```http
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**:

```json
{
  "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

```http
POST /api/admin/security-monitoring
```

**Authorization**: Platform admin required

**Request Body**:

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

### CSP Monitoring

#### CSP Violation Reporting

```http
POST /api/csp-report
```

**Authorization**: None (public endpoint)

**Headers**:

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

**Request Body** (automatic from browser):

```json
{
  "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

```http
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**:

```json
{
  "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

```http
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**:

```json
{
  "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

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

**Authorization**: ADMIN role required

**Response**:

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

### CSRF Token

#### Get CSRF Token

```http
GET /api/csrf-token
```

**Authorization**: None

**Response**:

```json
{
  "csrfToken": "abc123..."
}
```

**Headers Set**:

- `Set-Cookie`: HTTP-only CSRF token cookie

### Authentication

#### User Registration

```http
POST /api/register
```

**Authorization**: None

**Headers Required**:

- `X-CSRF-Token`: CSRF token

**Request Body**:

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

**Rate Limit**: 3 attempts per hour per IP

**Response**:

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

#### Password Reset Request

```http
POST /api/forgot-password
```

**Authorization**: None

**Headers Required**:

- `X-CSRF-Token`: CSRF token

**Request Body**:

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

**Rate Limit**: 5 attempts per 15 minutes per IP

**Response**:

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

#### Password Reset Completion

```http
POST /api/reset-password
```

**Authorization**: None

**Headers Required**:

- `X-CSRF-Token`: CSRF token

**Request Body**:

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

**Response**:

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

## Error Responses

### Standard Error Format

```json
{
  "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:

```http
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

```json
{
  "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

```http
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

```javascript
// 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

```javascript
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

```bash
# 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

```javascript
// 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](./admin-audit-logs-api.md)
- [CSP Metrics API](./csp-metrics-api.md)
- [Security Monitoring](./security-monitoring.md)
- [CSRF Protection](./CSRF_PROTECTION.md)
- [Batch Monitoring Dashboard](./batch-monitoring-dashboard.md)

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.