Admin Audit Log — Append-Only Record of Admin Actions

The Audit Log provides a tamper-proof, chronological record of every significant action taken by admin and super_admin accounts on the platform. Each entry captures who performed an action, what was done, which resource was affected, and when it happened. Use the audit log to investigate incidents, satisfy compliance requirements, and monitor admin behaviour over time.

Audit log entries are append-only. They cannot be modified, soft-deleted, or hard-deleted through any API endpoint. The log is a permanent and authoritative record of admin activity.

This endpoint requires SUPER_ADMIN role. Requests from ADMIN-level sessions will receive a 403 Forbidden response.

Authentication

The audit log endpoint requires:

A valid session cookie (obtained via POST /auth/login)
SUPER_ADMIN role (ADMIN-level access is insufficient)

No write operations are available on this endpoint — it is read-only.

Query the Audit Log

Retrieve a paginated, filterable view of the audit trail. Filter by the admin who performed the action, the action type, the resource type, a specific resource, or a date range to narrow down the log to the entries you need. GET /admin/audit

integer

default:"1"

Page number (1-based).

integer

default:"20"

Items per page. Minimum 1, maximum 100.

string

Filter by the public ID of the admin who performed the action (e.g. usr_01H). Max 50 characters.

string

Filter by action name prefix. For example, passing user. returns all entries whose action starts with user.. Max 100 characters.

string

Filter by the type of resource that was affected (e.g. user, order, product, review). Max 50 characters.

string

Filter by the public ID of a specific resource to see all audit history for that record (e.g. usr_01H, ord_01H). Max 50 characters.

string

ISO 8601 datetime with UTC offset. Return entries created at or after this time.

string

ISO 8601 datetime with UTC offset. Return entries created at or before this time.

string

default:"-created_at"

Sort by creation time. Use created_at for oldest-first or -created_at for newest-first.

curl -X GET "https://api.example.com/api/v1/admin/audit?sort=-created_at&limit=50" \
  -H "Cookie: session=<your-super-admin-session>"

curl -X GET "https://api.example.com/api/v1/admin/audit?actor=usr_01H&sort=-created_at" \
  -H "Cookie: session=<your-super-admin-session>"

curl -X GET "https://api.example.com/api/v1/admin/audit?entity_public_id=ord_01H" \
  -H "Cookie: session=<your-super-admin-session>"

curl -X GET "https://api.example.com/api/v1/admin/audit?date_from=2024-06-01T00:00:00.000Z&date_to=2024-06-30T23:59:59.000Z" \
  -H "Cookie: session=<your-super-admin-session>"

Response Structure

200 OK

boolean

Always true on a successful response.

array

Array of audit log entries.

Show Audit entry fields

string

Unique identifier for this audit entry (prefix: aud_). Use this to reference a specific log entry.

string

The public ID of the admin or super_admin who performed the action (e.g. usr_01H).

string

A dot-separated string describing what was done (e.g. user.suspend, order.status.update, review.delete). Max 100 characters.

string

The type of resource that was targeted by this action (e.g. user, order, product, review, coupon). Max 50 characters.

string

The public ID of the specific resource that was affected (e.g. usr_01H, ord_01H). Max 50 characters.

string

ISO 8601 UTC timestamp recording exactly when the action was performed.

object

Standard pagination metadata.

Show Pagination fields

integer

Current page number (1-based).

integer

Items per page used in this request.

integer

Total number of audit entries matching the applied filters.

integer

Total number of pages given the current limit.

boolean

true if a subsequent page exists.

boolean

true if a previous page exists.

Example response:

{
  "success": true,
  "data": [
    {
      "public_id": "aud_01H",
      "actor": "usr_01H",
      "action": "user.suspend",
      "entity_type": "user",
      "entity_public_id": "usr_02H",
      "created_at": "2024-06-12T14:35:22.000Z"
    },
    {
      "public_id": "aud_02H",
      "actor": "usr_01H",
      "action": "order.status.update",
      "entity_type": "order",
      "entity_public_id": "ord_01H",
      "created_at": "2024-06-12T13:10:05.000Z"
    },
    {
      "public_id": "aud_03H",
      "actor": "usr_03H",
      "action": "review.delete",
      "entity_type": "review",
      "entity_public_id": "rev_01H",
      "created_at": "2024-06-11T09:45:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Error Responses

Status Code	Meaning
`200`	Audit entries returned successfully.
`400`	Invalid query parameters (e.g. malformed date, limit out of range).
`401`	Missing or expired session.
`403`	Insufficient role — SUPER_ADMIN required.

Usage Patterns

Investigate a specific admin's actions

To audit everything an admin did during a time window, combine the actor filter with date_from and date_to:

curl -X GET "https://api.example.com/api/v1/admin/audit?actor=usr_01H&date_from=2024-06-01T00:00:00.000Z&date_to=2024-06-30T23:59:59.000Z" \
  -H "Cookie: session=<your-super-admin-session>"

Trace all changes to a resource

Pass entity_public_id to see the complete modification history of a specific order, product, user, or any other entity:

curl -X GET "https://api.example.com/api/v1/admin/audit?entity_public_id=usr_01H&sort=created_at" \
  -H "Cookie: session=<your-super-admin-session>"

Filter by action type

Use the action prefix filter to find all suspension events, for example:

curl -X GET "https://api.example.com/api/v1/admin/audit?action=user.suspend" \
  -H "Cookie: session=<your-super-admin-session>"

Export a compliance report

Page through the entire log for a fiscal period using date bounds and multiple pages:

curl -X GET "https://api.example.com/api/v1/admin/audit?date_from=2024-01-01T00:00:00.000Z&date_to=2024-03-31T23:59:59.000Z&limit=100&page=1&sort=created_at" \
  -H "Cookie: session=<your-super-admin-session>"

Increment page until meta.hasNext is false to retrieve all entries.

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Audit Log — Append-Only Record of Admin Actions

Authentication

Query the Audit Log

Response Structure

Error Responses

Usage Patterns

​Authentication

​Query the Audit Log

​Response Structure

​Error Responses

​Usage Patterns

Authentication

Query the Audit Log

Response Structure

Error Responses

Usage Patterns