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

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

Viewing Audit Logs

Get Applicant Audit Trail

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

Response

{
  "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
  "audit_entries": [
    {
      "id": "audit_001",
      "timestamp": "2025-01-20T14:30:00Z",
      "action": "applicant.viewed",
      "actor": {
        "type": "user",
        "id": "user_123",
        "email": "analyst@company.com",
        "ip_address": "192.168.1.1"
      },
      "details": {
        "fields_viewed": ["personal_info", "documents"]
      }
    },
    {
      "id": "audit_002",
      "timestamp": "2025-01-20T14:35:00Z",
      "action": "applicant.status_changed",
      "actor": {
        "type": "user",
        "id": "user_123",
        "email": "analyst@company.com",
        "ip_address": "192.168.1.1"
      },
      "details": {
        "previous_status": "pending_review",
        "new_status": "approved",
        "reason": "All checks passed"
      }
    },
    {
      "id": "audit_003",
      "timestamp": "2025-01-20T14:40:00Z",
      "action": "document.downloaded",
      "actor": {
        "type": "user",
        "id": "user_456",
        "email": "manager@company.com",
        "ip_address": "192.168.1.2"
      },
      "details": {
        "document_id": "doc_789",
        "document_type": "passport"
      }
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "per_page": 50
  }
}

Query Audit Logs

curl -X GET "https://api.bytrustgate.com/v1/audit-logs?action=applicant.status_changed&from=2025-01-01&to=2025-01-31&actor_id=user_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Description
`action`	Filter by action type
`actor_id`	Filter by user or API key
`actor_type`	Filter by actor type (user, api_key, system)
`resource_type`	Filter by resource (applicant, case, document)
`resource_id`	Filter by specific resource ID
`from`	Start date (ISO 8601)
`to`	End date (ISO 8601)

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 Details

Actor Information

Each log entry includes:

{
  "actor": {
    "type": "user",
    "id": "user_123",
    "email": "analyst@company.com",
    "name": "John Analyst",
    "role": "compliance_analyst",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "session_id": "sess_abc123"
  }
}

API Key Actions

{
  "actor": {
    "type": "api_key",
    "id": "key_xyz789",
    "name": "Production API Key",
    "ip_address": "10.0.0.1",
    "environment": "production"
  }
}

System Actions

{
  "actor": {
    "type": "system",
    "process": "workflow_engine",
    "trigger": "rule_auto_approve_low_risk"
  }
}

Log Export

Export Audit Logs

curl -X POST https://api.bytrustgate.com/v1/audit-logs/export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "from": "2025-01-01",
    "to": "2025-01-31",
    "filters": {
      "action": "applicant.*"
    },
    "delivery": {
      "method": "email",
      "email": "compliance@company.com"
    }
  }'

Export Formats

Format	Use Case
`csv`	Spreadsheet analysis
`json`	System integration
`pdf`	Regulatory submission

Real-Time Log Streaming

Configure Log Streaming

Stream logs to your SIEM or monitoring system:

curl -X POST https://api.bytrustgate.com/v1/audit-logs/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "webhook",
    "url": "https://your-siem.com/ingest",
    "events": ["auth.*", "applicant.deleted", "settings.*"],
    "format": "json",
    "batch_size": 100,
    "flush_interval_seconds": 60
  }'

Supported Destinations

Destination	Description
`webhook`	HTTPS endpoint
`s3`	S3-compatible storage
`cloudwatch`	Cloud logging service
`datadog`	Datadog logs
`splunk`	Splunk HEC

Log Retention

Default Retention

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

Configure Retention

curl -X PUT https://api.bytrustgate.com/v1/settings/audit-log-retention \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "security_events_years": 7,
    "applicant_actions_years": 5,
    "system_events_years": 2
  }'

Log Integrity

Tamper Protection

Logs are append-only
Cryptographic hash chains ensure integrity
Logs cannot be modified or deleted
Regular integrity verification

Verify Log Integrity

curl -X GET "https://api.bytrustgate.com/v1/audit-logs/verify?from=2025-01-01&to=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "verification": {
    "status": "verified",
    "period": {
      "from": "2025-01-01",
      "to": "2025-01-31"
    },
    "entries_verified": 125000,
    "hash_chain_valid": true,
    "last_verified": "2025-01-20T00:00:00Z"
  }
}

Next Steps

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

What's Logged​

User Actions​

System Events​

Viewing Audit Logs​

Get Applicant Audit Trail​

Response​

Query Audit Logs​

Query Parameters​

Action Types​

Applicant Actions​

Document Actions​

Verification Actions​

Case Actions​

Security Actions​

Log Details​

Actor Information​

API Key Actions​

System Actions​

Log Export​

Export Audit Logs​

Export Formats​

Real-Time Log Streaming​

Configure Log Streaming​

Supported Destinations​

Log Retention​

Default Retention​

Configure Retention​

Log Integrity​

Tamper Protection​

Verify Log Integrity​

Next Steps​