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

# Event Logs

> Provisionr records workspace actions in an audit trail of structured event types that cannot be edited, for compliance, security, and troubleshooting.

Throughout these pages, you've seen events such as `policy.user.create.success` used as the evidence of what Provisionr did and why. Those events live in your workspace's **event log**, which is the audit trail of the actions taken within your workspace. We record every identity sync, policy evaluation, group membership change, API call, and administrative action with structured metadata, so that you can use the event log for compliance, troubleshooting, and operational visibility.

Event logging is built into the core of Provisionr and runs automatically for every workspace on every plan, so there's nothing to enable, configure, or install. From the moment your workspace is created, every operation that changes state in it produces an event log entry, whether the operation was started by a user, a scheduled job, the REST API, or the Admin CLI.

This page walks through the event log in this order:

* How events are recorded, and how their event types are named
* What each part of Provisionr logs, and the fields that every event shares
* How sensitive data is masked or kept
* How you view, export, and stream events, and how long they're retained
* How events drive notifications and performance metrics

The last section covers the integrity of the event log and the compliance controls it supports, for auditors and compliance engineers.

***

## Recording Events

Every operation in Provisionr generates one or more event log entries, which are stored in your workspace's `audit_logs` table. Events are written synchronously at the time of execution, and they can't be edited, which means that once an event is created, it can't be modified or permanently deleted. Any soft delete is itself recorded as a new event. See [Immutability and Integrity](#immutability-and-integrity).

Each event captures who performed the action, what changed, when it happened, and why. For automated operations such as scheduled syncs, we also record the job context and the policy rules that triggered the change.

When a single operation affects several records, we write a separate event for each record. For example, if a policy sync adds 12 users to an Okta group and removes 3, the sync creates 15 separate events, one for each membership change, and links them all with a shared `job_id` and `job_batch` identifier. This granularity allows you to trace exactly what happened to each user while still being able to view the operation as a whole.

Events are written to the database within the same transaction as the operation itself. If an operation fails and is rolled back, the corresponding event is still recorded with an error result, so that failed operations are visible in your audit trail rather than silently disappearing.

