audit — API

GET/api/v1/businesses/:businessId/audit-events auth: jwt (administrator | view_audit)

Paginated audit log for a business. Supports filters by eventType (comma-separated → IN clause), resourceType, resourceId, dateFrom/dateTo (epoch ms), and a search term (matches ResourceId or ActorEmail with %term%). Returns items + total + stats (fiscalised/failed/actors counts). Fires VIEW_AUDIT_LOG fire-and-forget after the response is sent.

handlers: AuditController.list

Inputs

name	required	default	description
`businessId` path uuid	yes	—	Target business UUID. Caller's JWT businessId must match (Administrator bypasses via requireBusinessAccess).
`page` query int	no	`1`	1-based page number; clamped to >= 1.
`pageSize` query int	no	`20`	Page size, clamped 1..100.
`eventType` query string	no	—	AuditEventType, optionally comma-separated for IN().
`resourceType` query string	no	—	Filter by ResourceType (INVOICE, USER, XERO_CONNECTION, ...).
`resourceId` query string	no	—	Filter by exact ResourceId.
`dateFrom` query int (epoch ms)	no	—	Inclusive lower bound on CreatedAt.
`dateTo` query int (epoch ms)	no	—	Inclusive upper bound on CreatedAt.
`search` query string	no	—	Substring match against ResourceId or ActorEmail.

Outputs

200

APIResponseDataObject<{ items: AuditLogDTO[]; total: number; page: number; totalPages: number; stats: { fiscalised: number; failed: number; actors: number } }>

Paginated items plus computed stats.

403

APIError

USER_FORBIDDEN — businessId mismatch (non-Administrator) or insufficient role.

GET/api/v1/businesses/:businessId/audit-events/export auth: jwt (administrator)

Stream all matching audit events as CSV (Content-Disposition: attachment; filename=audit-log-<businessId>-<yyyy-mm-dd>.csv). Same filters as the list endpoint; Administrator only (requireAdmin). Registered before /:id so Express does not treat 'export' as an id param.

handlers: AuditController.export

Inputs

name	required	default	description
`businessId` path uuid	yes	—	Target business UUID. Administrator bypasses requireBusinessAccess.
`eventType` query string	no	—	AuditEventType, optionally comma-separated.
`resourceType` query string	no	—	Filter by ResourceType.
`resourceId` query string	no	—	Filter by exact ResourceId.
`dateFrom` query int (epoch ms)	no	—	Inclusive lower bound on CreatedAt.
`dateTo` query int (epoch ms)	no	—	Inclusive upper bound on CreatedAt.
`search` query string	no	—	Substring match against ResourceId or ActorEmail.

Outputs

200 text/csv

text/csv

CSV stream with columns Id,CreatedAt,EventType,ActorEmail,ActorRole,ResourceType,ResourceId,IpAddress,Payload.

403

APIError

USER_FORBIDDEN — caller is not Administrator.

GET/api/v1/businesses/:businessId/audit-events/:id auth: jwt (administrator | view_audit)

Fetch a single audit log entry by its BIGINT AuditLogId. Scoped to the business.

handlers: AuditController.getById

Inputs

name	required	default	description
`businessId` path uuid	yes	—	Target business UUID.
`id` path int (BIGINT)	yes	—	AuditLogs.AuditLogId — numeric, parsed via parseInt.

Outputs

200

APIResponseDataObject<AuditLogDTO>

Single audit log entry.

400

APIError

Invalid audit event id (id not parseable as integer).

403

APIError

USER_FORBIDDEN — businessId mismatch or insufficient role.

404

APIError

Audit event not found.