Audit

Audit query — `/api/v1/admin/audit` (authenticated)

Method · Route	Purpose	Source
GET `/query` · `/query/detail`	Query audit events	`AdminAuditEndpoints.cs:39`
GET `/sessions`	Member sessions	`:41`
GET `/stats` · `/stats/quick`	Dashboard stats	`:42`
GET `/stats/forensic`	Forensic query by email (scope to an app group)	`:44`
GET `/verify/{logId}`	Verify a single sealed record	`:46`
GET `/presign`	Presigned URL for archived logs	`:38`
GET `/retention`	This organization’s audit retention window	`:46`
POST `/heartbeat`	Active-time heartbeat	`:45`
GET `/analytics`	Aggregated usage analytics (added 2026-08-04)	`AdminAuditEndpoints.cs`
GET `/analytics/rollup`	Sign-in outcomes and event volumes from sealed daily rollups (added 2026-08-04)	`AdminAuditEndpoints.cs`
GET `/behavior/rollup`	Pages, dwell time, referrers and countries from sealed daily rollups (added 2026-08-14)	`AdminAuditEndpoints.cs`

Who sees which events — `scope=mine|all`

GET /query takes scope (default mine). Visibility is decided by scopes, not role labels, with one owner-only carve-out (updated 2026-08-24):

Caller holds	`scope=mine`	`scope=all`
Nothing audit-specific (default member grant `org.audit_event_log.list:actor=self`)	Own events only	`403 PERMISSION_DENIED`
Per-system grants `org.audit_event_log.list_system:system=<key>` (the Team Lead preset ships `agent`, `project_mgmt`, `reporting`)	Own events only	All events of the granted systems plus the caller’s own events
Unconstrained `org.audit_event_log.list` (Owner/Admin hold this implicitly)	Own events only	The whole organization

Two further conditions apply to scope=all (since 2026-09-23): the caller must be an organization Owner or Admin — a Member who was granted the unconstrained scope still gets 403 PERMISSION_DENIED — and the organization must be on Pro or higher. Below Pro the server answers 403 {"error": "UPGRADE_REQUIRED", "feature": "feature.audit.view_all"}; the dashboard shows an upgrade prompt in place and falls back to the caller’s own records. Every plan keeps scope=mine (the default) fully available. A single query covers at most 90 days; the plan’s retention window (below) still applies inside that.

System keys map to event-type prefixes: agent → agent.*, project_mgmt → org.project.*, reporting → reporting.*, payment → payment.*.

payment.* events are visible to the organization owner only. This is a carve-out, not a scope: admins and per-system holders never receive them on any path (list, detail, or archive), mirroring the billing owner-only rule.

GET /query/detail applies the same judgment per event — knowing a logId does not open an event you could not see in the list.

Aggregated metrics behind the dashboard’s Audit Analytics page. Requires membership in the organization.

Query parameters:

Param	Meaning
`orgId`	Organization id (required)
`days`	Window length in days — clamped to 1–90, default 30
`appGroupId`	Optional. Scopes end-user metrics to one app group

Two layers with different scopes, matching the data model:

End-user metrics (daily active users, logins, sign-ups, sign-in method mix, top users / IPs, per-app-group actives) come from end-user events, which carry an app-group axis. Every KPI ships with the previous-period value so clients can render a change badge.
Organization audit metrics (orgEventTypes) come from member/system audit events and are always organization-wide — those records carry no app-group axis. They cover only the hot window (orgAuditWindowDays, currently 3 days); longer horizons come from the archive path in a later phase.

Where the daily series comes from (windowSource, added 2026-08-16): windows beyond the 3-day preview read the daily activity / sign-up series and period totals from sealed daily rollups (the same files behind /analytics/rollup), bucketed by UTC day; only the current, incomplete day is filled from the hot store. rollupCoveredDates / rollupRequestedDates say how much of the window rollups actually cover — missing days chart as zero but are declared, not hidden. windowSource is "hot" for 3-day windows and app-group-filtered views (rollups carry no app-group axis), and "hot_fallback" when no rollups exist yet for the window. MAU and the identity-level widgets (top users / IPs, sign-in methods, per-app-group actives) still read the hot end-user store — daily rollups cannot express cross-day distinct users or those dimensions.

