# Audit

The Tenant API exposes the tenant audit log, which contains records of every user action, configuration change, and operation performed through the API. Required scope: **audit:read**.

## Fetch audit records [#fetch-audit-records]

API operations:

- `GET /v1/kyc/audit`

## Audit event types [#audit-event-types]

Events are classified by resource type.

### Verification sessions [#verification-sessions]

| Event              | Description                     |
| ------------------ | ------------------------------- |
| `session.created`  | Session created                 |
| `session.started`  | Session started                 |
| `session.approved` | Verification approved           |
| `session.rejected` | Verification rejected           |
| `session.expired`  | Session expired                 |

### Review [#review]

| Event             | Description                  |
| ----------------- | ---------------------------- |
| `review.assigned` | Task assigned to an operator |
| `review.started`  | Reviewer started the task    |
| `review.decided`  | Review decision made         |

### Flows (verification scenarios) [#flows-verification-scenarios]

| Event                         | Description                                          |
| ----------------------------- | ---------------------------------------------------- |
| `flow.created`                | Flow created                                         |
| `flow.updated`                | Flow updated                                         |
| `flow.cloned`                 | Flow cloned (copy created)                           |
| `flow.archived`               | Flow archived                                        |
| `flow.country_filter_changed` | Country filter changed in the `country_select` step  |
| `flow.deleted`                | Flow deleted                                         |

### API keys [#api-keys]

| Event             | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `api_key.created` | Key created                                                       |
| `api_key.updated` | Key parameters updated (scope, name, limits)                      |
| `api_key.rotated` | Key secret rotated                                                |
| `api_key.revoked` | Key revoked                                                       |
| `api_key.deleted` | Key deleted                                                       |

### Users [#users]

| Event                   | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `user.created`          | Account created                                     |
| `user.updated`          | Account updated                                     |
| `user.deleted`          | Account deleted                                     |
| `user.login`            | Sign-in                                             |
| `user.logout`           | Sign-out                                            |
| `user.login_failed`     | Failed sign-in attempt                              |
| `user.password_changed` | Password changed                                    |
| `user.password_reset`   | Password reset by an admin                          |

### Team (roles and invites) [#team-roles-and-invites]

| Event                         | Description                                       |
| ----------------------------- | ------------------------------------------------- |
| `team.invite_created`         | Team invite created                               |
| `team.invite_resent`          | Invite resent                                     |
| `team.invite_deleted`         | Invite deleted                                    |
| `team.member_removed`         | Member removed from the team                      |
| `team.role_changed`           | Member role changed                               |
| `team.permissions_changed`    | Member fine-grained permissions changed           |

### Settings and tenant [#settings-and-tenant]

| Event                  | Description                               |
| ---------------------- | ----------------------------------------- |
| `settings.updated`     | Settings changed                          |
| `tenant.created`       | Tenant created                            |
| `tenant.updated`       | Tenant updated                            |
| `tenant.suspended`     | Tenant suspended                          |
| `tenant.blocked`       | Tenant blocked                            |
| `tenant.unblocked`     | Tenant unblocked                          |
| `tenant.deleted`       | Tenant deleted                            |
| `tenant.force_logout`  | Forced sign-out of all users              |

### Applicants and businesses (KYC/KYB) [#applicants-and-businesses-kyckyb]

| Event               | Description                  |
| ------------------- | ---------------------------- |
| `applicant.created` | Applicant created            |
| `applicant.updated` | Applicant data updated       |
| `applicant.deleted` | Applicant deleted            |
| `business.deleted`  | Business deleted (KYB)       |

### Documents and media [#documents-and-media]

| Event                | Description                                |
| -------------------- | ------------------------------------------ |
| `document.uploaded`  | Document uploaded                          |
| `document.requested` | Reviewer requested resubmission            |
| `document.deleted`   | Document deleted                           |
| `selfie.uploaded`    | Selfie uploaded                            |

### Webhooks [#webhooks]

