Querying Audit Logs

Search and filter audit logs for investigations, compliance reporting, and monitoring.

Query Endpoint

GET /audit-logs

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)
userId	UUID	Filter by user who performed action
action	string	Filter by action type
resourceType	string	Filter by resource type
resourceId	UUID	Filter by specific resource
startDate	ISO 8601	Filter logs from this date
endDate	ISO 8601	Filter logs until this date
correlationId	string	Filter by correlation ID

Response

{
  "data": [
    {
      "id": "log-001",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "action": "UPDATE",
      "resourceType": "USER",
      "resourceId": "661f9511-f30c-52e5-b827-ff3366551111",
      "oldValue": { "firstName": "John" },
      "newValue": { "firstName": "Jonathan" },
      "metadata": {},
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0...",
      "correlationId": "req-abc123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "user": {
        "email": "admin@example.com",
        "firstName": "Admin",
        "lastName": "User"
      }
    }
  ],
  "pagination": {
    "total": 1250,
    "page": 1,
    "limit": 20,
    "totalPages": 63
  }
}

Common Queries

User Activity

Get all actions by a specific user:

GET /audit-logs?userId=550e8400-e29b-41d4-a716-446655440000

Resource History

Get all changes to a specific resource:

GET /audit-logs?resourceType=USER&resourceId=661f9511-f30c-52e5-b827-ff3366551111

Date Range

Get logs from a specific period:

GET /audit-logs?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z

Failed Logins

Get login failures:

GET /audit-logs?action=LOGIN_FAILURE

Correlation Tracking

Track all operations from a single request:

GET /audit-logs?correlationId=req-abc123

Get Single Log Entry

GET /audit-logs/:id

Response

{
  "id": "log-001",
  "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "action": "UPDATE",
  "resourceType": "USER",
  "resourceId": "661f9511-f30c-52e5-b827-ff3366551111",
  "oldValue": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "newValue": {
    "firstName": "Jonathan",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "metadata": {
    "changedFields": ["firstName"]
  },
  "ipAddress": "192.168.1.100",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "correlationId": "req-abc123",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@example.com",
    "firstName": "Admin",
    "lastName": "User"
  }
}

Code Examples

TypeScript

interface AuditLog {
  id: string;
  userId: string | null;
  action: string;
  resourceType: string;
  resourceId: string | null;
  oldValue: any;
  newValue: any;
  ipAddress: string | null;
  createdAt: string;
}

interface AuditQueryParams {
  page?: number;
  limit?: number;
  userId?: string;
  action?: string;
  resourceType?: string;
  resourceId?: string;
  startDate?: string;
  endDate?: string;
}

async function queryAuditLogs(
  accessToken: string,
  params: AuditQueryParams
): Promise<{ data: AuditLog[]; pagination: any }> {
  const url = new URL('http://localhost:8091/audit-logs');

  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined) {
      url.searchParams.set(key, String(value));
    }
  });

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${accessToken}` },
  });
  return response.json();
}

// Example: Get user activity in last 7 days
const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
const logs = await queryAuditLogs(token, {
  userId: 'user-id',
  startDate: weekAgo,
  limit: 100,
});

cURL

# Query all logs
curl "http://localhost:8091/audit-logs?page=1&limit=50" \
  -H "Authorization: Bearer <access-token>"

# Query by user
curl "http://localhost:8091/audit-logs?userId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <access-token>"

# Query by date range
curl "http://localhost:8091/audit-logs?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer <access-token>"

# Get specific log
curl "http://localhost:8091/audit-logs/log-001" \
  -H "Authorization: Bearer <access-token>"