Skip to Content
KnowaKYC
Tenant API (KYC)

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

GET
/v1/kyc/audit

Authorization

ApiKeyAuth
headerAuthorization<token>

HMAC-SHA256 Credential=<key_id>, Signature=<hex_signature>. SignedHeaders=x-timestamp is optional. Requires X-Timestamp header.

Query Parameters

page?integer

Page (default 1)

page_size?integer

Page size (1-100, default 50)

action?string

Filter by action

actorId?string

Filter by actor UUID

dateFrom?string

From (RFC3339)

dateTo?string

To (RFC3339)

Header Parameters

X-Timestamp*string

Unix timestamp (seconds, max 5 min drift)

Response Body

Paged audit log items

*/*
  1. response
data?array<>
pagination?
success?boolean
Example Request
curl -X GET 'https://example.com/tenant/v1/kyc/audit' \  -H 'X-Timestamp: string'
Example Response
{  "pagination": {    "page": 0,    "page_size": 0,    "total_items": 0,    "total_pages": 0  },  "success": true,  "data": [    {      "action": "string",      "actor_email": "string",      "actor_id": "string",      "actor_type": "string",      "created_at": "string",      "details": {        "changes": [          "string"        ],        "metadata": {          "property1": null,          "property2": null        },        "new_value": {          "property1": null,          "property2": null        },        "old_value": {          "property1": null,          "property2": null        }      },      "id": "string",      "resource_id": "string",      "resource_type": "string",      "tenant_id": "string"    }  ]}

Audit event types

Events are classified by resource type.

Verification sessions

EventDescription
session.createdSession created
session.startedSession started
session.approvedVerification approved
session.rejectedVerification rejected
session.expiredSession expired

Review

EventDescription
review.assignedTask assigned to an operator
review.startedReviewer started the task
review.decidedReview decision made

Flows (verification scenarios)

EventDescription
flow.createdFlow created
flow.updatedFlow updated
flow.clonedFlow cloned (copy created)
flow.archivedFlow archived
flow.country_filter_changedCountry filter changed in the country_select step
flow.deletedFlow deleted

API keys

EventDescription
api_key.createdKey created
api_key.updatedKey parameters updated (scope, name, limits)
api_key.rotatedKey secret rotated
api_key.revokedKey revoked
api_key.deletedKey deleted

Users

EventDescription
user.createdAccount created
user.updatedAccount updated
user.deletedAccount deleted
user.loginSign-in
user.logoutSign-out
user.login_failedFailed sign-in attempt
user.password_changedPassword changed
user.password_resetPassword reset by an admin

Team (roles and invites)

EventDescription
team.invite_createdTeam invite created
team.invite_resentInvite resent
team.invite_deletedInvite deleted
team.member_removedMember removed from the team
team.role_changedMember role changed
team.permissions_changedMember fine-grained permissions changed

Settings and tenant

EventDescription
settings.updatedSettings changed
tenant.createdTenant created
tenant.updatedTenant updated
tenant.suspendedTenant suspended
tenant.blockedTenant blocked
tenant.unblockedTenant unblocked
tenant.deletedTenant deleted
tenant.force_logoutForced sign-out of all users

Applicants and businesses (KYC/KYB)

EventDescription
applicant.createdApplicant created
applicant.updatedApplicant data updated
applicant.deletedApplicant deleted
business.deletedBusiness deleted (KYB)

Documents and media

EventDescription
document.uploadedDocument uploaded
document.requestedReviewer requested resubmission
document.deletedDocument deleted
selfie.uploadedSelfie uploaded

Webhooks

EventDescription
webhook.configuredWebhook configuration changed (general)
webhook.endpoint_createdEndpoint created
webhook.endpoint_updatedEndpoint updated
webhook.endpoint_deletedEndpoint deleted
webhook.secret_rotatedEndpoint secret rotated
webhook.test_sentTest webhook sent
webhook.deliveredWebhook delivered successfully
webhook.failedWebhook delivery failed
EventDescription
verification_link.createdVerification link created
verification_link.activatedLink activated by the applicant
verification_link.sentLink sent (email / SMS)
verification_link.duplicatedLink duplicated
verification_link.bulk_actionBulk action on links
verification_link.revokedLink revoked

Sessions (admin operations)

EventDescription
session.pausedSession paused by an operator
session.resumedSession resumed by an operator
session.cancelledSession cancelled by an operator
session.deletedSession deleted
session.exportedSession data exported

Manual review (extended actions)

EventDescription
review.unassignedReview task assignment removed
review.priority_updatedTask priority changed
review.comment_addedComment added to a task
review.resubmit_requestedResubmission requested from the applicant
review.resubmit_cancelledResubmission request cancelled

Other

EventDescription
data.exportedData exported
deletion_request.createdData deletion request created
deletion_request.cancelledDeletion request cancelled

Audit record structure

Every record contains the following fields:

FieldDescription
idAudit record UUID
tenant_idTenant UUID
actor_typeActor type: admin_user, superadmin_user (actions by KnowaKYC support), api_key, system, applicant
actor_idActor UUID (or null for system events)
actor_emailActor email (when available)
actionEvent type (see the lists above)
resource_typeResource type: session, applicant, document, selfie, flow, api_key, user, tenant, webhook, review
resource_idResource UUID
detailsObject with detailed change information
created_atEvent time (ISO 8601)

details object structure

FieldDescription
old_valuePrevious values (for update operations)
new_valueNew values (for update operations)
changesList of changed fields
metadataExtra context (IP address, session identifier, etc.)

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

  • 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 KnowaKYC 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).

Metrics and analytics

Previous Page

Errors and limits

Next Page

On this page

Fetch audit recordsAudit event typesVerification sessionsReviewFlows (verification scenarios)API keysUsersTeam (roles and invites)Settings and tenantApplicants and businesses (KYC/KYB)Documents and mediaWebhooksVerification linksSessions (admin operations)Manual review (extended actions)OtherAudit record structuredetails object structureRetention periodAdditional information