> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verifow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit

> View immutable audit logs for compliance and regulatory inspection

## Overview

The Audit module provides a complete, immutable record of every significant action within your tenant. Every screening event, case update, rule change, and user management action is logged with full context -who did what, when, and from where.

## Common Workflows

**Regulatory inspection:** A CBN examiner requests audit evidence → An `AUDITOR` exports logs for a date range → The logs show every decision, case action, and rule trigger with timestamps and user attribution.

**Internal investigation:** A compliance manager suspects an unauthorized rule change → Queries audit logs for `resourceType: rules` and `action: UPDATE` → Identifies the user and reviews the exact change.

## Permissions

| Action          | Who Can Do It                                 |
| --------------- | --------------------------------------------- |
| View audit logs | `BANK_ADMIN`, `COMPLIANCE_OFFICER`, `AUDITOR` |

## Endpoints

| Method | Endpoint               | Description                   |
| ------ | ---------------------- | ----------------------------- |
| `GET`  | `/api/v1/audit/events` | Query audit logs with filters |
| `GET`  | `/api/v1/audit/verify` | Verify audit chain integrity  |

***

### List Audit Events

Retrieve audit trail entries with filtering and pagination. The list view excludes `beforeState` and `afterState` for performance.

**Query Parameters**

| Parameter      | Type      | Default | Description                                                             |
| -------------- | --------- | ------- | ----------------------------------------------------------------------- |
| `resourceType` | `string`  | -       | `transactions`, `cases`, `rules`, `users`, `reports`, `kyc`, `api_keys` |
| `action`       | `string`  | -       | `CREATE`, `UPDATE`, `DELETE`, `SCREEN`, `APPROVE`, `LOGIN`, `VERIFY`    |
| `actorEmail`   | `string`  | -       | Filter by acting user email                                             |
| `from`         | `string`  | -       | ISO 8601 start date                                                     |
| `to`           | `string`  | -       | ISO 8601 end date                                                       |
| `page`         | `integer` | `1`     | Page number                                                             |
| `limit`        | `integer` | `50`    | Items per page (max 500)                                                |

**Example Request**

```bash theme={null}
curl -X GET "/v1/audit/events?resourceType=cases&action=UPDATE&from=2026-05-01T00:00:00Z&to=2026-05-16T23:59:59Z&page=1&limit=20" \
  -H "Authorization: Bearer <access_token>"
```

**Example Response -200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "audit_001",
        "actorEmail": "officer@bank.com",
        "action": "UPDATE",
        "resourceType": "cases",
        "resourceId": "case_12345abcde",
        "ipAddress": "192.168.1.100",
        "createdAt": "2026-05-16T14:30:00Z",
        "hash": "a3f5c8e2d1b4..."
      },
      {
        "id": "audit_002",
        "actorEmail": "system",
        "action": "SCREEN",
        "resourceType": "transactions",
        "resourceId": "fae50ecb-d997-4700-bae7-49650678bb06",
        "ipAddress": null,
        "createdAt": "2026-05-16T14:15:00Z",
        "hash": "b7e9d2f1a8c3..."
      }
    ],
    "total": 145,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}
```

<Note>
  Audit logs are **immutable** and retained for **7 years** to meet CBN
  regulatory requirements. Each entry includes a SHA-256 hash forming a
  cryptographic chain.
</Note>

<Warning>
  For large exports, use `limit=500` and paginate through results. Do not
  attempt to retrieve more than 90 days of logs in a single request.
</Warning>

***

### Verify Audit Chain

Verify the cryptographic integrity of the audit trail. This checks that no logs have been tampered with.

**Example Request**

```bash theme={null}
curl -X GET /v1/audit/verify \
  -H "Authorization: Bearer <access_token>"
```

**Example Response -200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "isValid": true,
    "totalEvents": 145,
    "brokenAt": null
  }
}
```

**Example Response -Chain Broken**

```json theme={null}
{
  "success": true,
  "data": {
    "isValid": false,
    "totalEvents": 145,
    "brokenAt": "audit_003"
  }
}
```