Audit Endpoints
API reference for security audit log retrieval — paginated, filterable audit trail for admin oversight.
Audit Endpoints
View the security audit trail. All authentication events (login, logout, token refresh, security events) are logged automatically and can be queried through this endpoint.
Base Path: /api/v1/audit
All endpoints require authentication and ROLE_ADMIN authorization.
Get Audit Logs
GET /api/v1/auditReturns a paginated list of audit log entries, sorted by newest first. Supports filtering by action type.
Authorization: ROLE_ADMIN only
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
action | String | — | Filter by action type: LOGIN, LOGOUT, TOKEN_REFRESH, TOKEN_REVOKED, SECURITY_EVENT |
limit | Number | 100 | Results per page (max) |
page | Number | 1 | Page number |
Success Response — 200 OK
{
"logs": [
{
"_id": "...",
"action": "LOGIN",
"status": "SUCCESS",
"userId": {
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com",
"rollNumber": "CS2024001",
"role": "ROLE_STUDENT"
},
"ipAddress": "192.168.1.1",
"userAgent": "Mozilla/5.0 ...",
"details": null,
"createdAt": "2026-07-06T21:00:00.000Z"
}
],
"pagination": {
"total": 245,
"page": 1,
"limit": 100,
"totalPages": 3
}
}Audit Action Types
| Action | Description |
|---|---|
LOGIN | User login attempt (success or failure) |
LOGOUT | User logout |
TOKEN_REFRESH | Access token refresh via refresh token |
TOKEN_REVOKED | Token manually revoked |
SECURITY_EVENT | System security events (e.g., cron job failures) |
Audit Status Values
| Status | Description |
|---|---|
SUCCESS | The action completed successfully |
FAILURE | The action failed (e.g., invalid password, expired token) |
Route Summary
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /audit | Admin only | Get paginated audit logs |
Note: Audit logs are write-only from the application's perspective. They are created automatically by the
auditLoggerutility and cannot be modified or deleted through the API.