# System Audit Logs | Operation | Syntax | | ------------------------------------------- | ------------------------------------ | | [List audit events](#list-audit-events) | GET /api/preview/system/audit | | [Export audit events](#export-audit-events) | GET /api/preview/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](#audit-events) for more details about the audit event object. ### 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 {% openapi src="" path="/api/preview/system/audit" method="get" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media) {% endopenapi %} 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: ```shell 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" ``` ### Export audit events Returns a paginated list of events, intended for exporting entries into an external log management system. {% openapi src="" path="/api/preview/system/audit/export" method="get" %} [openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media) {% endopenapi %} 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: ```shell curl -X GET "$VEZA_URL/api/preview/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" ``` {% hint style="info" %} **Question**: If a customer includes the `persisted_at` timestamp hard-coded in a script, and Veza only exports events for 1 month, what happens after a month? **Answer**: The `persisted_at` parameter is ignored if you send a `page_token` in the API call. It won’t matter if the date is more than 90 or 30 days in the past. {% endhint %} ### 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: ```json { "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" } ``` #### Identity | Field | Description | | ------------ | -------------------------------- | | `user_id` | Unique user identifier. | | `session_id` | Unique session identifier. | | `api_key_id` | Unique identifier of an API key. | | `email` | User email address. | #### Status | Field | Description | | -------------- | ------------------------------------ | | `grpc_code` | gRPC code indicating request status. | | `http_status` | HTTP status code of the response. | | `error_reason` | Details about a bad request. | #### Client | Field | Description | | ------------ | ------------------------- | | `ip` | Client IP address. | | `user_agent` | Client user agent string. | #### Event | Field | Description | | ------------ | ------------------------------------------ | | `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. | * `request` and `response` both only contain some whitelisted fields. Due to size limitations, the entire message is not recorded. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/audit-logs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.