Audit Trail: Track Every Action in Your Organization

Every time someone in your organization creates a loan, records a deposit, changes a setting, deletes an expense, or modifies a role, Agatabo writes a permanent, tamper-proof entry to the audit trail. These logs tell you who performed the action, what resource was affected, when it happened, and whether it succeeded or failed. No user can delete or alter audit entries — the trail is immutable by design, making it your strongest tool for compliance reporting, security investigations, and staff accountability.

Accessing audit logs requires the audit_logs:read permission with ANY scope. Read-only operations (viewing pages, running reports, searching records) are intentionally excluded from the audit trail to keep it focused on meaningful state changes.

What the Audit Trail Records

Agatabo logs all CREATE, UPDATE, DELETE, and CONFIGURE operations automatically. You do not need to configure anything — logging is always on.

Logged ✅	Not Logged ❌
Creating a new loan	Viewing a loan
Recording a deposit or withdrawal	Running a report
Modifying loan terms	Searching for members
Approving a loan application	Browsing the dashboard
Recording an expense	Viewing the trial balance
Adding or disposing an asset	Downloading an export
Changing organization settings
Assigning or revoking roles
Sending an invitation
Deleting an expense
Deactivating a member

Access the Audit Logs

Navigate to Settings → Audit Logs in the Agatabo interface, or query the API directly:

GET /audit-logs?page=1&limit=20&sortBy=createdAt&sortOrder=desc
Headers:
  Authorization: Bearer {accessToken}
  x-organization-id: {organizationId}

Query Parameters

Use these parameters to filter, sort, and paginate the log.

Parameter	Type	Default	Description
`actorType`	Enum	—	Filter by who acted: `organization_admin` or `organization_user`
`resourceType`	Enum	—	Filter by the type of resource affected (see table below)
`actionType`	Enum	—	Filter by action: `CREATE`, `UPDATE`, `DELETE`, `DEFAULT`, or `CONFIGURE`
`startDate`	ISO date string	—	Return only logs on or after this date
`endDate`	ISO date string	—	Return only logs on or before this date
`search`	String	—	Case-insensitive search across `actorName` and `description` fields
`page`	Number	`1`	Page number for pagination
`limit`	Number	`20`	Records per page (max recommended: 100)
`sortBy`	Enum	`createdAt`	Sort field: `createdAt`, `actorName`, `actionType`, or `resourceType`
`sortOrder`	Enum	`desc`	Sort direction: `asc` or `desc`

Resource Types

Value	What It Covers
`ORGANIZATION`	Organization settings and configuration
`ORGANIZATION_USER`	Members and user accounts
`SAVINGS`	Deposits and withdrawals
`LOAN`	Loan creation and modifications
`LOAN_INSTALLMENT`	Changes to loan installment schedules
`LOAN_PAYMENT`	Loan payment recording
`EXPENSE`	Expense entries
`ASSET`	Fixed asset management
`TRANSACTION`	General ledger transactions
`UPLOAD`	File uploads
`CONFIG`	System configuration changes

Response Structure

