Audit Logging

TrustGate maintains comprehensive audit logs of all actions taken on applicants, cases, and system configurations. These logs are essential for regulatory compliance, security monitoring, and incident investigation.

What's Logged

User Actions

Every action by users and API clients:

Event Type	Examples
Applicant Actions	View, create, update, delete applicants
Document Actions	Upload, view, download documents
Verification Actions	Initiate, review verifications
Case Actions	Create, assign, resolve cases
Screening Actions	Run screens, resolve hits
Settings Changes	Update configurations

System Events

Automated system actions:

Event Type	Examples
Workflow Triggers	Auto-approve, escalation rules
Scheduled Jobs	Periodic reviews, data retention
Integrations	Webhook deliveries, third-party calls
Security Events	Login attempts, permission changes

API Endpoints

The audit log API is mounted at /api/v1/audit-log. All endpoints require the read:settings permission.

Method	Path	Description
GET	/api/v1/audit-log	List audit logs with filtering and pagination
GET	/api/v1/audit-log/{entry_id}	Get a single audit log entry by ID
GET	/api/v1/audit-log/export/csv	Export audit logs as a CSV file
GET	/api/v1/audit-log/verify/chain	Verify integrity of the audit log hash chain
GET	/api/v1/audit-log/stats/summary	Get audit log statistics and breakdowns
GET	/api/v1/audit-log/filters/options	Get distinct values for filter dropdowns

Listing Audit Logs

Request

curl -X GET "https://api.bytrustgate.com/api/v1/audit-log?action=applicant.status_changed&start_date=2026-01-01T00:00:00Z&end_date=2026-01-31T23:59:59Z&actor_id=USER_UUID&limit=50&offset=0&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Description
resource_type	string	Filter by resource type (applicant, case, document, screening_hit)
resource_id	UUID	Filter by specific resource UUID
actor_id	UUID	Filter by the user who performed the action
action	string	Filter by action type (e.g., applicant.created, case.resolved)
start_date	datetime	Filter entries after this date (ISO 8601)
end_date	datetime	Filter entries before this date (ISO 8601)
search	string	Search in action name or user email
limit	int	Number of results to return (1-100, default: 50)
offset	int	Number of results to skip (default: 0)
sort_order	string	asc or desc (default: desc -- newest first)

Response

{
  "items": [
    {
      "id": 1234,
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "user_email": "analyst@company.com",
      "ip_address": "192.168.1.1",
      "action": "applicant.status_changed",
      "resource_type": "applicant",
      "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "old_values": { "status": "pending_review" },
      "new_values": { "status": "approved" },
      "extra_data": { "reason": "All checks passed" },
      "checksum": "a3f2b8c1d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678",
      "created_at": "2026-01-20T14:35:00Z"
    }
  ],
  "total": 45,
  "limit": 50,
  "offset": 0
}

Filtering by Applicant

To get audit logs for a specific applicant, use the resource_type and resource_id query parameters:

curl -X GET "https://api.bytrustgate.com/api/v1/audit-log?resource_type=applicant&resource_id=APPLICANT_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting a Single Entry

Request

curl -X GET "https://api.bytrustgate.com/api/v1/audit-log/{entry_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns the same fields as a list item, plus additional detail fields:

{
  "id": 1234,
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "user_email": "analyst@company.com",
  "ip_address": "192.168.1.1",
  "action": "applicant.status_changed",
  "resource_type": "applicant",
  "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "old_values": { "status": "pending_review" },
  "new_values": { "status": "approved" },
  "extra_data": {},
  "checksum": "a3f2b8c1d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678",
  "created_at": "2026-01-20T14:35:00Z",
  "user_agent": "Mozilla/5.0...",
  "resource_name": null
}

Action Types

Applicant Actions

Action	Description
applicant.created	New applicant created
applicant.viewed	Applicant record accessed
applicant.updated	Applicant data modified
applicant.deleted	Applicant record deleted
applicant.status_changed	Status updated
applicant.exported	Data exported

Document Actions

Action	Description
document.uploaded	Document uploaded
document.viewed	Document image accessed
document.downloaded	Document downloaded
document.deleted	Document removed
document.verified	Verification completed

Verification Actions

Action	Description
verification.initiated	Check started
verification.completed	Check finished
verification.manual_review	Manual override applied

Case Actions

Action	Description
case.created	Case opened
case.assigned	Case assigned to user
case.status_changed	Case status updated
case.note_added	Note added to case
case.resolved	Case resolved
case.closed	Case closed

Security Actions

