API Reference

Audit Logs

Overview

Fetch a paginated audit trail of tenant moderation and governance actions — bans, mutes, report resolutions, settings changes, and related events — for the Platform Moderation → Audit view.

Each log entry records who acted (actorType / actorName), what happened (action), and an optional target plus structured details.

When to use this endpoint?

Use Audit Logs when:

Opening Platform → Moderation → Audit to review recent actions.
Confirming a ban, mute, unban, or report resolution was recorded.
Building a timeline table with actor, action slug, target, and timestamp.
Reading pagination to page through a long history.

Part of the client Platform Moderation module. This endpoint is read-only — actions themselves are performed via List/Resolve Reports, Mute, Ban, and Settings endpoints.

Response Data

data.list is an array of audit entries. data.pagination describes the current page.

Log entry fields

Field	Description
_id	Audit log entry id.
actorType	Who performed the action: `client` (workspace admin), `superadmin`, or `user`.
actorId / actorName	Actor identity when available (for example the Platform admin who banned a user).
action	Action slug such as `moderation.user-banned`, `moderation.user-muted`, or report / settings actions. Display as a human label in the UI (for example "User banned").
targetType / targetId	Optional resource the action applied to (for example `user` + user id).
details	Optional structured context (for example `userName`). Shape varies by action.
createdAt / updatedAt	ISO timestamps for the log row.

pagination

Field	Description
currentPage	Current 1-based page.
totalCount	Total audit log entries.
pageSize	Items returned per page (for example 20).
hasNextPage / hasPreviousPage	Whether adjacent pages are available.

GET{baseUrl}/api/{apiVersion}/client/audit-logs

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Client Access Token with tenant admin privileges (Platform panel).
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Required when is-tenant=true.

This endpoint has no request body. Call it with tenant headers only; pagination metadata is returned using server defaults.

Success Response (HTTP 200 OK)

On success, the API returns a paginated list of audit log entries.

json

{
  "success": true,
  "message": "Audit logs fetched successfully",
  "data": {
    "list": [
      {
        "_id": "6a589c09c43829ebc51a80ed",
        "actorType": "client",
        "actorId": "6a589b96cfa34ab66e35b2a9",
        "actorName": "Mod Test",
        "action": "moderation.user-banned",
        "targetType": "user",
        "targetId": "6a589b96cfa34ab66e35b2ab",
        "details": {
          "userName": "Bad Actor"
        },
        "createdAt": "2026-07-16T08:53:29.542Z",
        "updatedAt": "2026-07-16T08:53:29.542Z",
        "__v": 0
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalCount": 4,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "pageSize": 20
    }
  },
  "error": null
}

Common Errors

Fetch fails when the token is missing/invalid or the caller is not a tenant admin.

HTTP 401 Unauthorized — No token

json

{
  "success": false,
  "message": "No token, authorization denied",
  "data": null,
  "error": "Unauthorized"
}

HTTP 403 Forbidden — Tenant admin required

json

{
  "success": false,
  "message": "Access denied: tenant admin privileges required",
  "data": null,
  "error": null
}

Code	Reason
401 Unauthorized	Access Token is missing, invalid, or expired.
403 Forbidden	Tenant admin privileges required for Platform Moderation.
500 Internal Server Error	An unexpected error occurred while fetching audit logs.

Best Practices

Humanize action slugs in the UI (for example moderation.user-banned→ "User banned").
Expand details on demand — shapes differ by action.
Badge actorType so workspace admin, super admin, and end-user actions are easy to scan.
Refetch after Mute, Ban, or Resolve so new entries appear promptly.
Restrict audit content to trusted Platform admins — it can include user names and moderation decisions.

Audit trail ready

Use the list to verify moderation actions. To change state, go back to List Reports, Mute / Unmute User, or Ban / Unban User.

Field

Description

_id

Audit log entry id.

actorType

Who performed the action: client (workspace admin), superadmin, or user.

actorId / actorName

Actor identity when available (for example the Platform admin who banned a user).

action

Action slug such as moderation.user-banned, moderation.user-muted, or report / settings actions. Display as a human label in the UI (for example "User banned").

targetType / targetId

Optional resource the action applied to (for example user + user id).

details

Optional structured context (for example userName). Shape varies by action.

createdAt / updatedAt

ISO timestamps for the log row.

Field

Description

currentPage

Current 1-based page.

totalCount

Total audit log entries.

pageSize

Items returned per page (for example 20).

hasNextPage / hasPreviousPage

Whether adjacent pages are available.

Header

Value

Description

Authorization

Bearer <access_token>

Client Access Token with tenant admin privileges (Platform panel).

is-tenant

true

Targets the tenant DB ("true", needs x-client-id).

x-client-id

Tenant (client) id. Required when is-tenant=true.

{ "success": true, "message": "Audit logs fetched successfully", "data": { "list": [ { "_id": "6a589c09c43829ebc51a80ed", "actorType": "client", "actorId": "6a589b96cfa34ab66e35b2a9", "actorName": "Mod Test", "action": "moderation.user-banned", "targetType": "user", "targetId": "6a589b96cfa34ab66e35b2ab", "details": { "userName": "Bad Actor" }, "createdAt": "2026-07-16T08:53:29.542Z", "updatedAt": "2026-07-16T08:53:29.542Z", "__v": 0 } ], "pagination": { "currentPage": 1, "totalCount": 4, "hasNextPage": false, "hasPreviousPage": false, "pageSize": 20 } }, "error": null }

Code

Reason

401 Unauthorized

Access Token is missing, invalid, or expired.

403 Forbidden

Tenant admin privileges required for Platform Moderation.

500 Internal Server Error

An unexpected error occurred while fetching audit logs.