Audit Logs API

Overview

Audit Logs provide comprehensive user activity tracking across the Merq platform. Every significant action—creating outlets, updating visits, managing users—is automatically logged with full context including who performed the action, what changed, and when it occurred.

Key characteristics:

• Workspace-scoped — Users can only view logs from their workspace
• Read-only API — Logs are created automatically by the system; no manual create/update/delete
• Compliance-ready — Maintains complete audit trail for regulatory requirements
• Immutable — Once created, logs cannot be modified or deleted

Use cases:

• Compliance & Auditing — Track who made changes to sensitive data, maintain audit trail for regulatory requirements
• Troubleshooting — Investigate data inconsistencies, trace when and where changes occurred
• Activity Monitoring — Monitor user activity patterns, track feature usage
• Security — Detect unauthorized access attempts, track privilege escalation

Data Model

AuditLog

Field	Type	Description
id	integer	Primary key
workspace_id	integer	FK to workspaces (scope)
actor_id	integer	FK to users (who performed action)
actor_name	string	User name snapshot at time of action
actor_role	string	User role value at time of action
entity_type	string	Entity type (e.g., “outlet”, “visit”, “user”)
entity_id	string	ID of affected entity (string supports UUID + uint)
entity_name	string	Entity name snapshot for display
action	string	Action type (e.g., “created”, “updated”, “deleted”)
old_values	JSON	Previous state before change (for updates)
new_values	JSON	New state after change (for creates/updates)
metadata	JSON	Additional context (IP address, user agent, etc.)
created_at	timestamp	When action occurred

Action Types

Action	Description
created	Entity was created
updated	Entity was modified
deleted	Entity was removed
approved	Submission/workflow item approved
rejected	Submission/workflow item rejected
assigned	Entity assigned to user/team
unassigned	Entity unassigned from user/team
login	User authentication
logout	User session termination

Entity Types

Entity	Constant
Users	user
Outlets	outlet
Teams	team
Projects	project
Principals	principal
Visits	visit
Submissions	submission
Forms	form
Products	product
Roles	role
Permissions	permission
Workspaces	workspace
Attendance	attendance
Sales Orders	sales_order

API Endpoints

Method	Endpoint	Permission	Description
GET	/office/v1/audit-logs	audit_log.view	List logs (paginated, filtered)
GET	/office/v1/audit-logs/:id	audit_log.view	Get log by ID

Note: Audit logs are read-only. Logs are created automatically by the system via handler-level middleware that captures all mutations.

Filter Parameters

List endpoint accepts these query parameters:

Param	Type	Description	Example
page	integer	Page number (default: 1)	1
limit	integer	Items per page (default: 50)	50
keyword	string	Search across text fields	carrefour
entity_type	string	Filter by entity type	outlet
entity_id	string	Filter by entity ID	123
action	string	Filter by action type	created
actor_id	integer	Filter by user ID	5
date_from	string (ISO 8601)	Start date range	2026-03-01T00:00:00Z
date_to	string (ISO 8601)	End date range	2026-03-05T23:59:59Z

All filters are optional. Multiple filters can be combined.

Example Requests & Responses

List with Filters

Request:

GET /office/v1/audit-logs?page=1&limit=20&entity_type=outlet&action=created&date_from=2026-03-01
Authorization: Bearer <token>

Response:

