Audit trail
Overview​
Enterprise h2oGPTe streams a record of security-relevant user actions to the H2O AI Cloud (HAIC) Audit Trail service for compliance and governance tracking. The audit trail answers "who did what, where, and when" for direct end-user actions in the platform.
The audit trail is a platform-level compliance feature. Your deployment administrator enables it at the infrastructure level — it's not a setting available inside Enterprise h2oGPTe's System Dashboard, and audit events themselves are never visible inside Enterprise h2oGPTe's own interface. It's also separate from the Live Logs page in the System Dashboard, which shows application logs rather than a compliance-grade audit record.
h2ogpt:
config:
cloudConfigurations:
auditTrail:
enabled: true
Audit events are viewed in the HAIC Audit Trail UI, or its REST/gRPC read API. Contact your deployment administrator for access to your environment's Audit Trail UI.
What gets audited​
The audit trail only records direct end-user actions — actions a user explicitly triggers through the UI or API. A small number of asynchronous background jobs that directly correspond to a user action (such as collection deletion or document ingestion) are also recorded, but most other background job types, along with automated processes that aren't triggered by a user action (such as scheduled syncs) and internal service-to-service calls, are excluded.
Most operations produce an audit event only when they succeed. If a user attempts an action that fails (for example, due to insufficient permissions or a database error), no audit event is recorded. Guardrail violations always produce an audit event. A chat turn produces one once it starts running, whatever its outcome, unless its chat is deleted before the turn finishes.
Audited operations cover the following domains:
| Domain | Actions covered |
|---|---|
| Collections | Create, update, delete; share or unshare with a user, group, or all users; make public or private; set or reset the prompt template, collection settings, chat settings, or RAG type — see Collection lifecycle for the complete list |
| Chat sessions | Create a session; delete sessions; delete individual messages within a session |
| Chat messages | Submit a chat turn (actions/h2ogpte/chatMessages/CREATE). The event records the models that received the turn in metadata.models and the turn's entry point in metadata.source, such as web, rest-api, or openai-api; for WebSocket chats the client reports this value. Generating an AI assistant or scheduled task spec records up to three turns. The question and answer text are never recorded. Scheduled task and AI assistant runs aren't audited, including runs started with Run now or Wake now. The Run now action itself is recorded. |
| Model calls | Ask a model directly through the answer_question, summarize_content, or extract_data endpoints (actions/h2ogpte/models/ANSWER_QUESTION, SUMMARIZE_CONTENT, or EXTRACT_DATA). The event records the model that answered in metadata.models, and its status.code is OK, PERMISSION_DENIED when a guardrail blocked the call, or UNKNOWN when it failed. The text sent is never recorded. |
| Documents | Ingest a document (upload or plain text only — cloud storage, website, and filesystem ingests are not yet audited); delete documents |
| Roles and permissions | Create/delete a role; add/remove a role to or from a user or group; reset roles; assign or add permissions; set role priority; set or bulk-delete role configuration; set the default role |
| User groups | Create a group; delete groups by ID or by name |
| API keys | Create a key (including collection- or user-scoped keys); deactivate a key; set expiration; set the inactivity interval; admin-initiated deletion |
| Secrets | Create, update, delete |
| Configuration | Set global or user configuration; bulk-delete global or user configuration; reset user configuration |
| User management | Delete a user |
| Guardrails | Guardrail violation (blocked prompt or response) |
Additional domains are planned for future releases. The preceding table reflects the operations audited in the current release.
Earlier releases recorded principal as users/<h2ogpte-user-id>. New events use the platform user ID instead. A saved search or security information and event management (SIEM) rule that filters on the old value no longer matches new events. To match them by the old ID, filter on metadata.h2ogpte_user_id.
What an audit event contains​
Each audit event captures the actor, the action, the affected resource, and the actor's IP address. Events include resource-identifying metadata (such as role names and configuration keys) but exclude the data values themselves. For example, creating a role produces an event with fields similar to:
| Field | Example value |
|---|---|
action | actions/h2ogpte/roles/CREATE |
eventSource | h2oai-h2ogpte-mux |
principal | users/<platform-user-id>, the user's H2O AI Cloud ID. Guests and users without a platform identity appear as users/<h2ogpte-user-id>. |
metadata.h2ogpte_user_id | <h2ogpte-user-id> (only when principal holds the platform user ID) |
resource | //h2ogpte/<workspace>/roles/<role-uuid> |
workspace | workspaces/<workspace-uuid> (carried in the event's metadata) |
status.code | OK |
eventTime | Timestamp of when the event was recorded (typically within seconds of the action) |
type | TYPE_API |
Most events have a status.code of OK. Guardrail violation events use PERMISSION_DENIED. A chat turn's status.code gives its outcome:
OK: the turn produced an answer, including a partial answer the user stopped.CANCELLED: the turn stopped before producing any answer text.PERMISSION_DENIED: a guardrail blocked the turn.UNKNOWN: the turn failed.
Sensitive values are never included in audit events​
Operations that handle secrets or credentials, such as creating an API key or updating a configuration value, are scrubbed before the event is recorded. For example, an API key creation event includes the key's identifier but never the plaintext key value itself. This scrubbing happens automatically; there's nothing for end users or administrators to configure.
Accessing audit trail data​
Events typically appear in the Audit Trail UI within 30 seconds of the action. To review them:
- Open the HAIC Audit Trail UI for your environment (your deployment administrator can provide the URL).
- In the Event Source filter, enter
h2ogpte-muxto see only Enterprise h2oGPTe events. - Sort by event time to review the most recent activity first.
If your environment doesn't show expected events in the HAIC Audit Trail UI, ask your deployment administrator to confirm the audit trail integration is enabled and correctly configured for your deployment.
Related topics​
- Roles and Permissions - Manage the roles and permissions whose changes are recorded in the audit trail
- Secret manager - Manage secrets whose lifecycle events are recorded in the audit trail
- API key management - Manage API keys whose lifecycle events are recorded in the audit trail
- Live logs - Application-level logs, distinct from the compliance-grade audit trail
- Collection lifecycle - Detailed reference for collection-related audit events
- Submit and view feedback for this page
- Send feedback about Enterprise h2oGPTe to cloud-feedback@h2o.ai