Audit Trail for Configuration Changes

Learn how the platform records all configuration changes as audit events. Query the audit trail via API to see who changed what, when, and from what to

Overview

The platform captures every configuration change as an audit event, creating a comprehensive audit trail. This feature is designed to address governance requirements by providing a complete history of administrative actions. The audit trail answers the questions of who made a change, what was changed, when it happened, and what the configuration looked like before and after the change.

Audit events are integrated into the platform's observability user interface, allowing both operational and governance queries to be performed from a single location.

How It Works

The audit trail is a mandatory function of the control plane. Every action that mutates the platform's configuration automatically generates an audit event.

Audited Actions

An audit event is created for any change that could affect how API traffic is converted or who can administer the platform. This includes the following actions:

Service Management: Creating, updating, soft-deleting, and hard-deleting services.
Service Versioning: Activating a new service version or rolling back to a previous one.
Mapping Logic: Manual edits, regeneration, and overrides of request/response mappings.
Backend Profiles: Updates to backend endpoint URLs, authentication modes, timeouts, retry settings, and credentials.
Access Control: Changes to role-bindings, such as mapping identity provider (IdP) groups to platform roles or direct user role assignments.
Platform Settings: Modifications to any mutable system setting, including timeouts, retries, data retention policies, debug flags, and SMTP alert delivery configurations.

Audit Event Structure

Each audit event records a consistent set of fields to provide a full context for the change.

Field	Description
Actor email	The identity of the user or system that performed the action.
Actor role	The application role (e.g., `admin`, `operator`, `reader`) that the actor was using at the time.
Action type	The specific operation that was performed.
Before / after state	The state of the configuration before and after the change, allowing for a full reconstruction of the modification.
Correlation ID	A unique identifier to cross-reference the change with other related activities, such as logs or traces.
Result status	Indicates whether the action succeeded or failed.

IMPORTANT

Sensitive values, such as backend credentials, are never written to the audit trail in plaintext. When a credential is changed, the audit event records metadata about the change (e.g., that the credential was set or updated and when) but not the secret value itself. For more details, see backend credential encryption.

Querying the Audit Trail

You can retrieve audit history by making requests to the Admin API. The audit trail is paged on the server side to handle large volumes of data efficiently.

Example Request

The following example demonstrates how to query for audit events that occurred within the last 24 hours.

curl -X GET "https://<your-platform-host>/admin/v1/audit-events?window=24h&pageSize=50" \
  -H "Authorization: Bearer <API_TOKEN>"

The response will be a JSON object containing the first 50 events (pageSize=50) from the last 24 hours, along with pagination metadata to retrieve subsequent pages.

API Reference

`GET /admin/v1/audit-events`

Returns a paginated list of audit events.

Query Parameters

Name	Type	Default	Required	Description
`window`	string	—	No	The time window for the query. Can be a predefined value (`15m`, `1h`, `24h`, `7d`, `30d`, `60d`) or a custom range using `start` and `end` parameters. The source does not specify the format for `start`/`end`.
`page`	integer	—	No	The page number to retrieve.
`pageSize`	integer	—	No	The number of items to include per page.

Response Body

The API returns a JSON object with the following structure:

items[]: An array of audit event objects. The structure of these objects is detailed in the Audit Event Structure section.
page: The current page number.
pageSize: The number of items requested per page.
totalItems: The total number of audit events matching the query.
totalPages: The total number of pages available.

NOTE

For more details on the Admin API, see the Admin API reference documentation.

Retention

By default, audit events are retained for 60 days. This retention period is configurable to align with your organization's data retention policies. The retention model for audit events is the same as for the platform's other telemetry data.

For more information, see Data Retention.