Audit

✅ Verified

Routes against Axowl.Auth/EndPoints/AdminAuditEndpoints.cs, IntegrityEndpoints.cs (origin/main) — 2026-06-22. Response shapes ⚠️ pending OpenAPI.

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

Analytics — GET /analytics

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.

{
  "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": "a@b.com", "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.

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": 30
}

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. They are retained for a 30-day grace period, during which upgrading the plan restores access to them instantly. The organization’s owner is emailed when the grace period starts.

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