Audit and Decision Records
This page explains what OpenProdkt records about decisions, approvals, and outcomes, what it does not record, who can read it, and how the records are exported and retained. Read it before you rely on the trail for an investigation or a review.
What the audit trail is
OpenProdkt keeps two related records of every governed decision:
- Audit events, an append-only sequence of events for each organization. You read them with
GET /v1/auditand in the Console Audit view. - Decision history, one item per recorded decision, with the asset, outcome, reason, policy, and the metadata the caller sent. You read it in the Console decision explorer and through the decision endpoints.
Both are written in the same transaction as the decision they describe, so a recorded decision always has its audit event.
Decision versus execution
The trail records what the control plane decided, and, only when a reporter says so, what happened afterwards.
- A decision is an authorization result. OpenProdkt does not execute your tool or request. It cannot see whether an allowed call ran, failed, or was never made.
- Execution is recorded only when the principal that received the
allowreports an outcome through the operation outcome endpoint (succeeded,failed, orunknown, with a completion time and an optional result hash). The MCP stdio wrapper reports outcomes automatically. The SDKs and the HTTP and gRPC proxy paths report them only if your application does so, either by calling the report method or by using the SDK one-shot outcome guard. - Outcome reports are an audit record only. They never change authorization, approval state, or billing.
- The first outcome for an operation is authoritative. Repeating an identical report, including identical optional correlation members, is accepted; a different one returns
409 operation_outcome_conflict. A report from a principal other than the one that received theallow, or for an operation that was not allowed, returns404 operation_not_found.
Paths with no outcome reporter
Some paths cannot report an outcome. The Envoy MCP path marks its decisions with outcome_reporting: none, and any allowed operation for which nothing is reported has no outcome. When you filter the audit by operation_id, the page then includes a read-time row operation.outcome.not_reported with outcome no_outcome_reporter. This means no reporter exists or reported. It does not mean execution failed or did not happen.
Coverage events
Availability. Coverage events exist only when the control plane build includes them and the operator has turned on outcome deadline monitoring, which is off by default. See Outcome deadline monitoring.
With monitoring on, the worker stores one of two events for an allowed operation that has no reported outcome. They are stored audit events with the actor worker, and GET /v1/audit returns them like other events (use the operation_id filter to find the ones for one operation).
| Event type | outcome | Meaning | When it is stored |
|---|---|---|---|
execution.outcome.missing | missing | The allow was issued, a reporter was expected, and no outcome had been reported when the deadline passed. | After the configured deadline has elapsed since the allow, and only if no outcome has been reported by then. |
execution.outcome.not_reportable | not_reportable | The allow came from a decision that declared outcome_reporting: none, so no reporter was expected. | When the worker next checks the operation, without waiting for the deadline, and only if no outcome has been reported. |
Each event payload carries the organization, operation_id, decision ID, asset ID, the deadline, the time the worker observed the gap, the outcome_reporting value and a reason (deadline_elapsed or reporting_disabled).
- A record, not an action. These are stored evidence records that a report was not received. They do not mean the operation failed, did not run or ran. They are not a decision, and the control plane takes no enforcement action because of them: it does not replay, re-execute, block or retry the call, and does not change authorization, approval state or billing. They do not authorize a retry.
- One per operation. The worker records at most one coverage result for an operation. If an outcome was already reported when the check ran, no coverage event is stored.
- Only after the cutover. The operator sets a start time when turning monitoring on. Allows issued before it get no coverage event, and nothing is backfilled.
- Late reports are still accepted. If the real outcome arrives after a coverage event, it is accepted as the first report and stored as
operation.outcome.reported. The coverage event is not edited or removed, so the trail shows both in time order. The control plane never writes asucceeded,failedorunknownoutcome for you. - Relation to the read-time row. For an allow that declared
outcome_reporting: none, a stored coverage event replaces the read-timeoperation.outcome.not_reportedrow described above, so the page does not show both. - Not exported. Coverage events are in the operational database like other mutable audit rows. The audit exporter does not copy them, so they have no write-once copy (see Export to write-once storage).
- Same limits as the rest of the trail. A coverage event is not tamper-proof, is not proof about what an upstream system did, and is not a compliance or certification claim. See Known limits of the trail.
What is recorded
| Event type | When | Notable content |
|---|---|---|
decision.evaluated | A decision is recorded for an application call | Decision ID, asset ID, result, winning policy ID, actor ID, operation ID, and approval recipients when approval is required |
decision.evaluation_failed | A policy could not be evaluated | Same fields, with the failing policy ID. The call was denied. |
decision.playground_evaluated | A Console playground evaluation | Same fields as a decision. Not an application call. |
approval.pending, approval.approved, approval.rejected, approval.expired, approval.revoked, approval.consumed | Approval lifecycle changes | Approval ID, decision ID, status, reviewer, and comment where one was given |
operation.outcome.reported | A reporter records an outcome | Operation ID, decision ID, asset ID, status, completion time, result hash, the reporting principal, and, when the reporter supplied them, execution_id, attempt and upstream_request_id |
execution.outcome.missing, execution.outcome.not_reportable | Outcome deadline monitoring is on and no outcome was reported (see Coverage events) | Operation ID, decision ID, asset ID, deadline, observation time, outcome_reporting and a reason. The actor is worker. |
asset.*, group.*, policy.*, member.*, api_key.*, webhook.* | Configuration changes (created, updated, deleted, and similar) | Resource ID and the actor |
asset.discovery.received, asset.discovery.skipped | Detection of an unregistered tool | Discovery details |
enforcement.mode.changed | A super admin changes the enforcement mode | Organization, actor, new mode, previous mode (see Enforcement Modes) |
enforcement.override.changed | A super admin sets, changes or removes a mode override | Organization, actor, dimension, value, mode, action (set or removed), previous mode when one existed (see Overrides) |
asset.definition.pinned | A super admin sets, changes or removes the approved definition pin of an MCP tool | Organization, actor, asset ID, action (set or removed), digest, canon, previous digest when there was one (see Definition Pinning) |
asset.definition.changed | A call carried a tool definition digest that differs from the pin | Pinned and observed digest, asset ID, server version when given, operation ID when valid, transport, time. Written by the background worker after a short delay, best effort, once per distinct pair and at most 20 per asset and pin; not exported. The same event name also records other asset changes, which differ in their legacy event type. |
killswitch.activated, killswitch.deactivated | A super admin turns a kill switch on or off | Organization, actor, scope, asset ID for an asset switch, switch ID, and the reason on activation (see Kill Switch) |
breakglass.requested, breakglass.approved, breakglass.rejected, breakglass.revoked | A break-glass grant changes state | Organization, grant ID, asset ID, actor, requester, and the reason, duration, expiry or note where they apply (see Break-Glass) |
breakglass.invoked, breakglass.expired | A grant allowed a strict deny, or reached its end | Grant ID, asset ID, and the original reason and decision ID, or the previous status and end time. Written by the background worker after a short delay; the invoked event is best effort. No free text. |
enforcement.denied | The organization is in strict, or an organization-wide kill switch is active, and a call for an unregistered asset was denied | Reason, mode, time, transport, operation ID when valid, and only a digest of the asset key. Written by the background worker after a short delay, best effort, not exported (see Enforcement Modes). Denied calls that have a decision record appear as decision.evaluated with result deny instead |
enforcement.would_deny | The organization is in observe and a call was allowed for no_matching_policy, no_policies_assigned or asset_not_registered | Reason, mode, time, transport, and decision, asset and operation IDs when they exist; only a digest for an unregistered asset key. Written by the background worker after a short delay, best effort, not exported (see Enforcement Modes) |
evidence.accessed | An auditor views an operation's detail | Operation ID, action view, user ID, role, and view time. Written by the background worker after a short delay (see Auditor access records). |
evidence.vault.settings.changed | A super admin turns the evidence vault on or off | Organization, actor, new value, previous value |
evidence.vault.gap | A decision or an outcome was recorded with a vault gap (a reason you reported, or absent). Written once per asset, side (input or output), reason and UTC day, by the background worker after a short delay | Organization, asset, side, reason, day. Never a pointer |
principal.erased | A super admin erases a pseudonym (see Pseudonymous Principals) | Organization, the pseudonym, the time and the actor who erased it. Never the person's id or address |
Each audit event has an id, eventType, actorId, resourceType, resourceId, outcome, a JSON payload, and createdAt.
What is not recorded
- Request content is not in audit events. The audit payload holds identifiers and results, not the metadata the caller sent. Decision history items do keep the request metadata, transport kind, MCP server and tool, and policy revision, so treat decision history as sensitive.
- Raw prompts and attachment content are rejected as metadata keys, so they are not stored.
- MCP tool arguments are stored only if you map them into metadata.
- Unregistered-tool calls are not recorded as decisions. They appear only as a discovery.
- Registered assets with no policy (
no_policies_assigned) are recorded but not billed. - Requests rejected before a decision (validation errors, authentication failures, rate-limit and quota rejections) are not decisions and have no decision record.
- Upstream effects. Without an outcome report, the trail does not show that an allowed operation ran.
- Reads. Most reads are not audited, including lists, the dashboard, API key and member reads, and operation reads by roles other than
auditor. The exception is an auditor's read of operation detail (see Auditor access records). - A decision-quota rejection is not recorded as a decision.
Trace and execution correlation
Callers can attach identifiers so that you can line up a decision, the call that followed it, and your own traces.
- Trace context. An evaluation may carry a W3C
traceparentheader. The control plane keeps a valid trace ID, adds its own span ID, returns the result in the responsetraceparentheader and stores both IDs with the operation. Invalid, duplicate or missing values start a new trace and are never an error. Formats and bounds are in Trace context. - Execution identifiers on outcomes. An outcome report may include
execution_id,attemptandupstream_request_id. They appear in theoperation.outcome.reportedevent and in the operation status. Formats and bounds are in Execution correlation on outcome reports. - Not stored by correlation. Raw tool arguments, request and response bodies,
tracestate,baggageand credentials are not stored for correlation. Decision history still keeps request metadata, as described above. - Reading the recorded trace. The operation detail endpoint returns stored trace and span IDs when present.
GET /v1/audit, decision history, the principal-bound operation status, webhooks and audit export do not include them. - No effect on decisions. Correlation is never policy input, is not part of approval binding and does not authorize a retry.
Asset risk classification records
When an asset is created with an ai_inventory, or a PATCH changes it, an asset.risk.classified record is written in the same database transaction as the asset change. The record names the asset and its type, carries the inventory members you submitted (including intended_purpose and any references), identifies the acting user or API key, and has a SHA-256 hash of its content. An unchanged resubmission writes no record. The regular asset.created and asset.updated events do not carry inventory members.
In the current implementation these records are kept in the operational database. They are not returned by GET /v1/audit, shown in the Console, sent to webhooks, or included in the audit export, so they have no write-once copy. The hash lets a holder of a record check that the record matches its own contents. It is not a signature or a hash chain, and it does not protect against someone who can change the database.
Who can read it
GET /v1/audit requires the audit:read scope on an API key, or a signed-in user. Users who are not organization-wide roles see only events and approvals for assets they own. Organization-wide roles see the whole organization. The auditor role is organization-wide and read-only. Roles are described in Access & Permissions.
GET /v1/audit accepts search, operation_id, limit, and offset. limit is 1 to 100 (default 25) and offset is zero or greater. Events are returned newest first, with total. An operation_id outside ^[A-Za-z0-9._:-]{1,128}$ returns 400.
Operation timeline in the Console
On the Audit page, enter an operation ID and choose Show timeline. Events returned for your access are displayed oldest first within Decisions, Approvals, Outcomes, Evidence access and Other lanes. Use the checkboxes to hide lanes, or Back to list to return to the normal audit list.
The timeline loads the newest 100 events at most. If more events exist, it warns that the displayed timeline is incomplete. An empty lane does not prove that nothing happened, and absence of an outcome event does not become a new missing outcome assertion. Attempt details and integrity verification are not shown. This view reads operational audit records, not reconstructed write-once evidence. Failed requests or malformed responses show an error rather than an empty timeline. Changing the operation or signed-in access context discards results from the previous request.
When a timeline is shown, the Console also loads an Operation detail panel from the operation detail endpoint. Requests are independent: a detail error never hides timeline events. The panel shows recorded operation, approval, correlation, first reported outcome and outcome expectation facts. Absent records are labeled neutrally. A missing or hidden operation reads "Not found or not visible", without distinguishing the cause. The outcome is a single first report, not attempt history, and an operation records one entry path, so mixed-path traces are not available. An Integrity section reads "Not verified": sealed-evidence verification and reconstruction are not available, so no integrity badge is shown. No principal claim is shown. If an auditor's access cannot be recorded, the panel shows "Access could not be recorded, so the detail was not shown. Try again." and nothing is retried automatically.
Operation detail
GET /v1/audit/operations/{operation_id} reads the recorded detail of an
allowed or approval-required operation. When both records exist, the allow
takes precedence. This is a read-only operational projection, not reconstructed
write-once evidence. Responses use Cache-Control: no-store.
Required members are version (operation-detail.v1) and operation_id.
Other members are omitted when absent:
| Member | Recorded information |
|---|---|
decision_id, asset_id | Decision and asset identifiers |
transport_kind | http, grpc or mcp; omitted for older records without transport |
outcome_reporting | none when the allow declares it cannot observe outcomes; otherwise omitted |
allowed_at | Allow time |
approval | status and optional expires_at, grant_expires_at, consumed_at, revoked_at |
correlation | One recorded trace_id and span_id, not a multi-hop trace |
outcome | The single first report, not a list of attempts |
outcome_expectation | state (pending, reported, missing, not_reportable), deadline_at, optional observed_at |
The outcome has operation_id, status (succeeded, failed, unknown) and
completed_at, plus optional result_hash, execution_id, attempt and
upstream_request_id. See execution correlation
for identifier formats and bounds. An absent member never proves execution
failure. Outcome expectations exist only when deadline monitoring applies.
Approval state is read live. Overall expiry is derived using the same precedence
as principal-bound operation status: an outcome, allow, consumption, revocation
or rejection takes precedence over expiry. Otherwise an elapsed approval reads
as expired. A revocation is represented by revoked_at, not a new status.
Access matches the audit trail: API keys require audit:read, signed-in users
use their existing role visibility, and audit entitlement must be available.
Organization-wide roles and API keys can read organization records; other users
can read only operations on assets they own. Audit reads do not evaluate a PDP
policy. The principal-bound proxy status endpoint remains unchanged.
The operation ID must match ^[A-Za-z0-9._:-]{1,128}$; invalid IDs return
400 invalid_operation_id. Missing, foreign-organization and not-visible
operations share 404 operation_not_found. A store failure returns
503 operation_detail_unavailable. For an auditor, 503 access_record_unavailable
means the view could not be recorded, so no detail was returned (see
Auditor access records). Existing credential, license
and rate-limit errors still apply.
Denied operations are timeline-only through GET /v1/audit?operation_id=.
Detail returns no principal/reporter identities, audit events, request content
or integrity verification result. It does not reconstruct sealed evidence,
infer attempts or authorize execution retries.
Outcome coverage
GET /v1/audit/outcome-coverage counts allowed operations by how their outcome is recorded. In the Console, open Audit, choose a range under Outcome coverage, and select Show coverage.
- What it counts. Only operations that were allowed (an
allowdecision). Denied and approval-required evaluations are not included. Counts are grouped by entry path (http,grpc,mcp, orunknownwhen the transport was not recorded) and byreporting:nonewhen the caller declared that it reports no outcome, otherwiseexpected. Groups with no operations are omitted, so an empty window returnsgroups: []. The response carries counts only: no operation IDs, asset IDs, principals or payloads. - States. Each operation is counted once. It is
reportedif an outcome report exists. Otherwise it takes the outcome expectation state (pending,missingornot_reportable) if one exists. Otherwise it isunmonitored.unmonitoredmeans no expectation was recorded and no outcome was reported. It does not mean the outcome is missing or failed. Expectations exist only while outcome deadline monitoring is on, and only for operations allowed after it was turned on.reportedincludes outcomes reported while monitoring was off. - Caveats. The response always includes a
caveatslist (each with acodeand amessage), and the Console shows every caveat next to the counts:allow_only,monitoring_default_off,reported_includes_unmonitored,mutable_projection, and, for callers limited to owned assets,owned_assets_only. - Query. Optional
fromandto, RFC3339, selecting operations allowed in the half-open window[from, to). Defaults:tois now andfromis 30 days earlier. The window can be at most 90 days. UseZ, or percent-encode a+offset as%2B. The response usesCache-Control: no-storeand carriesversion(outcome-coverage.v1),generated_at, thewindow,total_allowed,groupsandcaveats. Each group hasentry_path,reporting,totaland astatesobject with all five states (pending,reported,missing,not_reportable,unmonitored). - Limits and errors.
400withinvalid_from,invalid_toorinvalid_window(fromnot beforeto, or a window longer than 90 days).400 coverage_window_too_largewhen the window holds more than 250,000 allowed operations; narrow it.503 coverage_unavailableon a store failure or when the query exceeds its 5-second limit. Credential, entitlement and rate-limit errors still apply. - Access. Same as the audit trail: an API key needs
audit:read, the audit capability must be in your plan, users limited to owned assets see counts for those assets only, and organization-wide roles and auditors see the whole organization. Reading coverage is not itself audited. - Evidence vault. When your organization has the evidence vault turned on, the response also has a
vaultmember with aninputand anoutputside. Each side countsreferenced(a pointer was reported), one counter per gap reason (absent,key_service_unavailable,storage_unavailable,record_too_large,write_failed) andunrecorded(nothing was recorded, for example an operation from before you turned the vault on).inputcounts every allowed operation of the window andoutputonly those with a reported outcome, so each side adds up to the operations it counted. A pointer count is a count of claims: it does not show that a record exists. Without the vault the member is absent. - What it is not. The counts are a mutable operational projection computed when you ask, not write-once exported evidence. They are not a complete history (allowed operations only, expectations only while monitoring runs), and they are not proof of what an upstream system did.
Auditor access records
When a signed-in user with the auditor role successfully reads an operation's detail, the view is recorded as an evidence.accessed audit event.
- When it appears. The request records the intent, and the background worker writes the event afterwards. There is a short delay before it shows in
GET /v1/audit. Once written, it also appears in that operation's timeline, in the Evidence access lane, for organization-wide roles. Users limited to owned assets do not see it, because the event carries no asset reference. - Fail closed. If the access cannot be recorded, the request returns
503withaccess_record_unavailableand no operation data. Retry later; the Console never retries on its own. - What is recorded. The operation ID, the action (
view), the user ID, the user's role, and the time of the view. - What is not recorded. The request's query and any of the detail returned.
- What is not covered. Only an auditor's successful signed-in read of operation detail is recorded. Failed requests (
400,401,403,404) record nothing. Reads by other roles or API keys, list reads, and the coverage view are not recorded. - Not exported. Like other events outside the export list, it has no write-once copy.
evidence.exportedevents are not emitted yet.
Decision explanation export
GET /v1/decisions/{decision_id}/explanation returns a read-only decision-explanation.v1 summary of one stored decision. In the Console, super_admin and auditor users see Export explanation (JSON) on each decision in the Decision Explorer.
- Who. Signed-in
super_adminandauditorusers only. API keys are always refused with403, as are other roles. A decision that is missing, malformed or belongs to another organization returns the same404. Responses are not cached. - What it contains. The decision ID, asset ID and name, policy ID, name and revision, decision, result, status, error code, decision time, operation ID and transport when recorded, an approval summary (ID and status only), and a digest and key count of the request metadata.
- What it does not contain. Raw request metadata, tool arguments, request bodies, prompts, approval comments, and credentials are never included. Decisions do not store an evaluation trace or a reason text, so the file says the trace is not recorded and has no reason field. The policy engine is not run again.
- Not sealed evidence. The file is an operational summary computed when you ask for it. It is not write-once or sealed, and it is not recorded as an
evidence.accessedorevidence.exportedevent.
Export to write-once storage
The worker runs an audit exporter. It copies selected audit events to object storage that has Object Lock enabled.
- Which events. Only
decision.evaluated,decision.evaluation_failed, andoperation.outcome.reportedare exported. Approval lifecycle events are archived separately (see below). Configuration events and playground events are not exported by this exporter. - Not through webhooks. The exporter reads audit rows directly. These events do not pass through the webhook or notification path, and subscribing to a webhook does not create an export.
- Delay. A row is exported only after it is older than the export lag (default 60 seconds), and the exporter runs on an interval (default 300 seconds). A new decision can therefore be outside write-once storage for roughly the lag plus one interval, longer if an export cycle fails.
- Batching. The exporter writes sequence-ordered batches of up to the batch size (default 500) as newline-delimited JSON objects named by their sequence range. It stops at the first row that is not yet old enough, so rows are exported in order with no gaps.
- Format. Each line has
schemaVersion(1),seq,eventId,eventType,organizationId,actorId,resourceType,resourceId,outcome,occurredAt, andpayload. - Retries and duplicates. The export position advances only after a successful write. If the position update fails after a write, the next cycle rewrites the same object key. With Object Lock versioning that leaves an earlier version, so delivery is at-least-once. Consumers should deduplicate on
eventId. - Approval lifecycle records. For each approval lifecycle event the worker writes one locked JSON object per organization, approval, and event. Redelivery rewrites the same content. These records require the approval event to be dispatched, which needs the outbox dispatcher (
OPK_OUTBOX_DISPATCH_ENABLED) to be on.
Settings and their limits are in Limits and Configuration.
Retention, deletion, and integrity
S3 storage-conformance builds: Builds with the read-only startup conformance check also require any bucket default retention rule to use
COMPLIANCEand retain objects for at least the deployment's configured retention, never below 2555 days. AGOVERNANCEbucket default, a disabled lock or an unreadable lock configuration prevents startup. An absent default rule is allowed; individual exports still receive the configured retention. This check writes no test objects. Turning off optional evidence features does not skip these storage protections.
- Locked retention. Exported objects use provider-enforced retention: S3 Object Lock, or native Locked retention in builds with the Azure/GCS drivers. The duration defaults to, and cannot be set below, 2555 days (7 years). The worker refuses to start with a lower value. The mode defaults to
COMPLIANCE; S3 can useGOVERNANCE, which allows privileged principals to shorten or remove retention. Native Azure/GCS require COMPLIANCE and check that their object-retention capability is enabled; they do not have the full S3 conformance checks. See storage driver requirements. - Operational rows are mutable. Audit events, decision history, and approvals live in the operational database. They are protected by access control and by the application, which has no endpoint that edits or deletes audit events. They are not write-once at the storage level. Someone with database administrator access could alter them, and their retention follows how the operator manages the database.
- Only exports are write-once, and only after the delay above. Anything not yet exported, and any event type that is not exported, has no write-once copy.
- No claim of full immutability. OpenProdkt does not claim that the whole audit trail is WORM or that it satisfies a particular regulation. The Object Lock guarantee applies to the exported objects, within the mode and retention you configure, and to the storage service that enforces it.
- Integrity checking. Export lines carry sequence numbers, so a consumer can detect gaps. The exports are not cryptographically signed or hash-chained by OpenProdkt.
Known limits of the trail
- A decision is not proof of execution.
- Correlation is not a guarantee. Trace, execution and upstream request identifiers are supplied by callers or adapters and are not verified against your upstream systems. An
execution_idis a candidate the reporter chose, not proof that a call was dispatched. A reporter can omit them, and an operation has one outcome. Correlation is not tamper-proof and is not a compliance or certification claim. - Not available. These are not provided: a model-endpoint asset type, parsing of delegation or OAuth tokens, definition pinning on the MCP over HTTP route through Envoy, OpenTelemetry export, and injection of trace or correlation headers into upstream requests by the Envoy adapter.
- Order of audit events is by sequence within an organization;
createdAtis the server time at write. - The audit view reads the operational database, so its history depends on the operator's database retention.
- Coverage events are not enforcement or proof.
execution.outcome.missingandexecution.outcome.not_reportablerecord that no report was received. They do not show what an upstream system did, and they exist only when the operator has turned monitoring on. - The export covers a subset of events and lags by design.
- Coverage counts are a projection. Outcome coverage counts are computed on request from operational records and are not write-once.
unmonitoredis not a missing outcome. - The audit endpoint is paginated with a maximum page size of 100. For large reviews, use the export.
- Not available in the Console or API today. Integrity badges and verification, reconstruction from write-once storage, an evidence pack export, legal hold, a per-attempt history (an operation keeps its first reported outcome), mixed-path traces (an operation records one entry path), and a stored evaluation trace or reason text for the decision explanation export. The Integrity section reads "Not verified" for this reason, and the export is not recorded as an
evidence.exportedevent.
See also Security Model, Approvals, and Policy Engine.