Skip to main content

​
GET /api/audit-logs

Retrieves a paginated list of audit logs that capture all system activities. Each log entry records user actions, including authentication events, role assignments, permission changes, and other security-relevant operations.

​
Authentication

This endpoint requires admin privileges. Include a valid JWT token in the Authorization header. 
Authorization: Bearer <token>
Required Role: ADMIN

​
Query Parameters

​
module
string
Filter logs by module name. Common modules include:
  • AUTH - Authentication events
  • USERS - User management operations
  • ROLES - Role assignment and modifications
  • PERMISSIONS - Permission changes
  • AUDIT - Audit system events
​
date
string
Filter logs by date in ISO 8601 format (YYYY-MM-DD). Returns all logs created on the specified date.Example: 2026-03-04
​
page
integer
default:"0"
Page number for pagination (zero-based index).
​
size
integer
default:"10"
Number of records per page.
​
sortField
string
default:"timestamp"
Field to sort by. Available options:
  • timestamp - Log creation time
  • module - Module name
  • action - Action type
  • status - Operation status
  • userId - User identifier
​
sortDir
string
default:"desc"
Sort direction. Options: asc (ascending) or desc (descending).

​
Response

​
content
array
Array of activity log entries.
​
id
string
Unique identifier for the log entry (UUID format).
​
userId
string
Identifier of the user who performed the action. May be null for system-initiated events.
​
module
string
The system module where the action occurred (e.g., AUTH, USERS, ROLES, PERMISSIONS).
​
action
string
Description of the action performed (e.g., LOGIN, CREATE_USER, ASSIGN_ROLE, UPDATE_PERMISSION).
​
details
string
Additional context and arguments for the action. May contain JSON-formatted data with relevant parameters.
​
ipAddress
string
IP address from which the action was initiated.
​
status
string
Outcome of the operation. Common values:
  • SUCCESS - Operation completed successfully
  • FAILURE - Operation failed
  • ERROR - System error occurred
​
timestamp
string
ISO 8601 timestamp when the action occurred (e.g., 2026-03-04T10:30:45.123Z).
​
pageNumber
integer
Current page number (zero-based).
​
pageSize
integer
Number of items per page.
​
totalElements
integer
Total number of log entries matching the filter criteria.
​
totalPages
integer
Total number of pages available.
​
isLast
boolean
Indicates whether this is the last page of results.

​
Examples

​
Get all audit logs (paginated)

curl -X GET "https://api.example.com/api/audit-logs?page=0&size=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Filter by module

curl -X GET "https://api.example.com/api/audit-logs?module=AUTH&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Filter by date

curl -X GET "https://api.example.com/api/audit-logs?date=2026-03-04&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Filter by module and date

curl -X GET "https://api.example.com/api/audit-logs?module=USERS&date=2026-03-04&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Sort by user ID in ascending order

curl -X GET "https://api.example.com/api/audit-logs?sortField=userId&sortDir=asc&page=0&size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Response Example

{
  "content": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "userId": "[email protected]",
      "module": "AUTH",
      "action": "LOGIN",
      "details": "{\"method\": \"credentials\", \"success\": true}",
      "ipAddress": "192.168.1.100",
      "status": "SUCCESS",
      "timestamp": "2026-03-04T10:30:45.123Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-2345-678901bcdef0",
      "userId": "[email protected]",
      "module": "USERS",
      "action": "CREATE_USER",
      "details": "{\"newUserId\": \"[email protected]\", \"roles\": [\"USER\"]}",
      "ipAddress": "192.168.1.100",
      "status": "SUCCESS",
      "timestamp": "2026-03-04T10:32:15.456Z"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-3456-789012cdef01",
      "userId": "[email protected]",
      "module": "ROLES",
      "action": "ASSIGN_ROLE",
      "details": "{\"userId\": \"[email protected]\", \"role\": \"MANAGER\"}",
      "ipAddress": "192.168.1.100",
      "status": "SUCCESS",
      "timestamp": "2026-03-04T10:33:20.789Z"
    }
  ],
  "pageNumber": 0,
  "pageSize": 10,
  "totalElements": 3,
  "totalPages": 1,
  "isLast": true
}

​
Error Responses

​
403 Forbidden

Returned when the authenticated user does not have admin privileges. 
{
  "status": 403,
  "message": "Access denied. Admin role required.",
  "timestamp": "2026-03-04T10:30:45.123Z"
}

​
What Data is Captured

The audit logging system automatically captures comprehensive information about system activities:
  • User Identity: The userId field identifies who performed the action
  • IP Address: The source IP address from which the request originated
  • Action Type: A descriptive action name indicating what operation was performed
  • Module Context: The system module or component where the action occurred
  • Arguments: The details field contains JSON-formatted data with relevant parameters, input values, and context
  • Outcome: The status field indicates whether the operation succeeded or failed
  • Timestamp: Precise date and time when the action was executed (automatically set by the system)
This comprehensive audit trail enables security monitoring, compliance reporting, troubleshooting, and forensic analysis of system activities.

Build docs developers (and LLMs) love

Get started for freeTalk to us