List Audit Logs

Retrieve paginated audit logs for the organization with optional filtering by event type, actor, and time range.

Request

GET /audit-logs

Authentication

Requires an Admin Bearer JWT token or an API Key with the audit:read scope.

Authorization: Bearer <access_token>

or

X-API-Key: egk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Query Parameters

Parameter	Type	Required	Default	Description
eventType	string	No	-	Filter by event type (e.g., USER_LOGIN, SESSION_START)
actorEmail	string	No	-	Filter by email of the user who performed the action
from	string	No	-	ISO timestamp for start of time range
to	string	No	-	ISO timestamp for end of time range
page	integer	No	0	Page number (zero-indexed)
size	integer	No	20	Number of records per page

Event Types

Common event types include:

• USER_LOGIN
• USER_REGISTER
• USER_LOGOUT
• SESSION_START
• SESSION_STOP
• SESSION_EXTEND
• RESOURCE_CREATE
• RESOURCE_UPDATE
• RESOURCE_DELETE
• CREDENTIAL_CREATE
• CREDENTIAL_DELETE
• ROLE_CREATE
• ROLE_UPDATE
• ROLE_DELETE
• STATIC_IP_RULE_CREATE
• STATIC_IP_RULE_DELETE
• API_KEY_CREATE
• API_KEY_REVOKE
• ORGANIZATION_SETTINGS_UPDATE
• SUBSCRIPTION_CREATED
• SUBSCRIPTION_CANCELLED

Response

Returns a paginated list of audit log entries.

Success Response

Status Code: 200 OK

Response Body:

{
  "content": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "eventType": "SESSION_START",
      "actorEmail": "[email protected]",
      "actorType": "USER",
      "resourceType": "SESSION",
      "resourceId": "660e8400-e29b-41d4-a716-446655440001",
      "resourceName": "Production DB Session",
      "result": "SUCCESS",
      "ipAddress": "203.0.113.42",
      "errorMessage": null,
      "details": {
        "durationHours": 2,
        "resourceCount": 3
      },
      "organizationName": "Example Corp",
      "createdAt": "2026-02-18T10:30:00Z"
    }
  ],
  "totalElements": 150,
  "totalPages": 8,
  "number": 0,
  "size": 20
}

Response Fields

Field	Type	Description
content	array	Array of audit log entries for the current page
content[].id	UUID	Unique identifier for the audit log entry
content[].eventType	string	Type of event that occurred
content[].actorEmail	string	Email of the user or system that performed the action
content[].actorType	string	Type of actor: USER, SYSTEM, or API_KEY
content[].resourceType	string	Type of resource affected (e.g., SESSION, RESOURCE, CREDENTIAL)
content[].resourceId	UUID	Unique identifier of the affected resource
content[].resourceName	string	Human-readable name of the affected resource
content[].result	string	Result of the action: SUCCESS or FAILURE
content[].ipAddress	string	IP address from which the action was performed
content[].errorMessage	string	Error description if result is FAILURE
content[].details	object	Additional event-specific details (JSON object)
content[].organizationName	string	Name of the organization
content[].createdAt	string	ISO timestamp when the event occurred
totalElements	integer	Total number of audit log entries matching the filter
totalPages	integer	Total number of pages
number	integer	Current page number (zero-indexed)
size	integer	Number of entries per page

Errors

Status Code	Error Code	Description
400	BAD_REQUEST	Invalid query parameters (e.g., invalid date format)
401	UNAUTHORIZED	Missing or invalid JWT token or API key
403	FORBIDDEN	User does not have admin privileges or API key lacks audit:read scope

Example

Request with Bearer Token

curl -X GET "https://api.entryguard.io/api/v1/audit-logs?eventType=SESSION_START&page=0&size=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Request with API Key

curl -X GET "https://api.entryguard.io/api/v1/audit-logs?from=2026-02-01T00:00:00Z&to=2026-02-18T23:59:59Z&page=0&size=50" \
  -H "X-API-Key: egk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"

Response

{
  "content": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "eventType": "SESSION_START",
      "actorEmail": "[email protected]",
      "actorType": "USER",
      "resourceType": "SESSION",
      "resourceId": "660e8400-e29b-41d4-a716-446655440001",
      "resourceName": "Production DB Session",
      "result": "SUCCESS",
      "ipAddress": "203.0.113.42",
      "errorMessage": null,
      "details": {
        "durationHours": 2,
        "resourceCount": 3
      },
      "organizationName": "Example Corp",
      "createdAt": "2026-02-18T10:30:00Z"
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "eventType": "SESSION_STOP",
      "actorEmail": "[email protected]",
      "actorType": "USER",
      "resourceType": "SESSION",
      "resourceId": "660e8400-e29b-41d4-a716-446655440001",
      "resourceName": "Production DB Session",
      "result": "SUCCESS",
      "ipAddress": "203.0.113.42",
      "errorMessage": null,
      "details": {},
      "organizationName": "Example Corp",
      "createdAt": "2026-02-18T12:15:00Z"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

Notes

• Audit logs are immutable and cannot be modified or deleted.
• Logs are retained according to your organization's data retention policy.
• The details field contains event-specific contextual information that varies by event type.
• Use pagination for large result sets to avoid performance issues.