Caching (added 2026-09-22): a completed day’s rollup never changes, so its parsed rows are cached per organization and day for up to 7 days; only days not yet in the cache are fetched from storage. A day with no rollup yet is remembered for 10 minutes, so a rollup that lands later shows up within that window. This applies to both /analytics and /analytics/rollup; it does not change any field of either response.

{
  "days": 30,
  "addonActive": true,
  "freeWindowDays": 3,
  "windowSource": "rollup",
  "rollupCoveredDates": 27,
  "rollupRequestedDates": 29,
  "appGroups": [{ "id": "…", "name": "My App", "eventsEnabled": true }],
  "kpi": { "mau": 812, "mauPrev": 640, "logins": 5210, "loginsPrev": 4102,
           "signups": 96, "signupsPrev": 71, "dauToday": 143 },
  "daily": [{ "date": "07-06", "logins": 180, "dau": 84, "signups": 3 }],
  "providers": [{ "provider": "Passkey", "count": 3120 }],
  "byAppGroup": [{ "appGroupId": "…", "name": "My App", "activeUsers": 490, "logins": 3800 }],
  "topUsers": [{ "email": "[email protected]", "displayName": "A", "logins": 88 }],
  "topIps": [{ "ip": "203.0.113.9", "count": 412, "users": 12 }],
  "orgEventTypes": [{ "eventType": "org.member.invited", "count": 12, "sealedCount": 12 }],
  "orgAuditWindowDays": 3
}

One honesty rule worth knowing: app groups with event collection turned off report zeros because nothing is recorded — the dashboard badges this rather than letting the number read as “no activity”.

Sign-in outcomes — `GET /analytics/rollup`

Sign-in success and failure over time, read from sealed daily rollups rather than the live tables. Same orgId / days parameters (1–90).

Two things this answers that the live query above cannot:

Failed attempts on accounts that don’t exist. End-user event rows require a real user, so an attempt against an unknown email — the signature of credential stuffing — can’t be stored there. The rollup is built from the audit chain, which has no such constraint, so those attempts are counted.
Windows longer than the hot cache. The rollup is one small file per day, so ninety days costs about the same to read as one.

{
  "available": true, "days": 30, "coveredDates": 12, "requestedDates": 30,
  "daily": [{ "date": "07-28", "logins": 412, "failures": 9, "totalEvents": 980 }],
  "failureReasons": [{ "reason": "invalid_credentials", "count": 61 }],
  "totals": { "logins": 5210, "failures": 118, "attempts": 5328, "failureRatePct": 2.2 }
}

coveredDates is the number of days that actually had a rollup — days without one are left out rather than filled with zeros, because a zero would read as “nothing happened” when the truth is “we don’t know yet”. When no rollup exists for the window at all, the response is { "available": false, "reason": "no_rollups_yet" }.

Rollups are built once a day just after midnight UTC, and missing past days are backfilled automatically from the archived raw events (up to the 90-day window) — so coverage extends as far back as your organization has raw history, not just from the day the feature was enabled. Each day’s rollup is uploaded once and then never rewritten; re-running the builder skips days whose rollup already exists.

Visitor behavior — `GET /behavior/rollup`

Pages, dwell time, referrers, campaign sources and countries for an app group, read from the same kind of sealed daily rollup. Takes orgId, days (1–90) and an optional appGroupId.

This route is on a different axis from the two above: it reports what visitors did on your site, collected through the behavior beacon, rather than what happened inside Axowl’s audit chain. Two consequences worth knowing:

No add-on gate. The full 90-day window is free — behavior analytics is metered on collection, not on reading. The 3-day preview clamp described under Access does not apply here.
Visitor counts are upper bounds. Rollup rows are keyed by page, referrer and country, so one visitor reading three pages is counted once per page. The fields are named visitorsUpperBound and identifiedUsersUpperBound for that reason. Views and dwell time are exact.

Full response shape and integration details live in the Behavior analytics guide.

Access

The two audit analytics routes — /analytics and /analytics/rollup — work without the Audit Analytics add-on, but only over a 3-day preview window: for organizations that don’t own the add-on, the server clamps days to 3 regardless of what you request, and the /analytics response says so with "addonActive": false, "freeWindowDays": 3. The add-on opens the full 90-day window. The clamp is enforced server-side — passing days=90 without the add-on returns 3 days, not an error.