{
  "message": "Audit logs retrieved successfully",
  "data": [
    {
      "id": "log-123",
      "actorName": "John Doe",
      "actorType": "organization_admin",
      "actionType": "CREATE",
      "resourceType": "LOAN",
      "description": "Created loan for Jane Smith - 500,000 RWF",
      "metadata": {
        "status": "success",
        "memberName": "Jane Smith",
        "amount": 500000,
        "term": 12,
        "interestRate": 10
      },
      "createdAt": "2026-06-10T14:32:15.000Z"
    },
    {
      "id": "log-124",
      "actorName": "Sarah Lee",
      "actorType": "organization_user",
      "actionType": "CREATE",
      "resourceType": "SAVINGS",
      "description": "Recorded deposit for Peter Kalisa - 20,000 RWF",
      "metadata": {
        "status": "success",
        "memberName": "Peter Kalisa",
        "amount": 20000,
        "paymentMethod": "Cash"
      },
      "createdAt": "2026-06-10T09:15:22.000Z"
    },
    {
      "id": "log-125",
      "actorName": "Mark Johnson",
      "actorType": "organization_admin",
      "actionType": "DELETE",
      "resourceType": "EXPENSE",
      "description": "Attempted to delete expense",
      "metadata": {
        "status": "failed"
      },
      "createdAt": "2026-06-10T16:45:33.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 523,
    "totalPages": 27,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Response Fields

Field	Type	Description
`id`	String	Unique identifier for this audit log entry
`actorName`	String	Full name of the person who performed the action
`actorType`	Enum	`organization_admin` or `organization_user`
`actionType`	Enum	`CREATE`, `UPDATE`, `DELETE`, `DEFAULT`, or `CONFIGURE`
`resourceType`	Enum	The type of resource that was acted upon
`description`	String	A human-readable summary of the action taken
`metadata.status`	String	`success` (HTTP 2xx) or `failed` (HTTP 4xx/5xx)
`metadata`	Object	Additional context: amounts, member names, rates, etc.
`createdAt`	ISO datetime	Timestamp of when the action occurred

Pagination Fields

Field	Type	Description
`totalCount`	Number	Total log entries matching your filters
`totalPages`	Number	Total number of pages
`hasNextPage`	Boolean	`true` if more pages follow the current one
`hasPreviousPage`	Boolean	`true` if pages precede the current one

Filtering Examples

By Actor Type — Admins Only

GET /audit-logs?actorType=organization_admin

Use this to review actions taken by users with elevated privileges.

By Resource Type — Loan Activity

GET /audit-logs?resourceType=LOAN

Narrow the view to all loan-related events in the organization.

By Action — Deletions Only

GET /audit-logs?actionType=DELETE

Deletions are the most sensitive class of action. Review them regularly to catch accidental or unauthorized removals.

By Date Range — A Specific Month

GET /audit-logs?startDate=2026-06-01&endDate=2026-06-30

Keyword Search — A Specific Person

GET /audit-logs?search=Jane%20Smith

The search parameter matches against both actorName (who acted) and description (what they did), case-insensitively.

Combined — Admin Deletions Last Month

GET /audit-logs?actorType=organization_admin&actionType=DELETE&startDate=2026-06-01&endDate=2026-06-30

Combining parameters narrows results precisely. Use this pattern for targeted security reviews.

Detecting Failed Operations

Agatabo determines success or failure from the HTTP response code at the time the action was attempted:

status: "success" — the operation completed with an HTTP 2xx response
status: "failed" — the operation was rejected with an HTTP 4xx or 5xx response

A failed entry means the action was attempted but did not complete. The underlying record was not modified. Use this to identify workflow errors, permission misconfigurations, and potential unauthorized access attempts.

{
  "actionType": "DELETE",
  "resourceType": "EXPENSE",
  "description": "Attempted to delete expense",
  "metadata": { "status": "failed" }
}

Use Cases

Compliance and External Audits

Export the full activity history for a fiscal year and provide it to your external auditors as evidence of internal controls. The audit trail demonstrates that your organization maintains proper authorization procedures, tracks every financial change, and retains records permanently.

GET /audit-logs?startDate=2025-01-01&endDate=2025-12-31&limit=100

Paginate through the full result set, compile the pages, and export to your preferred format.

Security Monitoring

Conduct a monthly security review to confirm that admin-level actions align with expected operations. Look specifically for unusual DELETE activity, configuration changes, or a spike in failed operations — these can indicate either a system problem or an unauthorized access attempt.

# Monthly admin DELETE review
GET /audit-logs?actorType=organization_admin&actionType=DELETE&startDate=2026-06-01&endDate=2026-06-30

# Failed operations — worth investigating
GET /audit-logs?search=failed

Troubleshooting Data Discrepancies

When a member disputes a transaction or a balance doesn’t match expectations, the audit trail gives you a chronological reconstruction of every action that touched the relevant records.

# All loan actions involving a specific member
GET /audit-logs?resourceType=LOAN&search=Jane%20Smith

# Sort oldest-first to see the full timeline
GET /audit-logs?resourceType=SAVINGS&sortBy=createdAt&sortOrder=asc

Cross-reference the actorName, description, and createdAt fields against the actual record to identify exactly when and by whom an error was introduced.

Staff Training and Quality Control

Review the actions of newly onboarded staff to confirm they are following correct procedures. Filter by actor name to see their activity, and check the metadata.status field to catch patterns of failed operations that may indicate confusion about a workflow.

GET /audit-logs?search=Mark%20Johnson

Log Retention

Audit logs are stored permanently. No user — including administrators — can delete audit entries. This is intentional: compliance obligations often require 7 or more years of financial records, and a mutable audit trail would undermine its legal and investigative value. For large organizations with thousands of entries, always apply date ranges and resource type filters rather than retrieving all logs at once. Paginate through results using the pagination.hasNextPage flag.

Best Practices

Schedule a weekly 15-minute review of DELETE actions and admin configuration changes. Catching unauthorized modifications early is far easier than reconstructing what happened months later.

Filter before you browse. Use resourceType, actionType, and date range parameters together to scope your review before looking at individual entries.
Always check metadata for context. The description field gives a one-line summary; metadata contains amounts, member names, rates, and other details that make the entry meaningful.
Sort chronologically for investigations. Set sortBy=createdAt&sortOrder=asc to see events in the sequence they occurred rather than most-recent-first.
Review audit logs before closing a period. Confirm that all entries look correct and no unexpected deletions or modifications occurred before you lock the period permanently.
Keep copies with your financial reports. When you archive a period-end balance sheet and profit & loss statement, export the corresponding audit log segment and store it alongside those reports.

Period Closing

Review the audit trail before you lock a period — corrections become much harder after closing.

Permissions

Control who holds audit_logs:read and understand the ANY scope requirement.

Organization Settings

See what configuration changes look like in the audit trail.

Settings Overview

Return to the top-level settings guide.

​What the Audit Trail Records

​Access the Audit Logs

​Query Parameters

​Resource Types

​Response Structure

​Response Fields

​Pagination Fields

​Filtering Examples

​By Actor Type — Admins Only

​By Resource Type — Loan Activity

​By Action — Deletions Only

​By Date Range — A Specific Month

​Keyword Search — A Specific Person

​Combined — Admin Deletions Last Month

​Detecting Failed Operations

​Use Cases

​Compliance and External Audits

​Security Monitoring

​Troubleshooting Data Discrepancies

​Staff Training and Quality Control

​Log Retention

​Best Practices

Period Closing

Permissions

Organization Settings

Settings Overview

What the Audit Trail Records

Access the Audit Logs

Query Parameters

Resource Types

Response Structure

Response Fields

Pagination Fields

Filtering Examples

By Actor Type — Admins Only

By Resource Type — Loan Activity

By Action — Deletions Only

By Date Range — A Specific Month

Keyword Search — A Specific Person

Combined — Admin Deletions Last Month

Detecting Failed Operations

Use Cases

Compliance and External Audits

Security Monitoring

Troubleshooting Data Discrepancies

Staff Training and Quality Control

Log Retention

Best Practices