{
  "data": {
    "data": [
      {
        "id": 1001,
        "workspace_id": 1,
        "actor_id": 5,
        "actor_name": "John Doe",
        "actor_role": "admin",
        "entity_type": "outlet",
        "entity_id": "123",
        "entity_name": "Carrefour Sudirman",
        "action": "created",
        "old_values": null,
        "new_values": {
          "name": "Carrefour Sudirman",
          "address": "Jl. Sudirman No. 1",
          "channel_group_id": 1,
          "timezone": "WIB"
        },
        "metadata": {
          "ip": "192.168.1.100",
          "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."
        },
        "created_at": "2026-03-05T10:30:00Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "total_pages": 8
    }
  },
  "message": "Success",
  "code": "AUDIT_LOG_LIST"
}

Detail by ID

Request:

GET /office/v1/audit-logs/1001
Authorization: Bearer <token>

Response:

{
  "data": {
    "id": 1001,
    "workspace_id": 1,
    "actor_id": 5,
    "actor_name": "John Doe",
    "actor_role": "admin",
    "entity_type": "outlet",
    "entity_id": "123",
    "entity_name": "Carrefour Sudirman",
    "action": "created",
    "old_values": null,
    "new_values": {
      "name": "Carrefour Sudirman",
      "address": "Jl. Sudirman No. 1",
      "channel_group_id": 1,
      "channel_id": 2,
      "account_id": 3,
      "timezone": "WIB"
    },
    "metadata": {
      "ip": "192.168.1.100",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."
    },
    "created_at": "2026-03-05T10:30:00Z"
  },
  "message": "Success",
  "code": "AUDIT_LOG_FOUND"
}

Use Cases

Compliance & Auditing

Track who made changes to sensitive data and maintain audit trail for regulatory requirements:

# Get all outlet changes in date range
GET /office/v1/audit-logs?entity_type=outlet&date_from=2026-01-01&date_to=2026-01-31

Export logs for external audit by iterating through all pages.

Troubleshooting

Investigate data inconsistencies by tracing when and where changes occurred:

# Get all changes to specific outlet
GET /office/v1/audit-logs?entity_type=outlet&entity_id=123

Review old_values and new_values to see exactly what changed.

Activity Monitoring

Monitor user activity patterns and track feature usage:

# Get all actions by specific user
GET /office/v1/audit-logs?actor_id=5

Identify training needs by analyzing which features users access most.

Security

Detect unauthorized access attempts and track privilege escalation:

# Get all login/logout events
GET /office/v1/audit-logs?action=login
GET /office/v1/audit-logs?action=logout

Monitor data export activities and admin-level changes.

Workspace Scoping

All audit log queries are automatically filtered by workspace_id. This ensures:

• Data isolation — Users can only see logs from their own workspace
• Multi-tenant security — No cross-workspace data leakage
• Compliance boundaries — Audit trails stay within workspace jurisdiction

Exception: Super Admin users with multi-workspace access can view logs across all workspaces they have access to.

RBAC Permissions

Permission Keys

Permission	Description
audit_log.view	View audit logs (list + detail)

Permission constant: PermissionKeyAuditLogView

Access Levels

Role	Access
Super Admin	Full access to all workspace logs
Admin	Full access to workspace logs
Manager	Read-only access (team-scoped if restricted)
Regular User	No access (unless explicitly granted)

Permission Configuration

Permissions are configured in internal/domain/constant.go:

PermissionKeyAuditLogView string = "audit_log.view"

Routes are registered with middleware requiring this permission:

group.Use(middleware.RequirePermission(middleware.PermissionRequirement{
    Key:          domain.PermissionKeyAuditLogView,
    Platform:     domain.PlatformMerqAdmin,
    AccessLevels: []string{domain.AccessLevelFull, domain.AccessLevelView},
    AllowFullUp:  true,
}))

Automatic Logging

Audit logs are created automatically for all mutation operations across the platform:

Entity	Actions Logged
Outlets	created, updated, deleted
Visits	created, updated, deleted, assigned, unassigned
Users	created, updated, deleted, assigned, unassigned
Teams	created, updated, deleted
Submissions	created, approved, rejected
Roles	created, updated, deleted
Permissions	created, updated, deleted
Workspaces	created, updated, deleted
Attendance	created, updated, deleted
Sales Orders	created, updated, deleted
Principals	created, updated, deleted
Projects	created, updated, deleted
Products	created, updated, deleted
Forms	created, updated, deleted

Log Creation Process

1. Handler-level middleware captures all mutation requests (POST, PUT, DELETE)
2. Before transaction commit — Log entry created with old/new values
3. Metadata enrichment — IP address, user agent, request context added
4. Denormalization — Actor name, role, and entity name snapshots stored
5. Transaction commit — Log persisted atomically with the mutation

Metadata Captured

Field	Description
ip	Client IP address
user_agent	Browser/client user agent string
request_id	Unique request identifier (for tracing)
timestamp	Request timestamp

Related Topics

• Workspace Scoping — How workspace isolation works
• RBAC System — Permission and access control
• Settings & RBAC (User Guide) — Configuring user permissions
• Backend Architecture — Handler → Service → Repository pattern