Audit log

What the VeloPhex audit trail records, how to search it in the web app and the API, and how long it is kept.

The Orchestrator writes an audit event for every security-relevant change: sign-ins, role and membership changes, tokens, OAuth applications and sign-in grants, assets and credentials, packages, jobs, queues, triggers and machines. Events are append-only. They cannot be edited or deleted through the web app or the API; only the retention sweep removes them once they pass the tenant's audit window.

What an event contains#

Field Meaning
scope Platform (platform administration, sign-ins) or Tenant
actorType User, Runner (a Robot), Runtime (a running automation), Application (a third-party application on client credentials), System or Anonymous
actorId, actorName Who acted
action What happened, for example a role assignment or a Robot being disabled
entityType, entityId What it happened to
data Details of the change as JSON, never including secret values
correlationId Ties the event to the request that caused it and to the API log line
ipAddress The client address, taken from X-Forwarded-For only when the request came through the trusted proxy
occurredAt When it happened (UTC)

Why the trusted proxy matters here

If VELOPHEX_TRUSTED_PROXY_NETWORK is wrong, every audit record stores the proxy's address instead of the client's. The API refuses to start without a value. See Network and firewall.

The actorType value Runner is the contract name for a Robot; it appears in API responses unchanged.

Search the audit trail in the web app#

Prerequisites: a role with audit.view in the tenant (Administrator has it).

  1. Open Audit in the tenant navigation.
  2. Filter by time range, user, action, entity type or free text.
  3. Open an event to see its full data and correlation id.

You should see the newest events first. Platform administrators see sign-ins and platform administration in the platform admin area.

Search it with the API#

HTTPCopy
GET /api/v1/tenants/{tenantId}/audit?from=2026-01-01T00:00:00Z&search=invoice&page=1&pageSize=50
Authorization: Bearer vpx_pat_…

Supported filters: from, to, actionType, action, user, userNumber, entityType, entityId, search, plus page and pageSize. Every route needs audit.view. Other routes:

Route Returns
GET /api/v1/tenants/{tenantId}/audit/{eventId} One event
GET /api/v1/tenants/{tenantId}/audit/by-number/{number} One event by its integer handle
GET /api/v1/platform/audit The platform-scope trail (platform administrators)

Every query is scoped to one tenant. An event from another tenant answers 404.

Correlate an event with logs#

Each API response carries an X-Correlation-ID header and error responses include correlationId. The same id is on the audit event and on the API's JSON log lines, so you can go from a change in the audit trail to the exact request in the logs:

BashCopy
docker compose -f docker-compose.core.yml logs api | grep '<correlation id>'

Retention#

Audit events are kept for the tenant's audit window. The platform default is 365 days, and a tenant administrator can set any value from 90 to 2555 days in the retention settings group. The retention sweep deletes events past the window every hour. See Retention.

Keep evidence longer than the window

If your compliance program needs audit evidence for longer than you want to keep it in the Orchestrator, include the database in your regular backups and keep backups for the period you need. See Backup and restore.

Webhooks for operational events#

Operational events such as job failures, Robots going offline or packages being published can be pushed to your systems as signed CloudEvents. These are a separate stream from the audit trail. See Webhooks.

Next steps#

What an event contains

Search the audit trail in the web app

Search it with the API

Correlate an event with logs

Retention

Webhooks for operational events

Next steps