Action	Description
auth.login	User login
auth.logout	User logout
auth.login_failed	Failed login attempt
auth.password_changed	Password updated
auth.mfa_enabled	MFA turned on
api_key.created	New API key created
api_key.revoked	API key revoked
permission.granted	Permission added
permission.revoked	Permission removed

Log Entry Fields

Each audit log entry contains:

Field	Type	Description
id	int	Sequential ID (BigInteger) for ordering
tenant_id	UUID	Tenant the entry belongs to
user_id	UUID	ID of the user who performed the action (null for system actions)
user_email	string	Email of the acting user
ip_address	string	IP address of the request (INET format)
action	string	Action type (e.g., applicant.created)
resource_type	string	Resource type (e.g., applicant, case, document)
resource_id	UUID	ID of the affected resource
old_values	JSON	Previous state of changed fields (null if not applicable)
new_values	JSON	New state of changed fields (null if not applicable)
extra_data	JSON	Additional context (reason, trigger, etc.)
checksum	string	SHA-256 chain hash for tamper evidence
created_at	datetime	Timestamp of the action

Exporting Audit Logs

Export audit logs as a CSV file. Supports the same filters as the list endpoint. Limited to 10,000 entries per export.

Request

curl -X GET "https://api.bytrustgate.com/api/v1/audit-log/export/csv?resource_type=applicant&start_date=2026-01-01T00:00:00Z&end_date=2026-01-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o audit_log_export.csv

Query Parameters

Parameter	Type	Description
resource_type	string	Filter by resource type
resource_id	UUID	Filter by specific resource UUID
actor_id	UUID	Filter by the user who performed the action
action	string	Filter by action type
start_date	datetime	Filter entries after this date
end_date	datetime	Filter entries before this date

Response

Returns a CSV file download with the following columns:

Column	Description
ID	Sequential audit log entry ID
Timestamp	ISO 8601 timestamp
User Email	Email of the acting user
User ID	UUID of the acting user
IP Address	Request IP address
Action	Action type
Resource Type	Type of affected resource
Resource ID	UUID of the affected resource
Old Values	Previous field values (JSON)
New Values	Updated field values (JSON)
Checksum	Chain hash for integrity verification

The response includes an X-Total-Count header with the number of exported entries.

Log Integrity

Tamper Protection

• Logs are append-only and immutable
• Each entry includes a SHA-256 checksum chained from the previous entry
• The chain hash covers: tenant ID, user ID, action, resource type, resource ID, old/new values, and timestamp
• Any modification to a log entry breaks the chain, making tampering detectable

Verify Chain Integrity

Recalculate checksums and compare them against stored values. Any mismatch indicates potential tampering.

curl -X GET "https://api.bytrustgate.com/api/v1/audit-log/verify/chain?limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameter	Type	Description
limit	int	Number of entries to verify (100-10,000, default: 1,000)

Response

{
  "is_valid": true,
  "total_entries": 125000,
  "entries_verified": 1000,
  "invalid_entry_ids": [],
  "verified_at": "2026-01-20T00:00:00Z"
}

If is_valid is false, the invalid_entry_ids array lists the IDs of entries whose checksums do not match the expected chain hash.

Audit Statistics

Get summary statistics about audit log activity.

Request

curl -X GET "https://api.bytrustgate.com/api/v1/audit-log/stats/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "total_entries": 125000,
  "entries_today": 342,
  "entries_this_week": 2150,
  "entries_this_month": 8420,
  "actions_breakdown": {
    "applicant.viewed": 1200,
    "applicant.created": 450,
    "document.uploaded": 380,
    "case.resolved": 120
  },
  "resource_types_breakdown": {
    "applicant": 2800,
    "document": 1200,
    "case": 500
  },
  "top_users": [
    {
      "email": "analyst@company.com",
      "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "count": 540
    }
  ]
}

Breakdowns cover the last 30 days. Top users are limited to 5 entries.

Filter Options

Get distinct values for building filter dropdowns in the UI.

Request

curl -X GET "https://api.bytrustgate.com/api/v1/audit-log/filters/options" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "actions": [
    "applicant.created",
    "applicant.viewed",
    "case.resolved",
    "document.uploaded"
  ],
  "resource_types": [
    "applicant",
    "case",
    "document"
  ],
  "users": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "email": "analyst@company.com"
    }
  ]
}

Log Retention

Log Type	Retention
Security events	7 years
Applicant actions	5 years
System events	2 years
Debug logs	90 days

---

Next Steps

• Data Retention - Configure retention policies
• GDPR Compliance - Privacy requirements
• Evidence Export - Export compliance evidence