Audit Logging

Comprehensive audit trail for all system events, including auth, user access, business operations, financial transactions, compliance actions, and workflow changes.

Overview

Audit logging is the foundation of accountability, regulatory compliance, and dispute resolution. Every significant action in the system is recorded in an immutable audit log. These logs cannot be edited or deleted by any user, including administrators. Audit data supports internal investigations, external audits, legal proceedings, and regulatory reporting.

What Gets Audited

The system captures events across six domains. Each domain covers a specific area of the platform.

1. Authentication Events

Event	Description	Detail Captured
`auth.login_success`	User successfully logged in	User ID, IP, timestamp, device
`auth.login_failed`	Failed login attempt	Username attempted, IP, reason
`auth.logout`	User logged out	User ID, session duration
`auth.token_refresh`	Access token refreshed	User ID, session ID
`auth.token_revoked`	Token explicitly revoked	User ID, token JTI, reason
`auth.password_changed`	User changed their password	User ID, method
`auth.password_reset_requested`	Password reset email sent	Email, IP
`auth.password_reset_completed`	Password reset completed	User ID, IP
`auth.account_locked`	Account locked due to failed attempts	User ID, reason, lockout duration
`auth.2fa_enabled`	Two-factor authentication enabled	User ID, method
`auth.2fa_disabled`	Two-factor authentication disabled	User ID, reason

2. User and Access Management Events

Event	Description	Detail Captured
`user.created`	New user account created	Actor, new user ID, role assigned
`user.updated`	User profile modified	Actor, user ID, fields changed
`user.deactivated`	User account deactivated	Actor, user ID, reason
`user.reactivated`	User account reactivated	Actor, user ID, reason
`role.created`	New role created	Actor, role name, permissions assigned
`role.updated`	Role permissions modified	Actor, role ID, permission changes
`role.deleted`	Role removed	Actor, role ID, reason
`permission.granted`	Permission added to role	Actor, role ID, permission name
`permission.revoked`	Permission removed from role	Actor, role ID, permission name
`tenant_access.granted`	User granted tenant access	Actor, user ID, tenant ID
`tenant_access.revoked`	User tenant access removed	Actor, user ID, tenant ID
`branch_access.granted`	User granted branch access	Actor, user ID, branch ID
`branch_access.revoked`	User branch access removed	Actor, user ID, branch ID

3. Business Operations Events

Event	Description	Detail Captured
`reservation.created`	New reservation created	Customer, dates, vehicle category
`reservation.updated`	Reservation details modified	Fields changed, actor
`reservation.confirmed`	Reservation confirmed	Vehicle assigned
`reservation.cancelled`	Reservation cancelled	Reason code, refund details
`reservation.no_show`	Customer no-show recorded	Auto-triggered
`contract.checkout`	Vehicle checked out to customer	Vehicle, odometer, fuel level
`contract.checkin`	Vehicle checked in from customer	Odometer, fuel level, condition
`contract.extended`	Rental contract extended	New return date, additional charges
`vehicle.status_changed`	Vehicle status updated	Old status → new status, reason
`vehicle.assigned`	Vehicle assigned to reservation	Vehicle ID, reservation ID
`vehicle.reassigned`	Vehicle reassigned to different reservation	Old vehicle → new vehicle, reason
`delivery.task_created`	Delivery task generated	Reservation, delivery type, address
`delivery.task_completed`	Delivery completed successfully	Driver, timestamp, proof captured
`delivery.task_failed`	Delivery failed	Failure reason, driver notes
`collection.task_created`	Collection task generated	Reservation, collection type
`collection.task_completed`	Collection completed	Driver, condition summary
`collection.task_failed`	Collection failed	Failure reason

4. Financial Events

Event	Description	Detail Captured
`invoice.created`	Invoice generated	Invoice ID, amount, customer
`invoice.issued`	Invoice sent to customer	Invoice ID, delivery method
`invoice.voided`	Invoice voided	Actor, reason
`payment.received`	Payment recorded	Amount, method, transaction ID
`payment.failed`	Payment attempt failed	Amount, failure reason
`payment.refunded`	Refund processed	Amount, reason, approval chain
`deposit.collected`	Security deposit collected	Amount, hold method
`deposit.released`	Security deposit returned	Amount, reason
`deposit.forfeited`	Security deposit forfeited	Amount, reason, linked damage/invoice
`credit_note.issued`	Credit note created	Amount, linked invoice
`billing.batch_generated`	Corporate billing batch created	Batch ID, account, total
`billing.batch_approved`	Billing batch approved	Approver, amount
`fine.charged`	Traffic fine charged to customer	Fine amount, vehicle, violation
`salik.charged`	Salik toll charged to customer	Amount, crossings count

5. Compliance Events

