Audit Log API

The Audit Log system automatically records every significant action performed within an organization — create, update, delete, and access events across all resource types. Logs are immutable and queryable for compliance, debugging, and analytics.

Authentication

All audit endpoints require a valid PASETO token and membership in the target organization.

Data Model

Each audit log entry contains:

Field	Type	Description
_id	ObjectId	Unique log entry ID
orgId	ObjectId	Organization the action belongs to
userId	ObjectId	User who performed the action
userName	string	Display name of the acting user
action	string	Action identifier (e.g. booking.created)
resourceType	string	Resource type (e.g. booking, invoice, room)
resourceId	ObjectId	ID of the affected resource
details	object	Action-specific metadata / change summary
ipAddress	string	Client IP address
userAgent	string	Client user-agent string
createdAt	Date	ISO 8601 timestamp

Example Entry

{
  "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
  "orgId": "org_abc123",
  "userId": "usr_xyz789",
  "userName": "John Doe",
  "action": "booking.created",
  "resourceType": "booking",
  "resourceId": "bkg_456def",
  "details": {
    "guestName": "Jane Smith",
    "roomNumber": "201",
    "checkIn": "2026-03-01",
    "checkOut": "2026-03-05"
  },
  "ipAddress": "203.0.113.42",
  "userAgent": "Mozilla/5.0 ...",
  "createdAt": "2026-02-20T14:30:00.000Z"
}

---

Endpoints

GET /api/audit/:orgId/logs

Retrieve paginated audit logs for an organization with flexible filtering.

Path Parameters

Param	Type	Description
orgId	string	Organization ID

Query Parameters

Param	Type	Default	Description
page	number	1	Page number
limit	number	50	Items per page (max 100)
action	string	—	Filter by action (e.g. booking.created)
userId	string	—	Filter by acting user ID
resourceType	string	—	Filter by resource type (e.g. invoice)
startDate	string	—	ISO 8601 start date (inclusive)
endDate	string	—	ISO 8601 end date (inclusive)

Example Request

GET /api/audit/org_abc123/logs?page=1&limit=20&action=booking.created&startDate=2026-02-01&endDate=2026-02-28

Response 200 OK

{
  "success": true,
  "data": [
    {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "action": "booking.created",
      "userName": "John Doe",
      "resourceType": "booking",
      "resourceId": "bkg_456def",
      "details": { "guestName": "Jane Smith", "roomNumber": "201" },
      "createdAt": "2026-02-20T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "pages": 8
  }
}

---

GET /api/audit/:orgId/statistics

Aggregated audit statistics for the organization — action breakdowns, top actors, daily trends.

Path Parameters

Param	Type	Description
orgId	string	Organization ID

Response 200 OK

{
  "success": true,
  "statistics": {
    "totalLogs": 4832,
    "actionBreakdown": [
      { "action": "booking.created", "count": 1240 },
      { "action": "invoice.created", "count": 892 },
      { "action": "payment.recorded", "count": 756 },
      { "action": "guest.updated", "count": 510 },
      { "action": "room.updated", "count": 234 }
    ],
    "topActors": [
      { "userId": "usr_xyz789", "userName": "John Doe", "count": 1820 },
      { "userId": "usr_abc456", "userName": "Jane Smith", "count": 1340 }
    ],
    "dailyTrend": [
      { "date": "2026-02-18", "count": 64 },
      { "date": "2026-02-19", "count": 78 },
      { "date": "2026-02-20", "count": 52 }
    ]
  }
}

---

GET /api/audit/:orgId/by-user/:userId

Retrieve all audit logs for a specific user within the organization.

Path Parameters

Param	Type	Description
orgId	string	Organization ID
userId	string	Target user ID

Query Parameters

Param	Type	Default	Description
page	number	1	Page number
limit	number	50	Items per page

Response 200 OK

{
  "success": true,
  "user": {
    "id": "usr_xyz789",
    "name": "John Doe"
  },
  "data": [
    {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "action": "booking.created",
      "resourceType": "booking",
      "resourceId": "bkg_456def",
      "details": { "guestName": "Jane Smith" },
      "createdAt": "2026-02-20T14:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1820, "pages": 37 }
}

---

GET /api/audit/:orgId/by-resource/:resourceType/:resourceId

Retrieve the complete audit trail for a specific resource (e.g., a single booking or invoice).

Path Parameters

Param	Type	Description
orgId	string	Organization ID
resourceType	string	Resource type (booking, invoice, room, etc.)
resourceId	string	Resource document ID

Response 200 OK

{
  "success": true,
  "resource": {
    "type": "booking",
    "id": "bkg_456def"
  },
  "data": [
    {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "action": "booking.created",
      "userName": "John Doe",
      "details": { "guestName": "Jane Smith", "roomNumber": "201" },
      "createdAt": "2026-02-20T14:30:00.000Z"
    },
    {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e2",
      "action": "booking.updated",
      "userName": "John Doe",
      "details": { "field": "checkOut", "from": "2026-03-05", "to": "2026-03-07" },
      "createdAt": "2026-02-21T09:15:00.000Z"
    }
  ]
}

---

GET /api/audit/:orgId/:logId

Fetch a single audit log entry by its ID.

Path Parameters

Param	Type	Description
orgId	string	Organization ID
logId	string	Audit log ID

Response 200 OK

{
  "success": true,
  "log": {
    "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
    "orgId": "org_abc123",
    "userId": "usr_xyz789",
    "userName": "John Doe",
    "action": "booking.created",
    "resourceType": "booking",
    "resourceId": "bkg_456def",
    "details": {
      "guestName": "Jane Smith",
      "roomNumber": "201",
      "checkIn": "2026-03-01",
      "checkOut": "2026-03-05"
    },
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0 ...",
    "createdAt": "2026-02-20T14:30:00.000Z"
  }
}

---

Action Reference

Common action identifiers recorded by the system:

Action	Resource Type	Trigger
booking.created	booking	New booking created
booking.updated	booking	Booking details modified
booking.deleted	booking	Booking cancelled / removed
invoice.created	invoice	Invoice generated
invoice.updated	invoice	Invoice edited
payment.recorded	payment	Payment received
expense.created	expense	Expense entry added
guest.created	guest	Guest registered
guest.updated	guest	Guest details updated
room.created	room	Room added
room.updated	room	Room details modified
user.invited	user	User invited to organization
user.role_changed	user	User role updated
settings.updated	settings	Organization settings changed

---

Error Responses

{
  "success": false,
  "message": "Descriptive error message"
}

Status	Meaning
400	Invalid query parameters
401	Unauthorized — missing or invalid token
403	Forbidden — not a member of the org
404	Log entry or org not found
500	Internal server error