System Audit Logs
Endpoints for monitoring Veza user activity
GET /api/preview/system/audit
GET /api/v1/system/audit/export
Audit Logs record every API call, providing a record of actions conducted within Veza. Depending on your use case, you can export a continuous list of events, or get events matching a filter in chronological order. Developers, administrators, and security teams can use these requests to:
Integrate Veza with an SIEM platform or other auditing tools
Detect potential inappropriate access or usage
Get insight into how users are interacting with the Veza platform
See Audit events for more details about the audit event object.
You can also browse audit events in the Veza UI. See Audit Log.
Pagination
Responses will include a next_page_token. Use this page_token in the request query to get the next batch of results.
Setting a page size is required for requests. The maximum page size is currently 10,000 records.
List audit events
Veza API key for authentication. Generate keys in Administration > API Keys.
Filter expression (required). Must include an ended_at GE timestamp filter that is within the last 90 days. Supports filtering by ended_at, method, user_id, and url. Cannot be set when page_token is provided. Example: ended_at GE "2025-01-01T00:00:00Z"
Number of results per page (required). Minimum: 1, maximum: 10,000.
Pagination token from a previous response. When provided, the filter parameter must not be set — the page token carries forward the original filter constraints.
OK
Default error response
GET /api/preview/system/audit?filter=text&page_size=1 HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"values": [
{
"id": "text",
"timestamp": "2026-01-01T00:00:00.000Z",
"intent": {
"trace_id": "text",
"user_id": "text",
"session_id": "text",
"api_key_id": "text",
"oauth2_token_id": "text",
"endpoint": "text",
"method": "text",
"url": "text",
"client": {
"ip_address": "text",
"user_agent": "text"
},
"request": {},
"delegate": "text",
"actor_full_name": "text",
"token_type": "text",
"actor_type": "text",
"action_name": "text",
"resource_type": "text",
"resources": [
{
"id": "text",
"name": "text",
"type": "text"
}
]
},
"result": {
"code": 1,
"error_reason": 1,
"response": {},
"resources": [
{
"id": "text",
"name": "text",
"type": "text"
}
],
"context_events": [
{
"event_type": "text",
"event": {}
}
]
}
}
],
"next_page_token": "text"
}This endpoint supports filtering by ended_at timestamp, method, user_id, and url. Results are ordered by time completed.
A timestamp filter is always required. The API allows querying events for up to 90 days in the past.
Example:
Export audit events
Returns a paginated list of events, intended for exporting entries into an external log management system.
Veza API key for authentication. Generate keys in Administration > API Keys.
OK
Default error response
GET /api/v1/system/audit/export HTTP/1.1
Host: your-tenant.vezacloud.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"values": [
{
"id": "text",
"timestamp": "2026-01-01T00:00:00.000Z",
"intent": {
"trace_id": "text",
"user_id": "text",
"session_id": "text",
"api_key_id": "text",
"oauth2_token_id": "text",
"endpoint": "text",
"method": "text",
"url": "text",
"client": {
"ip_address": "text",
"user_agent": "text"
},
"request": {},
"delegate": "text",
"actor_full_name": "text",
"token_type": "text",
"actor_type": "text",
"action_name": "text",
"resource_type": "text",
"resources": [
{
"id": "text",
"name": "text",
"type": "text"
}
]
},
"result": {
"code": 1,
"error_reason": 1,
"response": {},
"resources": [
{
"id": "text",
"name": "text",
"type": "text"
}
],
"context_events": [
{
"event_type": "text",
"event": {}
}
]
}
}
],
"next_page_token": "text"
}To ingest events as they become available without skipping any entries, first make call with a persisted_at GE "TIMESTAMP" filter. Then, continuously call the next page. The export endpoint can return the error code ResourceExhaused. If encountered, clients should wait for a minute before retrying the request.
Example:
Audit events
An event describes an API-level action, including the IP address and user agent of the caller. Requests can originate from user sessions, or from applications using API keys. The following is a sample event for a successful API key generation:
Identity
user_id
Unique user identifier.
session_id
Unique session identifier.
api_key_id
Unique identifier of an API key.
email
User email address.
full_name
Display name of the actor (user or API key).
type
Actor type, such as USER, API_KEY, or SERVICE_ACCOUNT.
Status
grpc_code
gRPC code indicating request status.
http_status
HTTP status code of the response.
error_reason
Details about a bad request.
Client
ip
Client IP address.
user_agent
Client user agent string.
For audit entries recorded between the July 20 and August 10, 2026 releases, client.ip recorded an internal address (such as 10.x.x.x) instead of the public client IP. A later release resolves the issue, and the original public IPs from this window cannot be recovered. See Audit Log for details.
Event
endpoint
The API endpoint that was accessed.
method
The HTTP method used for the request.
url
The URL of the request.
request_id
The unique identifier for the request.
request
The contents of the API request.
response
Excerpt of the API response.
started_at
RFC 3339 timestamp when the event started.
ended_at
RFC 3339 timestamp when the event ended.
requestandresponseboth only contain some whitelisted fields. Due to size limitations, the entire message is not recorded.
Action and resources
The following fields give a human-readable summary of the action. These are the fields surfaced in the Audit Log UI.
action_name
Human-readable description of the action, such as Update Role Mapping.
outcome
Result of the action, such as Success or Failed.
resources
The resources the action affected, each with an id, name, and type. Empty for list and system-wide actions.
context_events
Related changes captured with the action, such as the specific role mappings added or removed.
Last updated
Was this helpful?