Event	Description	Detail Captured
`document.uploaded`	Document submitted for verification	Entity, document type
`document.approved`	Document verified and approved	Reviewer, document type
`document.rejected`	Document rejected	Reviewer, rejection reason
`document.override`	Verification override applied	Override reason, authority
`complaint.created`	Complaint filed	Category, channel, priority
`complaint.escalated`	Complaint escalated	Escalation level, reason
`complaint.legally_escalated`	Complaint sent to Legal	Reason, linked legal case
`complaint.resolved`	Complaint resolved	Resolution type
`legal_case.created`	Legal case opened	Source, incident details
`legal_case.closed`	Legal case closed	Closure type, financial outcome
`compliance.task_created`	Compliance task auto-generated	Task type, entity, due date
`compliance.task_completed`	Compliance task resolved	Actor, resolution

6. Workflow Events

Event	Description	Detail Captured
`workflow.instance_created`	Workflow instance started	Entity type, entity ID, workflow
`workflow.transition_executed`	Status transition performed	From stage → to stage, action
`workflow.action_denied`	Transition blocked	Reason, permission missing
`workflow.task_created`	Workflow task created	Task type, assignee
`workflow.task_completed`	Workflow task completed	Actor, completion details
`workflow.task.escalated`	Workflow task escalated	Escalation reason
`workflow.approval.requested`	Approval request created	Requester, approval type
`workflow.approval.granted`	Approval given	Approver, conditions
`workflow.approval.denied`	Approval denied	Denier, reason
`workflow.sla.warning`	SLA approaching deadline	Task type, time remaining
`workflow.sla.breach`	SLA deadline exceeded	Task type, overage

Audit Entry Fields

Every audit log entry contains these fields:

Field	Description
`id`	Unique audit entry identifier (UUID)
`timestamp`	Date and time of the event (UTC, millisecond precision)
`actor_user_id`	ID of the user who performed the action
`actor_username`	Username or email of the actor
`actor_role`	Role(s) of the actor at the time of the event
`tenant_id`	Tenant context of the event
`branch_id`	Branch context (if applicable)
`event_type`	Categorized event code (e.g., `auth.login_success`)
`entity_type`	Type of entity affected (e.g., `reservation`, `vehicle`, `invoice`)
`entity_id`	ID of the entity affected
`action`	Description of what was done
`old_value`	Previous state (JSON, for update events)
`new_value`	New state (JSON, for update events)
`ip_address`	Client IP address
`user_agent`	Browser or app identifier
`request_id`	Correlates to the API request ID
`session_id`	User session identifier
`success`	Boolean — whether the action succeeded
`error_message`	Error details (if the action failed)

Immutability

Audit logs are write-once. The following rules apply:

Rule	Detail
No edits	Audit entries cannot be modified after creation
No deletes	Audit entries cannot be deleted by any user
No soft-delete	There is no "delete" flag on audit entries
No bulk operations	No bulk edit or delete tools are available on audit data
System-only writes	Only the application backend can create audit entries
Separate storage	Audit logs are stored in a dedicated table with write-only permissions

Critical: Even database administrators cannot modify audit logs through the application. Direct database manipulation is outside the application's control and is a violation of security policy.

Data Retention

Data Type	Retention Period	Archive After
Authentication events	3 years	Cold storage after 1 year
User management events	7 years	Cold storage after 2 years
Business operations events	7 years	Cold storage after 2 years
Financial events	10 years	Cold storage after 3 years
Compliance events	10 years	Cold storage after 3 years
Workflow events	5 years	Cold storage after 2 years

Note: Legal case audit trails are retained for the life of the case plus 10 years, regardless of standard retention periods.

Viewing Audit Logs

Who Can View

Role	Access Scope
Compliance Officer	All events across all tenants
Operations Director	All events for their tenant
Branch Manager	Events for their branch
Finance Lead	Financial events for their tenant
IT Administrator	System events, authentication events
Legal Team	Legal and complaint events (linked to their cases)
Other staff	No direct audit log access

Viewing Methods

Method	How
Entity-level audit trail	Open any entity (reservation, contract, customer, vehicle) → click Audit Trail tab
Global audit log	Compliance → Audit Log (filtered by default)
Export	Compliance → Audit Log → Export (CSV or PDF)
API	`GET /api/audit-logs` with query filters

Filter	Options
Event type	All, auth, user, business, financial, compliance, workflow
Entity type	All entity types
Actor	Specific user or "all users"
Date range	From/to date pickers
Tenant	Tenant name (multi-tenant view only)
Branch	Branch name
Success/Failure	Successful actions, failed actions, or both

Audit Export

For external audits, legal proceedings, or regulatory reporting:

Navigate to Compliance → Audit Log.
Apply the desired filters.
Click Export.
Select format (CSV or PDF).
Choose date range and scope.
Confirm export. The system generates the file and makes it available for download.

Rule: Audit exports are logged. The export request itself generates an audit entry recording who exported what data and when.

Callouts

Audit logs are the single source of truth for all actions. In any dispute, investigation, or legal proceeding, audit log data takes precedence over human memory, email records, or informal notes.

Audit log performance: The system indexes audit entries by timestamp, event type, entity, and actor. Queries return results in under 2 seconds for data within the past 30 days. Older data may take up to 10 seconds for complex queries.

Audit Logging

On this page