Audit

Every financial mutation and every sensitive action in the platform writes an AuditEvent. Operators read the trail through GET /v1/ops/audit, filtered by customer and attributed across the full actor chain — including autonomous agents and internal rules.

The endpoint

GET /v1/ops/audit?customer_id=<id>&limit=<n>

The endpoint is operator-gated (require_role("operator")). It returns audit events newest-first, optional customer_id filter, capped at limit (maximum 200):

apps/api/src/neobank/api.py

@router.get("/ops/audit", response_model=list[AuditEventView], tags=["Operator"])
async def ops_audit(
    _operator: Annotated[Principal, Depends(require_role("operator"))],
    session: DbSession,
    customer_id: str | None = None,
    limit: int = Query(default=100, ge=1, le=200),
) -> list[AuditEventView]:

See Operator console for the role and MFA requirements that gate this route.

The AuditEvent row

Each row is a single attributed action. The columns come from the AuditEvent model:

apps/api/src/neobank/models.py

class AuditEvent(Base):
    __tablename__ = "audit_events"
    __table_args__ = (Index("ix_audit_customer_created", "customer_id", "created_at"),)

    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_id)
    customer_id: Mapped[str | None] = mapped_column(String(36), index=True)
    actor_id: Mapped[str] = mapped_column(String(255), index=True)
    actor_client_id: Mapped[str | None] = mapped_column(String(255), index=True)
    action: Mapped[str] = mapped_column(String(120))
    resource_type: Mapped[str] = mapped_column(String(80))
    resource_id: Mapped[str | None] = mapped_column(String(255))
    request_id: Mapped[str] = mapped_column(String(128))
    metadata_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)

Field	Meaning
`customer_id`	The customer whose resource was acted on (nullable for cross-customer actions)
`actor_id`	The authenticated subject that performed the action
`actor_client_id`	The authorized client (agent or internal rule) the actor acted through; `null` for a direct customer session
`action`	What the actor did (for example, `mandate.execute`, `card.freeze`)
`resource_type` / `resource_id`	The kind and ID of the resource acted on
`request_id`	Correlates with `X-Request-ID` on the API response and in logs
`metadata`	Action-specific detail (amounts, states, failure codes)
`created_at`	When the event was written

The composite index ix_audit_customer_created (customer_id, created_at) backs the filtered, newest-first listing an operator runs during triage.

Attribution across the actor chain

The two actor_* columns are what make the trail usable for mandate investigation. A single mandate execution by an autonomous agent produces an event whose actor_id is the agent’s subject and whose actor_client_id is the authorized client that the customer approved on the mandate. Direct customer actions leave actor_client_id null. This lets an operator answer “which authorized client executed this mandated payment?” without inference. Cross-reference the request_id against the operation in /v1/ops/operations to tie the audit row to the resulting transfer and its outcome.

Actions taken by an internal_rule caller carry that rule’s identifier in actor_client_id, not a human subject. The trail distinguishes a human-initiated action from a rule-initiated one in the same column.

Operator console — the surface operators use alongside this trail.
Agent mandates — how authorized clients and rules come to hold execution authority, and what an actor_client_id value represents.

Get Started

Architecture

Deploy

Customize

Operate

Integrate

Security

Reference

Contributing

Audit

Audit

The endpoint

The AuditEvent row

Attribution across the actor chain

​Audit

​The endpoint

​The AuditEvent row

​Attribution across the actor chain

​Related

Audit

The endpoint

The AuditEvent row

Attribution across the actor chain

Related