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 for more details about the audit event object.
You can also browse audit events in the Veza UI. See .
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.
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:
Returns a paginated list of events, intended for exporting entries into an external log management system.
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:
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:
request and response both only contain some whitelisted fields. Due to size limitations, the entire message is not recorded.
The following fields give a human-readable summary of the action. These are the fields surfaced in the UI.
curl -X GET "$VEZA_URL/api/preview/system/audit?page_token=&page_size=1&filter=ended_at+GE+%222023-08-04T22:11:25.915674671Z%22" \
-H "authorization: Bearer $VEZA_TOKEN"curl -X GET "$VEZA_URL/api/v1/system/audit/export?filter=persisted_at+GE+%222023-08-07T22:11:25.915674671Z%22&page_size=5&next_page_token=" \
-H "authorization: Bearer $VEZA_TOKEN"{
"identity": {
"user_id": "aeaa34cf-e97f-4315-b185-249018cf191c",
"session_id": "b0ba024d-0158-4c7e-a47f-bbe8f7b98806",
"api_key_id": "",
"email": "cookie@cookie.ai"
},
"status": {
"grpc_code": "OK",
"http_status": 200,
"error_reason": "OK"
},
"client": {
"ip": "10.42.1.1",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36"
},
"endpoint": "/api_protos.v1.APIKeyService/CreateAPIKey",
"method": "POST",
"url": "/api/preview/keys",
"request_id": "1a98184880f9952551c53d836598b258",
"request": {
"name": "KeyName1"
},
"response": {
"value": {
"id": "fde4386f-3d85-4ef2-82d0-324dacb6e9ba",
"name": "KeyName1",
"team_id": "613df06e-9a40-4331-947c-5c327b54b228",
"user_id": "aeaa34cf-e97f-4315-b185-249018cf191c"
}
},
"started_at": "2023-07-26T08:23:17.134994459Z",
"ended_at": "2023-07-26T08:23:17.151080751Z"
}user_id
Unique user identifier.
session_id
Unique session identifier.
api_key_id
grpc_code
gRPC code indicating request status.
http_status
HTTP status code of the response.
error_reason
ip
Client IP address.
user_agent
Client user agent string.
endpoint
The API endpoint that was accessed.
method
The HTTP method used for the request.
url
action_name
Human-readable description of the action, such as Update Role Mapping.
outcome
Result of the action, such as Success or Failed.
resources
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 for details.
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.
Details about a bad request.
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.
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.
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
action_name and resource_type are resolved by cp-api at request time from the (audit.v1.method) proto annotation on the gRPC method and carried in the Kafka message so the auditor does not need proto reflection.
event_type is the unique, customer-facing identifier for classifying the event type and shape
event is the protojson form of the event encoded as a Struct so the
payload renders as a nested JSON object both at the DB column and across
the gRPC trailer wire format. Using bytes here would force protojson to
emit a base64-encoded string for what is otherwise structured data.
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
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"
}Veza API key for authentication. Generate keys in Administration > API Keys.
OK
action_name and resource_type are resolved by cp-api at request time from the (audit.v1.method) proto annotation on the gRPC method and carried in the Kafka message so the auditor does not need proto reflection.
event_type is the unique, customer-facing identifier for classifying the event type and shape
event is the protojson form of the event encoded as a Struct so the
payload renders as a nested JSON object both at the DB column and across
the gRPC trailer wire format. Using bytes here would force protojson to
emit a base64-encoded string for what is otherwise structured data.
Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
The type of the serialized message.
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"
}