| Event                      | Description                              |
| -------------------------- | ---------------------------------------- |
| `webhook.configured`       | Webhook configuration changed (general)  |
| `webhook.endpoint_created` | Endpoint created                         |
| `webhook.endpoint_updated` | Endpoint updated                         |
| `webhook.endpoint_deleted` | Endpoint deleted                         |
| `webhook.secret_rotated`   | Endpoint secret rotated                  |
| `webhook.test_sent`        | Test webhook sent                        |
| `webhook.delivered`        | Webhook delivered successfully           |
| `webhook.failed`           | Webhook delivery failed                  |

### Verification links [#verification-links]

| Event                              | Description                                       |
| ---------------------------------- | ------------------------------------------------- |
| `verification_link.created`        | Verification link created                         |
| `verification_link.activated`      | Link activated by the applicant                   |
| `verification_link.sent`           | Link sent (email / SMS)                           |
| `verification_link.duplicated`     | Link duplicated                                   |
| `verification_link.bulk_action`    | Bulk action on links                              |
| `verification_link.revoked`        | Link revoked                                      |

### Sessions (admin operations) [#sessions-admin-operations]

| Event                | Description                                |
| -------------------- | ------------------------------------------ |
| `session.paused`     | Session paused by an operator              |
| `session.resumed`    | Session resumed by an operator             |
| `session.cancelled`  | Session cancelled by an operator           |
| `session.deleted`    | Session deleted                            |
| `session.exported`   | Session data exported                      |

### Manual review (extended actions) [#manual-review-extended-actions]

| Event                          | Description                                       |
| ------------------------------ | ------------------------------------------------- |
| `review.unassigned`            | Review task assignment removed                    |
| `review.priority_updated`      | Task priority changed                             |
| `review.comment_added`         | Comment added to a task                           |
| `review.resubmit_requested`    | Resubmission requested from the applicant         |
| `review.resubmit_cancelled`    | Resubmission request cancelled                    |

### Other [#other]

| Event                           | Description                                        |
| ------------------------------- | -------------------------------------------------- |
| `data.exported`                 | Data exported                                      |
| `deletion_request.created`      | Data deletion request created                      |
| `deletion_request.cancelled`    | Deletion request cancelled                         |

## Audit record structure [#audit-record-structure]

Every record contains the following fields:

| Field           | Description                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`            | Audit record UUID                                                                                                   |
| `tenant_id`     | Tenant UUID                                                                                                         |
| `actor_type`    | Actor type: `admin_user`, `superadmin_user` (actions by OneKYC support), `api_key`, `system`, `applicant`           |
| `actor_id`      | Actor UUID (or null for system events)                                                                              |
| `actor_email`   | Actor email (when available)                                                                                        |
| `action`        | Event type (see the lists above)                                                                                    |
| `resource_type` | Resource type: `session`, `applicant`, `document`, `selfie`, `flow`, `api_key`, `user`, `tenant`, `webhook`, `review` |
| `resource_id`   | Resource UUID                                                                                                       |
| `details`       | Object with detailed change information                                                                             |
| `created_at`    | Event time (ISO 8601)                                                                                               |

### `details` object structure [#details-object-structure]

| Field       | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `old_value` | Previous values (for update operations)                         |
| `new_value` | New values (for update operations)                              |
| `changes`   | List of changed fields                                          |
| `metadata`  | Extra context (IP address, session identifier, etc.)            |

## Retention period [#retention-period]

The audit record retention period follows the `data_retention_days` parameter of the tenant's billing plan. Records are removed automatically after the period elapses.

For long-term archival, run a periodic export through `GET /v1/kyc/audit` with a `created_at` range filter.

## Additional information [#additional-information]

- The lists above cover the most common action types. The full list is available in the **Audit** section of the admin panel (filter by the "Action" field).
- Audit records cannot be deleted through the API — they are read-only.
- Actions performed through the Tenant API are recorded with `actor_type = "api_key"`.
- Actions performed by OneKYC support are recorded with `actor_type = "superadmin_user"`.
- Confidential data (passwords, key secrets) is never included in `details`.
- For real-time event monitoring, use the WebSocket connection in the admin panel.

---

For the full data format specification, see the [API reference (OpenAPI)](/en/api/api-reference).