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).
- Open Audit in the tenant navigation.
- Filter by time range, user, action, entity type or free text.
- 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#
HTTPCopyGET /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:
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#
- Decide who can read the trail: RBAC and permissions.
- Set your audit window: Retention.
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