> [!NOTE]
>
> Some of what Provisionr writes goes to operational logs rather than to your event log. Progress summaries for each sync are written to operational logs, and so are most `debug` events, so the per-record events in the event log are the evidence of record. [Logging Qualification](https://docs.provisionr.io/concepts/control/qualification.md#logging-qualification) and the levels in [Okta Audit Events](https://docs.provisionr.io/integrations/okta/audit-events#levels) describe this for each sync.

> [!TIP]
>
> The event log is written by the system as each operation is performed, rather than assembled afterward. Each affected record receives its own event, and every event names its actor and links to the job and batch that produced it. A sampled change can therefore be traced back to the operation that caused it and to the person, service account, or scheduled job that started that operation.

## Event Types

We give every event a structured event type in dot notation, in the form `area.record.action.result`. Each event type reads from the general to the specific, with one segment for each part of the event.

| Segment | Purpose | Examples |
| - | - | - |
| `area` | The part of Provisionr, or the vendor, involved | `policy`, `directory`, `workspace`, `auth`, `okta`, `google` |
| `record` | The type of record acted upon | `user`, `rule`, `ruleset`, `dimension`, `attribute`, `identity` |
| `action` | The operation performed | `create`, `update`, `activate`, `deprecate`, `deactivate`, `sync` |
| `result` | The outcome, or the stage of a process | `success`, `error`, `skipped`, `started`, `finished` |

Some event types add a segment where it makes them more precise, such as `policy.ruleset.sync.initiated.api` for a sync started through the API. The table below shows a few examples.

| Event Type | Description |
| - | - |
| `policy.user.create.success` | A person qualified for a policy, and a new grant began |
| `policy.user.deprecate.success` | A person stopped qualifying for a policy, and their grace period started |
| `policy.user.expired.deleted` | A person's grace period ended, and their grant left the manifest |
| `policy.rule.activate.success` | A rule version went live |
| `policy.ruleset.sync.initiated.api` | Someone started a sync of one policy through the API |
| `directory.user.deactivate.success` | A Directory User was deactivated because their account was deactivated in the primary integration |
| `directory.dimension.deprecate.success` | A dimension was deprecated |
| `workspace.integration.sync.okta.process.skipped` | An Okta sync did not run because the integration has no usable credential |
| `audit.log.soft_deleted` | An event log record was soft deleted |

This structure makes events easy to filter. You can filter on an exact event type, or search for part of one. For example, searching for `policy.user.` returns every Policy User event, and searching for `.skipped` returns every skipped operation, whatever its area. The [event log list](https://docs.provisionr.io/cli/workspace/v1/audit-log/list.md) in the CLI filters on any field this way.

The `skipped` result is different from both `success` and `error`. A skip means that Provisionr evaluated an operation and deliberately didn't perform it, for example because an integration had no usable credential. We log skips so that you have a complete picture of what Provisionr evaluated during a sync, and not only what it changed.

[Logging Qualification](https://docs.provisionr.io/concepts/control/qualification.md#logging-qualification) lists every Policy User and rule event, and [Okta Audit Events](https://docs.provisionr.io/integrations/okta/audit-events) lists the events of the Okta sync and write-back.

> [!NOTE]
>
> For the complete list of event types used in your workspace, see the [Event Log CLI Reference](https://docs.provisionr.io/cli/workspace/v1/audit-log/list.md).

## Event Coverage

Each part of Provisionr records its own events. This section describes what each of them logs, starting with the syncs and ending with the webhooks that you configure.

### Identity Sync Events

The Identity Sync fetches your user directory from your identity provider, such as Okta or Google Workspace, and caches it in your Provisionr workspace. Along the way, it detects new users, attribute changes, and deactivations, as well as changes to the dimensions and attributes that drive your policies.

Every time an Identity Sync runs, it records the following:

* Each user created, updated, or deactivated, with the specific attributes that changed and their old and new values
* Dimension and attribute changes detected, such as new departments appearing in your HRIS data, deprecated job titles, new cost centers, or reorganized teams
* The total number of users evaluated, the number of changes detected, and the number of API calls made to your identity provider
* Sync duration and performance metrics, including total elapsed time, per-record processing time, and API response latency
* Any errors or rate limits encountered during the sync, including the specific API endpoint, HTTP status code, and retry behavior
* The job identifier and batch identifier linking all events from this sync together

Identity Sync events use the `directory` area, such as `directory.user.*`, `directory.identity.*`, `directory.dimension.*`, and `directory.attribute.*`. The orchestration of each integration's sync uses the `workspace.integration.sync.*` area, such as `workspace.integration.sync.okta.process.started`.

If the Identity Sync encounters a rate limit from your identity provider, Provisionr logs the rate limit event, backs off according to the vendor's retry-after header, and resumes. The successful retry that follows is logged as a separate event, so you can see exactly how the sync behaved.

### Policy Sync Events

The Policy Sync evaluates each of your policies against the cached user directory and updates group memberships across your connected vendors. This is where Provisionr does the actual provisioning work, adding users to and removing them from Google Groups, Okta Groups, Slack User Groups, GitLab Groups, AWS Identity Center Groups, and other resources.

When a Policy Sync runs, it logs events for the following:

* Each user who newly qualifies for a policy and is added to the corresponding group, including which rules and conditions matched
* Each user who no longer qualifies and is removed from the group, including which rules or conditions they no longer satisfy
* Each user who was evaluated and skipped because their membership already matched the policy's expected state
* The vendor API calls made for each membership change, including the HTTP method, endpoint, response status, and response time
* Per-policy sync duration, including the time spent evaluating rules, the time spent making API calls, and the total number of records processed
* The manifest comparison between the policy's expected membership list and the vendor group's actual membership list, showing additions, removals, and unchanged members

Policy Sync events use two event type patterns. The qualification events use the `policy` area, such as `policy.user.create.success` for a person who qualifies and `policy.user.deprecate.success` for a person who stops qualifying, and [Logging Qualification](https://docs.provisionr.io/concepts/control/qualification.md#logging-qualification) lists each of them. The membership change events written to a vendor use the vendor's area, such as the Okta events in [Okta Audit Events](https://docs.provisionr.io/integrations/okta/audit-events).

All events from a single policy sync share the same `job_id`, and all events from a scheduled sync run, which evaluates all policies, share the same `job_batch`. This allows you to view a single policy's sync results, or the entire scheduled sync, as one unit.

### Administrative Events

We log every administrative action within your workspace, whether it's performed through the web interface, the CLI, or the API, so that you have a complete record of who changed your workspace configuration and when. These administrative actions generate event log entries:

| Category | Logged actions |
| - | - |
| Authentication | User sign-ins (including SSO), failed sign-in attempts, session creation and expiration, and multi-factor authentication events |
| Policy management | Policy creation, modification (including rule and condition changes), activation, deactivation, and deletion, with before and after values for each changed field |
| Workspace settings | Changes to workspace name, sync frequency, notification preferences, telemetry settings, connected vendor configurations, and any other workspace-level setting |
| Token and credential management | API token creation, rotation, and revocation, service account creation and deletion, and CLI token issuance and expiration |
| Team management | Invitations sent to new team members, role assignments and changes, and team member removal |
| Data operations | Data exports initiated (including the format, filters, and requesting user), data imports, and bulk operations |
| Billing events | Subscription plan changes, payment method updates, invoice generation, and billing contact changes |

Each administrative event records the authenticated user who performed the action, the specific fields that changed (with old and new values where applicable), the interface used (web, CLI, or API), and the IP address of the request.

### API and CLI Events

Operations performed through the REST API or the Admin CLI are logged with the same fidelity as operations performed through the web interface. The same event types, fields, and metadata are recorded regardless of how an operation was started, so there's no difference in audit coverage between the interfaces.

For API requests, each event log entry includes the following:

* The authenticated identity, whether that's a user session, a service account, a personal access token (PAT), or a CLI token
* The token identifier, and not the token value itself, so that you can trace activity back to the specific credential used
* The API endpoint, HTTP method, and request parameters
* The response status code and response time
* Rate limit headers and remaining quota, if applicable

For CLI operations, the event log also records the CLI version and the command that was executed, which helps with troubleshooting when a team member reports unexpected behavior from a CLI session.

### Vendor API Events

Every API call that Provisionr makes to an external vendor on your behalf is logged as an event. These events show you exactly how Provisionr interacts with your connected systems, which makes them the first place to look when you're troubleshooting an integration.

Vendor API events capture the following:

* The vendor, API endpoint, HTTP method, and request payload, with sensitive values masked
* The HTTP response status code, response time in milliseconds, and any error messages returned by the vendor
* Rate limit headers from the vendor's response, including remaining quota and reset time
* The Provisionr operation that triggered the API call, linked through `job_id` to the parent sync or user action
* Request identifiers from the vendor's response headers, such as Okta's `x-okta-request-id`, for cross-referencing with the vendor's own logs

If a vendor API call fails and Provisionr retries it, each attempt is logged as a separate event. The retry events include the retry attempt number and the backoff delay, so you can see exactly how Provisionr handled transient failures.

### Webhook Events

If your workspace uses webhooks to integrate with external systems or no-code workflow platforms, each webhook dispatch is logged as an event. A webhook event records the destination URL, the payload sent (with sensitive values masked), the HTTP response status from the receiving system, and the delivery latency. Failed webhook deliveries and the retries that follow them are logged as separate events.

## Event Log Schema

Each event log entry contains a consistent set of fields, but not every field is populated for every event. For example, `attribute_key` and `attribute_value_old` are only present for update events that change a specific attribute, and `job_id` is only present for events triggered by background jobs.

| Field | Description |
| - | - |
| `id` | Unique event identifier, which is a ULID with the `wslog_` prefix and sorts by creation time |
| `event_type` | Structured event type in dot notation, such as `policy.user.create.success` |
| `level` | The severity of the event, which is one of `debug`, `info`, `notice`, `warning`, `error`, `critical`, or `emergency` |
| `message` | A human-readable summary of the event |
| `method` | The Provisionr operation that recorded the event, for troubleshooting |
| `created_at` | When the event was recorded |
| `occurred_at` | When the event happened, where that differs from when it was recorded |
| `tenant_id`, `tenant_model` | The tenant that the event belongs to |
| `actor_type`, `actor_model`, `actor_id`, `actor_name`, `actor_handle` | Who or what performed the action, which is a person, a service account, or the system |
| `actor_session_id`, `actor_source` | The session that the action came from, and its source, such as `web` for the web interface or `system` for a scheduled job |
| `record_type`, `record_id` | The record that the event is about |
| `record_provider_id` | The vendor's identifier for the record, where it has one |
| `parent_type`, `parent_id` | The record's parent, for context, such as the attribute or group that a Policy User belongs to |
| `related_type`, `related_id` | A record related to the change, such as the rule that granted a Policy User |
| `subject_type`, `subject_id` | The person or record that the change affects, such as the Directory User of a Policy User |
| `attribute_key`, `attribute_value_old`, `attribute_value_new` | The field that changed, with its old and new values, for update events |
| `count_records` | The number of records the event covers, for events that summarize several |
| `job_id`, `job_batch`, `job_platform`, `job_pipeline_id`, `job_timestamp`, `job_transaction_id` | The background job, batch, and pipeline that recorded the event |
| `errors` | The error details, for events that record a failure |
| `metadata` | Additional structured context, which varies by event type. It is encrypted at rest. |

The `metadata` field contains event-type-specific information that doesn't fit into the standard schema. For a Policy User, for example, it lists the conditions of the rule that granted or no longer grants access. The structure of `metadata` varies by event type and is documented in the [Event Log CLI Reference](https://docs.provisionr.io/cli/workspace/v1/audit-log/describe.md), and [Logging Qualification](https://docs.provisionr.io/concepts/control/qualification.md#logging-qualification) shows complete Policy User events as examples.

### ULIDs

Provisionr uses ULIDs (Universally Unique Lexicographically Sortable Identifiers) for all event and record identifiers. A ULID encodes a millisecond-precision timestamp in its first 10 characters, which means that ULIDs sort naturally by creation time. Each identifier also starts with a prefix for its type, such as `wslog_` for an event, and [Naming Conventions](https://docs.provisionr.io/concepts/workspace/nomenclature.md) lists the prefix of every resource.

For example, an event with the ID `wslog_01jr38cz5ybr8hfye6j2vp4gc7` was created before an event with the ID `wslog_01jr38dn3w5cvpqraxe2p5xf19`, because the first 10 characters after the prefix sort lexicographically. This allows you to estimate when an event was created from its ID alone.

## Sensitive Data Handling

We're deliberate about what is and isn't stored in event logs. The goal is to provide enough information for compliance and troubleshooting while avoiding unnecessary exposure of sensitive data.

### Masked Values

Sensitive values are masked automatically before they're written to the event log. Masking is applied by default, so there's nothing for you to configure, and these types of data are always masked:

| Data | How it's handled |
| - | - |
| API tokens and secrets | Token values are never stored. Event logs reference tokens by their identifier, such as `wstok_01jr...`, rather than by the token string itself. |
| Passwords and credentials | Any credential value passing through the system is replaced with a masked placeholder before logging. |
| Vendor API keys | Your connected vendor credentials, such as OAuth tokens, API keys, and client secrets, are never included in event log entries. |

### Readable Values

Certain values aren't masked, because the audit trail wouldn't be meaningful without them, so anyone who can view the event log can read them. Actor names and email addresses, the old and new values of a changed attribute, the names of the records involved, and each event's `metadata` are all encrypted in the database, and they're only decrypted when someone with access views the event.

| Data | Why it's logged |
| - | - |
| Email addresses | Logged as part of user identification and group membership changes. Knowing that `jsmith@company.com` was added to the `engineering` group is the core purpose of the audit log. |
| User names and display names | Logged alongside email addresses for human readability. |
| Group names and identifiers | The names and vendor-side identifiers of the groups and resources being managed. |
| Attribute values used in policy rules | When a user's department changes from "Sales" to "Engineering" and triggers a policy re-evaluation, both values are logged so that you can understand why the membership changed. |

### PII in Event Logs

Event logs contain PII by design, because names, email addresses, and organizational attributes are fundamental to an audit trail for identity governance. This data is stored within your workspace's [isolated database](https://docs.provisionr.io/concepts/workspace/infrastructure.md), where it's subject to the same access controls, encryption at rest, and retention policies as all other workspace data.

If your organization has specific requirements for PII in audit logs, such as pseudonymization for GDPR, contact us to discuss your needs.

## Viewing Event Logs

You can reach your workspace's event logs through several interfaces. They all provide the same underlying data, and the only difference is how you interact with it.

### Web Interface

Go to the **Event Logs** section of your workspace to browse, search, and filter events. The web interface shows a paginated list of events, with the most recent events first, and you can filter it by these fields:

| Filter | Description |
| - | - |
| Event type | Use the full dot notation or wildcards, such as `okta.group.*` to see all Okta group operations |
| Date range | Select a start and end date to narrow results to a specific time window |
| Actor | Filter by a specific user, service account, or system process |
| Record | Filter by the affected record, such as a specific user, group, or policy |
| Result | Show only successes, errors, or skips |
| Job | Filter by job identifier or batch identifier to see all events from a specific sync run |

You can expand each event to view its full metadata, including the attribute changes. From the expanded view, you can go to related events, such as all events in the same job batch, or to the affected record's detail page.

### Admin CLI

You can use the CLI client to query event logs from your terminal, which is useful for scripting, automation, and quick lookups without leaving your workflow. The [Event Log CLI Reference](https://docs.provisionr.io/cli/workspace/v1/audit-log/list.md) lists every filter option.

```bash Querying the Event Log theme={null}
# List events by part of their event type
prv audit-log:list --event_type_search=policy.user.

# Find every error
prv audit-log:list --level=error

# List every event from one sync
prv audit-log:list --job_batch=01JR38CZ5YBR8HFYE6J2VP4GC7

# List every event about one record
prv audit-log:list --record_id=drusr_01kgst84wc8ak0a5ng6snvtw1n

# View a single event with its full metadata
prv audit-log:describe --id=wslog_01jr38cz5ybr8hfye6j2vp4gc7

# Show the raw JSON response
prv audit-log:list --level=error --json
```

### REST API

You can query event logs through the API to integrate them with your own tools, dashboards, and automated workflows. The API requires the `wks.maintenance.log` permission, which [Roles and Permissions](https://docs.provisionr.io/concepts/workspace/auth.md#roles-and-permissions) describes, and it returns events as JSON with the most recent events first.

```plain Querying the Event Log API theme={null}
GET /api/v1/audit/logs?filter[event_type_search]=policy.user.&filter[created_after]=2026-01-01
GET /api/v1/audit/logs?filter[level]=error&page[size]=100
GET /api/v1/audit/logs?filter[job_batch]=01JR38CZ5YBR8HFYE6J2VP4GC7&page[number]=2
GET /api/v1/audit/logs/{id}
```

Results come back in pages of up to 500 events, and you can ask for smaller pages with `page[size]`. Each response includes a `next_page_url` for the next page, which is empty on the last page, and the CLI follows it for you. Each filter has an exact form, such as `filter[event_type]`, and most also have a partial form, such as `filter[event_type_search]`. See the [API Reference](https://docs.provisionr.io/api/workspace/v1/overview.md) for the complete endpoint documentation.

## Exporting Event Logs

You can export event logs from your workspace for offline analysis, compliance reporting, long-term archival, or integration with external tools. Exports are available on all plans, in these formats:

| Format | Use Case |
| - | - |
| JSON | Complete data export for programmatic processing, SIEM ingestion, or archival |
| CSV | Tabular export for spreadsheet analysis, reporting, and sharing with non-technical stakeholders |
| YAML | Human-readable export for configuration review and documentation |
| API | Programmatic access for continuous integration with external systems and automated pipelines |

You can filter an export by date range, event type, actor, record, result, and job identifiers, and every export includes the full event metadata for each event. Exports are generated as downloadable files from the web interface, or returned as paginated JSON from the API.

### Export Size and Performance

For workspaces with large volumes of events, exports are split into manageable files. If an export from the web interface exceeds 100,000 events, it's generated as a ZIP archive that contains multiple JSON or CSV files.

### Scheduled Exports

Customers on the Growth and Scale plans can configure scheduled exports, which run automatically and deliver event log files to a destination of your choice. This is useful for maintaining a continuous archive of event logs in your own storage, or for feeding a regular compliance reporting pipeline.

## SIEM Integration (Scale Plan)

Customers on the Scale plan receive direct access to event log data in Amazon S3, for integration with your Security Information and Event Management (SIEM) platform. Because Scale plan workspaces run on dedicated AWS infrastructure, event logs are written to an S3 bucket in your dedicated AWS account, which gives you full control over access, retention, and lifecycle management.

Event logs are written to S3 in near real-time as operations occur, and the S3 event log files follow a predictable path format for easy ingestion:

```
s3://provisionr-audit-{workspace_id}/events/{year}/{month}/{day}/{hour}/
```

Each hourly partition contains one or more JSON files with the event log entries for that hour. The files are written in newline-delimited JSON (NDJSON) format, which most SIEM platforms support natively.

### Supported SIEM Platforms

The S3-based event log format is compatible with any SIEM that supports S3 ingestion, including the platforms in this table.

| Platform | How to ingest |
| - | - |
| Splunk | Use the Splunk Add-on for AWS to ingest from the S3 bucket with SQS notifications |
| Datadog | Configure an S3 log source with the Datadog Forwarder Lambda function |
| Elastic / OpenSearch | Use Filebeat or Logstash with the S3 input plugin |
| Sumo Logic | Configure an S3 source in a Hosted Collector |
| Microsoft Sentinel | Use the S3 connector through the Azure Monitor Agent or a custom Lambda forwarder |
| Chronicle (Google SecOps) | Configure an S3 feed with the Chronicle ingestion API |

### S3 Event Notifications

Your S3 bucket is configured with event notifications that trigger when new event log files are written. You can subscribe an SQS queue, an SNS topic, or a Lambda function to these notifications to process events in near real-time as they arrive.

### Access Control

You control access to your S3 event log bucket through standard AWS IAM policies. Provisionr's service role has write-only access, which it uses to deliver event logs, and your team manages read access through your own IAM policies. This allows you to grant access to your SIEM service account, security team, or compliance auditors without involving Provisionr.

## Retention Policies

Event log retention varies by plan. Retention is enforced automatically, so you don't need to configure cleanup jobs or manage storage.

| Plan | Retention Period | Storage | SIEM Access |
| - | - | - | - |
| Baseline | 90 days | Shared infrastructure | Not available |
| Growth | 3 years | Shared infrastructure | Not available |
| Scale | 3 years (default), configurable | Dedicated AWS account | S3 bucket with full access |

### Baseline Plan Retention

Events older than 90 days are permanently deleted on a rolling basis. If you need to retain event logs for longer than 90 days for compliance or operational purposes, we recommend setting up a regular export schedule, weekly or monthly, to archive events in your own storage before they expire.

### Growth Plan Retention

Three years of event log history is retained by default, which meets the retention requirements of most compliance frameworks, including SOC 2 and ISO 27001. Events older than 3 years are permanently deleted on a rolling basis.

### Scale Plan Retention

Customers on the Scale plan retain 3 years of event log history in the Provisionr application by default, with the option to configure custom retention periods. Because Scale plan event logs are also written to S3 in your dedicated AWS account, you can manage S3 lifecycle policies independently to extend retention to 7 years (common for financial compliance and HIPAA), 10 years, or indefinitely. The S3 bucket's retention policy is entirely under your control, and it's independent of the application-level retention.

Scale plan customers can also configure S3 Object Lock with governance-mode retention, which prevents deletion of event log files during the retention period, even by AWS root account holders. This satisfies regulatory requirements for immutable audit trails.

### Deleting Expired Events

When event log entries reach the end of their retention period, they're permanently deleted from the database. Deletion runs in background batches during off-peak hours, so that it doesn't affect workspace performance. Deleted events can't be recovered, so if you need to preserve events beyond their retention period, export them before they expire.

## Monitoring and Alerting

Beyond serving as a record of what happened, event logs are also used to generate operational alerts and notifications.

### Error Notifications

When a sync encounters errors, such as failed API calls, rate limits, or unauthorized responses, Provisionr can notify your team through your configured notification channels. Error notifications include the event type, the affected record, the error details, and a direct link to the event log entry in your workspace.

### Sync Summary Notifications

After each scheduled sync completes, Provisionr can send a summary notification that shows the total number of changes made, any errors encountered, and the sync duration. This gives your team a quick daily or weekly view of what Provisionr is doing in your environment, without needing to check the event log by hand.

### Webhook Notifications

Customers on the Growth and Scale plans can configure webhook notifications that fire when specific event types occur. This allows you to build custom alerting, automation, or integration pipelines that are triggered by event log entries. For example, you could trigger a Slack notification when a user is removed from a critical security group, or send an event to your SIEM when an authentication failure occurs.

## Performance Metrics

Provisionr times its operations as they run. The elapsed time of each operation is written to our operational logs, and events that cover several records also store an average for each record in the `event_ms_per_record` and `duration_ms_per_record` fields. The event log API doesn't return these fields today, so timing isn't yet part of what you can query or export.

## Frequently Asked Questions

> [accordion] Deleting Event Logs
>
> You can't delete event logs from your workspace. There's no API endpoint, CLI command, or web interface action to delete an event, and the application refuses to edit an event or delete one permanently. Any soft delete is itself recorded as a new event, which protects the integrity of your audit trail for compliance purposes. Events are removed automatically only after your plan's retention period expires.

> [accordion] Plan Downgrades
>
> If you downgrade from Growth or Scale to Baseline, your retention period changes to 90 days, and events older than 90 days are deleted on a rolling basis after the downgrade takes effect. We recommend exporting your event log history before you downgrade.

> [accordion] Subscription Cancellation
>
> Event logs are included in the data that you can export when you cancel your subscription. You have 30 days after cancellation to export your data, including event logs, in JSON, CSV, or YAML format through HQ or the API.

> [accordion] Event Availability
>
> Events are written synchronously at the time of the operation, so they're available for viewing and querying immediately. There's no delay between an operation completing and its event appearing in your event log.

> [accordion] Provisionr Employee Access
>
> Provisionr employees don't have routine access to customer event logs. Access requires just-in-time authorization, and it's itself logged in a separate internal audit trail.

> [accordion] Manual Syncs
>
> Clicking the **Sync** button on any policy generates the same event log entries as a scheduled sync, including all membership changes. There's no difference in audit coverage between manual and scheduled syncs.

> [accordion] Correlating Events with Vendor Logs
>
> Vendor API events include the request identifiers that the vendor returned in its response headers, such as Okta's `x-okta-request-id` or Google's request trace ID. You can use these identifiers to cross-reference a specific API call in Provisionr's event log with the corresponding entry in your vendor's admin console or logs.

> [accordion] Interrupted Syncs
>
> If a sync is interrupted, for example by a deployment or an infrastructure restart, all events logged before the interruption are preserved. The interrupted sync is logged with an error result, and the next scheduled sync picks up where it left off, so no events are lost because of the interruption.

> [accordion] Undoing Changes
>
> Event logs record what happened, but they don't undo anything themselves. When a rule change granted or removed the wrong people, [Rule Rollback](https://docs.provisionr.io/integrations/okta/rollback) previews the reversal and makes it in one step, and it records its own events. For other changes, each membership change is logged with the specific group, user, and action taken, so you can use the event log to identify exactly what needs to be reversed. If a policy sync made incorrect changes, correcting the policy and running a new sync brings memberships back to the expected state.

> [accordion] First Sync of a New Policy
>
> When you create a new policy and run its first sync, Provisionr evaluates all users against the policy's rules and logs an event for each user who qualifies. If the corresponding vendor group already has members, Provisionr compares the policy's expected membership with the group's actual membership and logs additions, removals, and skips accordingly. With Okta, the first time a policy writes to a group, nothing is written until an admin confirms the changes, and that confirmation records events of its own, which [First Write-Back Confirmation](https://docs.provisionr.io/integrations/okta/incidents#first-write-back-confirmation) describes.

> [accordion] Event Volume Limits
>
> There's no hard limit on event volume. Workspaces that manage many policies across many vendors naturally generate more events. Provisionr's infrastructure manages storage and query performance, and customers on the Scale plan benefit from dedicated compute resources for event log storage and retrieval.

> [accordion] Alerts for Specific Event Types
>
> Customers on the Growth and Scale plans can configure webhook notifications that are triggered by specific event types or patterns. Customers on the Baseline plan receive error notifications through their configured notification channels. See [Monitoring and Alerting](#monitoring-and-alerting).

***

## Audit and Compliance Reference

This section describes the event log in terms of controls and evidence, including how its records are protected and which controls it supports.

### Immutability and Integrity

Provisionr protects event records from being changed, and that protection is built into the application rather than being an optional feature.

The API and CLI can only read events, so there is no endpoint or command to edit or delete one. Underneath them, the application itself refuses to update an existing event record or to delete one permanently, which means that nothing running through Provisionr can rewrite the trail, even by mistake.

An event record can be soft deleted, which hides it without destroying it. Every soft delete and every restore is itself recorded as a new event, `audit.log.soft_deleted` or `audit.log.restored`, with the actor that performed it and any justification they gave. This means that an event can't quietly disappear from the trail, because removing it leaves a record of its own.

### Storage-Level Immutability (Scale Plan)

Customers on the Scale plan benefit from S3 Object Lock with governance-mode retention. Once an event log file is written to S3, it can't be deleted or overwritten until the retention period expires. This provides storage-level immutability that's independent of the Provisionr application, so even if the application were compromised, the S3 event log files would remain intact.

### Internal Access Controls

Provisionr employees don't have routine access to customer event logs. Access to customer data requires just-in-time authorization through a controlled process, and all employee access to customer environments is itself logged in a separate internal audit trail.

### Mapping Controls to Evidence

Event logging is designed to satisfy the audit trail and monitoring requirements of major compliance frameworks. The table below maps Provisionr's event logging capabilities to specific controls.

| Framework | Control | How Event Logging Supports It |
| - | - | - |
| SOC 2 (TSC) | CC6.1 (Logical Access) | Every authentication event and access change is logged with actor identity |
| SOC 2 (TSC) | CC7.2 (System Monitoring) | Continuous logging of all operations with error detection and alerting |
| SOC 2 (TSC) | CC8.1 (Change Management) | All configuration and policy changes logged with before/after values |
| ISO 27001 | A.12.4 (Logging and Monitoring) | Comprehensive event logging with structured types and retention policies |
| ISO 27001 | A.9.2 (User Access Management) | Every group membership change logged with the policy rule that triggered it |
| NIST 800-53 | AU-2 (Auditable Events) | All security-relevant events are logged automatically |
| NIST 800-53 | AU-3 (Content of Audit Records) | Events include who, what, when, where, and outcome |
| NIST 800-53 | AU-6 (Audit Review) | Filtering, search, and export tools for reviewing audit records |
| NIST 800-53 | AU-9 (Protection of Audit Information) | Event records cannot be edited or permanently deleted, and every soft delete or restore is itself recorded |
| NIST 800-53 | AU-11 (Audit Record Retention) | Configurable retention from 90 days to indefinite |
| HIPAA | § 164.312(b) (Audit Controls) | Hardware, software, and procedural mechanisms to record and examine activity |
| HIPAA | § 164.308(a)(1) (Security Management) | Event logs support risk analysis and security incident tracking |

If you need a compliance-specific report or attestation related to event logging, contact your account team or [compliance@provisionr.io](mailto:compliance@provisionr.io).

### Known Limitations

The event log records what happened, but it doesn't undo anything. When a change needs to be reversed, the event log tells you exactly what to reverse, and the reversal itself, including a [Rule Rollback](https://docs.provisionr.io/integrations/okta/rollback), is a new change with its own events.

The protections on event records are enforced by the application. Events aren't signed or linked together with a hash chain, so the event log can't prove on its own that nobody with direct access to the database altered a record. For that reason, [Internal Access Controls](#internal-access-controls) and, on the Scale plan, [Storage-Level Immutability](#storage-level-immutability-scale-plan) are part of the same control.

Events are kept only for your plan's retention period. After that, they're permanently deleted and can't be recovered, so any evidence that you need to keep for longer has to be exported before it expires.

A soft deleted event is hidden from the trail rather than destroyed. When you review the trail for a period, include the `audit.log.soft_deleted` and `audit.log.restored` events, which show what was hidden or restored, by whom, and with what justification.

Progress summaries for each sync, and most `debug` events, are written to operational logs rather than to the event log. The per-record events are the evidence of record, so a review should rely on them rather than on sync summaries.

***

With the event log, every change in your workspace leaves a record that you can search, export, and share with an auditor. For the complete list of event types and their descriptions, see the [Event Log CLI Reference](https://docs.provisionr.io/cli/workspace/v1/audit-log/list.md). For questions about event logging or compliance, contact [support@provisionr.io](mailto:support@provisionr.io).


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