Audit Rail

Audit Rail

Audit trails, compliance logging, and activity tracking.

Overview

The Audit Rail provides endpoints for comprehensive audit logging, activity tracking, and compliance reporting.

Base URL

/api/v1/audit

Endpoints

List Audit Logs

GET /api/v1/audit/logs

List audit log entries.

Query Parameters:

Parameter	Type	Description
action	string	Filter by action type
entityType	string	Filter by entity type
entityId	string	Filter by entity ID
actorId	string	Filter by actor
from	string	Start timestamp
to	string	End timestamp
page	number	Page number
perPage	number	Items per page

Response:

{
  "data": [
    {
      "logId": "log_abc123",
      "timestamp": "2025-01-15T10:00:00Z",
      "action": "CONTRACT_CREATED",
      "entityType": "CONTRACT",
      "entityId": "con_xyz",
      "actor": {
        "type": "USER",
        "id": "user_123",
        "email": "user@example.com"
      },
      "metadata": {
        "contractType": "MURABAHA",
        "amount": "500000.00"
      },
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0...",
      "traceId": "trace_abc"
    }
  ],
  "pagination": {
    "page": 1,
    "total": 15000
  }
}

Get Audit Log

GET /api/v1/audit/logs/:logId

Get single audit log entry with full details.

Get Entity History

GET /api/v1/audit/entities/:entityType/:entityId/history

Get change history for an entity.

Response:

{
  "data": [
    {
      "timestamp": "2025-01-15T10:00:00Z",
      "action": "CREATED",
      "actor": "user_123",
      "changes": null
    },
    {
      "timestamp": "2025-01-15T11:00:00Z",
      "action": "UPDATED",
      "actor": "user_456",
      "changes": {
        "status": {
          "from": "DRAFT",
          "to": "PENDING_APPROVAL"
        }
      }
    }
  ]
}

Export Audit Logs

POST /api/v1/audit/export

Export audit logs for compliance.

Request Body:

{
  "format": "CSV",
  "filter": {
    "from": "2025-01-01T00:00:00Z",
    "to": "2025-01-31T23:59:59Z",
    "entityType": "CONTRACT"
  },
  "destination": {
    "type": "EMAIL",
    "email": "compliance@example.com"
  }
}

Get Access Logs

GET /api/v1/audit/access-logs

Get data access logs (who accessed what).

Query Parameters:

Parameter	Type	Description
resourceType	string	Filter by resource type
accessType	string	READ, WRITE, DELETE
actorId	string	Filter by actor

Get Login History

GET /api/v1/audit/login-history

Get authentication history.

Query Parameters:

Parameter	Type	Description
userId	string	Filter by user
status	string	SUCCESS, FAILED
from	string	Start date

Response:

{
  "data": [
    {
      "timestamp": "2025-01-15T10:00:00Z",
      "userId": "user_123",
      "status": "SUCCESS",
      "method": "PASSWORD",
      "ipAddress": "192.168.1.100",
      "location": "Riyadh, SA",
      "device": "Chrome on Windows"
    }
  ]
}

Create Audit Report

POST /api/v1/audit/reports

Generate compliance audit report.

Request Body:

{
  "reportType": "COMPLIANCE_SUMMARY",
  "period": {
    "from": "2025-01-01",
    "to": "2025-01-31"
  },
  "includeStats": true,
  "format": "PDF"
}

Get Audit Statistics

GET /api/v1/audit/stats

Get audit statistics.

Response:

{
  "data": {
    "period": "2025-01",
    "totalEvents": 150000,
    "byAction": {
      "CREATE": 25000,
      "UPDATE": 80000,
      "DELETE": 5000,
      "READ": 40000
    },
    "byEntityType": {
      "CONTRACT": 30000,
      "CUSTOMER": 45000,
      "PAYMENT": 50000
    },
    "uniqueActors": 250,
    "failedLogins": 150
  }
}

Action Types

Action	Description
CREATE	Entity created
UPDATE	Entity updated
DELETE	Entity deleted
READ	Entity accessed
EXPORT	Data exported
LOGIN	User logged in
LOGOUT	User logged out
APPROVE	Approval action
REJECT	Rejection action

Actor Types

Type	Description
USER	Human user
API_KEY	API key access
SYSTEM	System process
WEBHOOK	Webhook trigger

Events

Event	Description
audit.log.created	Audit log created
audit.export.completed	Export completed
audit.suspicious.detected	Suspicious activity

See Also

• Compliance Rail - Compliance checks
• Observability Rail - Platform monitoring