> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit events

> The TruU IDV audit event model: event families, the event envelope, what each event records, OCSF alignment, redaction, immutability, and how to query or export the trail to your SIEM.

This page is for the SOC engineer wiring TruU IDV into a SIEM and the auditor who needs to know what the trail proves. When you finish, you know the event families, the envelope every event shares, and how to pull the trail into your own tooling.

## Overview

TruU IDV records every meaningful action (verification activity, help desk agent actions, admin configuration changes, and console access) as structured audit events in a tenant-scoped, append-only trail. The trail is the system of record: the **Activity** page in the IDV Console, the request timeline in the help desk app, and every export are projections of the same source, so what your SOC receives matches what an admin sees.

Activity presents the trail in two tabs: **Audit** for control-plane actions (configuration changes, access, administration) and **Events** for data-plane activity (the verification lifecycle). Both offer category and outcome filters, search, and export.

## Event families

Events use stable, lowercase dotted names. Names never change once shipped, and schema evolution is additive.

| Family | Covers | Examples |
| - | - | - |
| `verification.*` | The verification lifecycle | `verification.requested`, `verification.link_delivered`, `verification.started`, `verification.factor_attempted`, `verification.factor_succeeded`, `verification.factor_failed`, `verification.fallback_selected`, `verification.completed`, `verification.failed`, `verification.expired`, plus cancel events |
| `helpdesk.*` | What an agent did | `helpdesk.user_searched`, `helpdesk.contact_previewed`, `helpdesk.request_created`, `helpdesk.request_resent`, request cancellations |
| `admin.*` | Workspace configuration | Factor, flow and use case creation and updates; directory connection, rotation, and disconnect; team invitations and role changes; API client creation, rotation, and revocation; sign-in method and SSO changes; storage configuration changes |
| `integration.*` | Connector administration | ServiceNow, TruU Passwordless, Windows TAP, and PingOne MFA connector creation, updates, secret and key rotations, linking-code issuance, and test connections |
| `auth.*`, `session.*` | Access | Sign-in successes and failures per console, session lifecycle, access-denied decisions, failed or denied token requests from API clients |

The help desk is where social-engineering attacks happen. If an agent is convinced to search a user, preview contact methods, send a link, or cancel a request, that full sequence is reconstructable from `helpdesk.*` events. Configuration changes carry a structured before and after diff, so "who changed the use case and what exactly changed" is answerable from one event.

## What each event records

Every event answers four questions with distinct fields:

* **Actor**: who did it (an admin, an agent, the end user, an API client, or the system).
* **User**: the workforce identity being verified or affected. Actor and user are deliberately separate: for `helpdesk.request_created`, the actor is the agent and the user is the caller.
* **Target**: the object acted on (a verification request, a flow, a use case, a membership record).
* **Outcome**: success, failure, or denial, with a machine-readable reason code such as `OTP_MISMATCH`.

Plus the context needed for investigation: timestamps, request and session identifiers, flow and use case references, factor type and provider, client IP and user agent, and a correlation ID that links related events.

## Example event payload

```json theme={null}
{
  "event_id": "018f5a3e-4f0d-7c21-a45f-01a4d502c0f1",
  "schema_version": "2026-04-01",
  "tenant_id": "your-tenant-id",
  "time": "2026-04-27T23:12:05.123Z",
  "event_name": "verification.factor_failed",
  "event_family": "verification",
  "display_message": "SMS factor failed for help desk verification",
  "actor": {
    "type": "user",
    "id": "entra-object-id",
    "display_name": "Sally Harmon"
  },
  "user": {
    "id": "entra-object-id",
    "email": "s***y@a***.com",
    "display_name": "Sally Harmon"
  },
  "target": {
    "type": "verification_request",
    "id": "req_abc123"
  },
  "outcome": {
    "result": "failure",
    "reason_code": "OTP_MISMATCH",
    "message": "The submitted one-time code did not match"
  },
  "client": {
    "ip": "203.0.113.10",
    "user_agent": "Mozilla/5.0 ..."
  },
  "context": {
    "request_id": "req_abc123",
    "factor_type": "sms",
    "correlation_id": "trace-id"
  },
  "pii_redacted": true
}
```

The envelope is the same across families, and the payload is aligned with the Open Cybersecurity Schema Framework (OCSF) so it maps into security tooling without a proprietary parser.

## API access and export

Programmatic access uses an API client with the audit scopes:

| Scope | Grants |
| - | - |
| `idv:audit:read` | `GET /admin/audit/events` and `GET /admin/audit/events/{event_id}` |
| `idv:audit:export` | `GET /admin/audit/export` (implies read) |

`GET /admin/audit/events` supports cursor pagination and time-range filters for incremental SIEM ingestion. `GET /admin/audit/export` produces **CSV** (default) or **NDJSON**. See [Authentication](https://docs.truu.ai/idv/api/authentication.md) for creating clients and requesting scopes, and [Send to your SIEM](https://docs.truu.ai/idv/admin/activity.md#send-to-your-siem) for a collector pattern.

> [!NOTE]
>
> Every export is itself recorded as an audit event: who exported, with what filters, and how many events.

Audit events stay in TruU regardless of your storage setting. Connecting your own storage changes where verification artifacts are written; the events that reference them remain in TruU and stay exportable as above.

## Redaction

Audit events exclude PII. The stored event carries identifiers and masked display fields only; where an event's full payload contains sensitive detail, that payload is held in controlled storage referenced by the event, under the same tenant isolation and encryption as other verification assets. The trail never stores submitted one-time codes, document images, or biometric templates. Phone numbers and email addresses are masked, face outcomes appear as confidence bands rather than scores, and each event carries a `pii_redacted` flag. See [Data handling](https://docs.truu.ai/idv/security/data-handling.md).

## Immutability

The audit trail is append-only:

* There is no API to update or delete audit events, and the console cannot modify them.
* Exports are replayable, so a downstream copy can always be reconciled against the source.

## Reconstructing an incident

Events that share a verification request are linked, so a reviewer can read a complete sequence as a timeline:

```text theme={null}
4:10 PM  Agent searched for Sally
4:11 PM  Agent created verification request
4:12 PM  User opened verification link
4:12 PM  SMS factor failed
4:13 PM  Fallback selected
4:14 PM  Face factor passed
4:14 PM  Verification completed
```

In the IDV Console, opening any event shows its related events. In the help desk app, agents see the timeline for the request they are handling, and only that request.

## Access and retention

Owners and Admins can search the workspace trail and run exports. Agents see request-scoped events only. Sensitive fields are masked regardless of role. Retention in TruU is set by your agreement; export on a schedule to keep long-term history in your SIEM or data lake.

## Related pages

> [card] [Event export and SIEM](https://docs.truu.ai/idv/admin/activity.md#send-to-your-siem)
>
> Collector pattern for Splunk, Sentinel, and data lakes.

> [card] [Authentication](https://docs.truu.ai/idv/api/authentication.md)
>
> API clients and the audit scopes.

> [card] [Permissions and roles](https://docs.truu.ai/idv/admin/team-and-roles.md)
>
> Who can see and export the trail.

> [card] [Compliance](https://docs.truu.ai/idv/security/compliance.md)
>
> Using the trail as evidence.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.