The add-on is $99/month flat and is enabled from the dashboard: Billing → Add-ons → Audit Analytics → Enable. It is billed from the organization’s prepaid credit (a 402 on enable means the balance is short) and, like other paid add-ons, requires the Pro plan or higher (403 UPGRADE_REQUIRED on Free).

Audit retention is a plan limit and is unrelated — retention decides how far back history exists, the add-on decides how much of it your dashboards can read.

GET /behavior/rollup is not covered by any of the above — it has no add-on requirement and no preview clamp.

Retention

How far back audit history can be queried depends on the organization’s plan. Every event is sealed and notarized on every plan — retention limits how far back you can look, not whether we record. Sealing carries no volume limit and no per-event fee.

Plan	Queryable history
Free	1 day
Pro	7 days
Pro+	30 days
Business	90 days
Enterprise	Set per contract (unlimited by default)

The same window applies to Request & Approval records. Approvals that are still in flight are never hidden — retention only applies once a request is completed, rejected, or acknowledged.

Where long windows are read from

The most recent three days are served from the hot store. Older days come from the sealed daily Parquet archive. Since 2026-09-22 a completed day is read from a single compacted per-day file when one exists (built nightly from that day’s sealed batches, sorted by time); days without one fall back to the individual batch files. Since 2026-09-23 a per-organization manifest (rebuilt nightly) additionally lists the days that hold no events at all, so a long window skips those days without touching storage, and the query server keeps a local copy of archive files it has already fetched (they never change once written), so reopening the same window does not download them again. This changes only how fast a long window answers — the rows, fields and visibility rules are the same either way.

How the window is enforced

GET /retention returns the window so a UI can bound its date picker before querying:

{
  "planKey": "plan.pro",
  "retentionDays": 7,
  "unlimited": false,
  "windowStartUtc": "2026-07-21T09:14:00Z",
  "isContractOverride": false,
  "graceDays": 20,
  "noticeCount": 1,
  "noticeCountPolicy": 2,
  "noticeIntervalDays": 10,
  "firstNoticeAt": "2026-09-22T09:00:00Z",
  "finalNoticeAt": null,
  "purgeScheduledAt": "2026-10-12T00:00:00Z",
  "purgeUnlocked": false,
  "canPurgeNow": true
}

On /query, /query/detail, and /stats/forensic:

A range that partly predates the window is clamped to windowStartUtc; you get the portion inside the window.
A range that lies entirely outside the window returns 402 Payment Required with code: "UPGRADE_REQUIRED" and feature: "audit.retention".

After the window: grace, then deletion

Events that fall out of the window are not deleted immediately. When history first leaves the window, the organization’s owner is emailed twice, 10 days apart. The second email is an action-required notice that states the deletion date. If the plan is not upgraded within 10 days after that notice (20 days in total, graceDays), the expired history is permanently deleted. Upgrading at any point before then restores access instantly. History that leaves the window later is deleted on the same schedule without further emails; a new notice cycle only starts if the plan’s retention period changes.

An owner can also delete expired history right away from the console (audit dashboard → “Delete expired history now”), which requires a seal (passkey). The same call is available as POST /retention/purge-now with the seal assertion in the body; GET /retention reports canPurgeNow and the notice ledger (noticeCount, finalNoticeAt, purgeScheduledAt).

Only after the grace period is the underlying archive permanently deleted, and the owner is emailed again. Deletion is itself recorded: a sealed tombstone is written before anything is removed, carrying the Merkle root of the deleted events plus the integrity hashes on either side of the gap. That means:

A record you still hold a copy of can be proven to have belonged to the deleted range, via its payload hash.
The audit chain has a signed bridge across the gap rather than an unexplained hole — deletion under policy stays distinguishable from tampering.

Per-event verification (GET /verify/{logId}, and client-side “verify on my device”) is unaffected by deletion of other events: each record’s payload hash and signature are self-contained.

Organizations under a legal hold are never purged, regardless of plan.

Integrity violations — `/api/v1/admin/integrity` (authenticated)

Method · Route	Purpose	Source
POST `/restore/{entityType}/{entityId}`	Restore a record to its sealed baseline	`IntegrityEndpoints.cs:246`
POST `/resolve/{entityType}/{entityId}`	Resolve a violation as false-positive (append-only; the original `tampering_detected` record is preserved)	`:415`