# Audit log

> How the Agent Gateway records tamper-evident, cryptographically attested governance events, what each event category captures, and how to use the audit trail for compliance and post-incident review.
Policy decisions, trust registry checks, and credential delegation events are visible in the Logs page, but log entries are ephemeral and carry no cryptographic integrity guarantee. An auditor cannot use them as verifiable evidence of what the gateway authorised or denied. The Audit page provides a tamper-evident, persistent record of every significant governance decision the gateway makes. Each entry is embedded in a signed Verifiable Presentation, so the policy decisions it contains are cryptographically attested by the gateway’s own key.

You can demonstrate to auditors exactly what was authorised, by which agent, under which policy, with signed proof that the record was not modified after the fact. [Enable VP Auditing →](/products/affinidi-trust-fabric/agent-gateway/reference/configuration/settings.md#security-tab)

## Audit log vs. the Logs page

The gateway produces two distinct output streams. Both carry a trace ID, but they serve different purposes.

|  | Logs page | Audit log |
| What it records | All gateway activity: every routing decision, policy outcome, and error. | Significant governance events only: policy decisions, trust checks, and credential operations. |
| Persistence | Retained for operational diagnosis; configurable retention period. | Persistent, daily-rotating JSONL files with no volume cap. |
| Integrity | Structured log entries. | Each entry is embedded in a signed Verifiable Presentation, making policy decisions cryptographically attested. |
| Designed for | Real-time diagnosis during active incidents. | Compliance reporting, post-incident review, and credential delegation tracing. |

Use the Logs page to understand what happened on a specific request. Use the Audit page when you need durable, attributable evidence of governance decisions.

## Enabling VP Auditing

Prerequisite

VP Auditing must be enabled in Settings › Security before any audit entries appear. The Audit page shows no entries until it is turned on, regardless of traffic volume.

When enabling, choose which event categories to record. Each additional category increases storage in proportion to request volume.

| Category | What it records |
| Policy Decisions | OPA allow/deny outcomes for gateway, surface, MCP-tool, and response policy evaluations. |
| Trust Checks | TRQP recognition and authorisation query outcomes for every trust-registry verification. |
| Identity Bindings | Managed-identity VP injection events. |

See [Settings reference - Security tab](/products/affinidi-trust-fabric/agent-gateway/reference/configuration/settings.md#security-tab) for the configuration fields.

## Event categories

Once VP Auditing is enabled, the Audit page records events across six categories.

| Category | Triggered when |
| Policy Decisions | An OPA policy allows or denies a request at the gateway, surface, MCP-tool, or response scope. |
| Trust Checks | A TRQP trust registry query returns a result passed to OPA as trust_check_results. |
| Trace Terminated | A surface terminates a distributed trace at an organisational boundary and forwards a fresh trace ID downstream. |
| VP Injected | A Verifiable Presentation carrying the managed agent’s identity is injected into a proxied request or response. |
| Token Injected | A delegated credential from the vault is injected on the caller’s behalf. |
| Consent Granted | A user completes the OAuth consent flow and a delegation token is stored in the vault. |

### Policy Decisions

A gateway, surface, MCP-tool, or response OPA policy allowed or denied the request. Each entry records the policy scope (gateway or surface level), the flow direction (Access Point, Transit Point, or Fabric), the caller identity, and the denial reason from the policy rule where one was provided. The decision is attested in the signed VP’s policyDecisions claim.

Policy denials appear in the audit log regardless of how the Logs page is filtered, making the audit log the authoritative record of what was blocked and why.

### Trust Checks

A per-leg TRQP recognition or authorisation query to a connected [trust registry](/products/affinidi-trust-fabric/agent-gateway/concepts/connections/trust-registry.md) returned a result passed to OPA as trust_check_results. The entry records the authority queried, the entity checked, and whether the outcome was ok. When a trust check fails due to a network or protocol error, the entry includes an error code such as TRUST_REGISTRY_UNREACHABLE or AGENT_CARD_UNAVAILABLE.

### Trace Terminated

When a request crosses an organisational boundary, forwarding the caller’s trace ID to the downstream system would expose internal tracing details to an external party. The gateway keeps its own trace for the inbound leg and generates a fresh trace identifier for the outbound leg. The trace_terminated entry records the own and downstream trace ID mapping at the point of termination.

This mapping is the only record linking the two trace IDs. Without it, requests that cross gateway boundaries produce two unconnected traces with no way to establish which downstream trace corresponds to which inbound call. The audit entry bridges the gap without the original trace ID crossing the boundary.

### VP Injected

A Verifiable Presentation carrying the managed agent’s identity was injected into the proxied request or response. The entry records the agent identity DID, the agent endpoint DID used as the vault namespace, and a SHA-256 fingerprint of the VP JWT. The fingerprint allows a specific presentation to be identified and retrieved without storing the full JWT in the audit entry.

### Token Injected

A delegated credential from the vault was injected on the caller’s behalf. The entry records the credential provider and the caller identity. This is the outward side of Credential Delegation: when a token_injected entry is present, a per-caller OAuth token was transparently substituted for the shared application credential. See [Credentials](/products/affinidi-trust-fabric/agent-gateway/concepts/credentials.md) for how delegation tokens are stored and managed.

### Consent Granted

A user completed the OAuth consent flow and a delegation token was stored in the vault. Combined with token_injected entries, you can trace the full lifecycle from initial consent to per-request token injection.

## Cryptographic attestation

The audit log’s distinguishing property for compliance use is that policy decisions are cryptographically attested, not merely logged. Each entry is embedded in a signed Verifiable Presentation. The policyDecisions claim inside the VP carries the allow/deny outcome, the policy identifier, and the caller identity, signed by the gateway’s own key.

A policy decision in the audit log is verifiable: you can confirm the decision was made by this specific gateway and was not altered after recording. The vp_fingerprint field on each vp_injected entry provides a SHA-256 fingerprint of the signed presentation, enabling verification without storing the full VP JWT.

## Entry fields

Every audit entry carries a common set of fields regardless of event category.

| Field | Description |
| Timestamp | Precise time the event was recorded. |
| Event | Event category identifier: policy_decision, trust_check, trace_terminated, vp_injected, token_injected, or consent_granted. |
| Surface identifier | The identifier of the surface the request traversed. |
| Channel name | Human-readable surface name. |
| Caller | The authenticated caller’s DID, authentication method, and name or email where available. |
| Protocol | The surface protocol: a2a, mcp, or ap2. |
| MCP tool name | For MCP requests, the specific tool that was called. |
| Trace ID | Links this entry to its distributed trace and all related log entries for the same request. |
| VP JWT | The signed Verifiable Presentation. Present on vp_injected entries when the full JWT is stored. |
| VP fingerprint | SHA-256 fingerprint of the VP JWT. Present when the full VP is not stored inline. |

## Filtering

The Audit page supports four independent filter dimensions that can be combined with a free-text search.

| Filter | Options |
| Category | All / Policy Decisions / Trust Checks / Trace Terminated / VP Injected / Token Injected / Consent Granted |
| Decision | All / Allow / Deny |
| Flow | All / Access Point / Transit Point / Fabric |
| Type | All / Gateway / Surface / MCP Tool / Response |

The free-text search matches caller DID, surface identifier, channel name, and denial reason. Filters apply across the full dataset and entries are paginated in sets of 50.

## Event detail panel

Selecting an entry opens a detail panel with a plain-language summary of the event, such as “Denied POST /tools/call to surface-name” or “VP injected for did:webvh:…”. The panel includes four correlated sections derived from all audit events that share the same trace_id.

  Request journeyA vertical timeline of pipeline events for the request, in order. Shows which trust checks ran, which policy evaluated, and whether a VP was injected, all in sequence.
  Root of trustA ladder showing the recognition edges and signing gateway. Each rung identifies a DID recognised by the trust registry and its role in the chain. Human-readable DID names are resolved where available.
  Signed presentationThe decoded VP JWT or its fingerprint. When a VP is present, the panel shows the embedded policyDecisions count and the full decoded payload. This is the signed evidence you would present to an auditor.
  Raw fieldsThe remaining entry fields not surfaced in the other sections, organised into labelled groups.

## Credential delegation audit

Credential delegation events appear in two places, serving different reporting needs.

  Main Audit pageAll delegation events across every credential provider: token_injected, consent_granted, and error variants refresh_failed, token_revoked, and token_not_found. Use for cross-provider compliance reporting.
  Credential Tokens tabA per-provider delegation history on the Credentials page, scoped to one credential provider at a time. Use to investigate a specific provider's activity.

## Related

- [Settings reference - Security tab](/products/affinidi-trust-fabric/agent-gateway/reference/configuration/settings.md#security-tab): Enable VP Auditing and select the event categories to record.

- [Observability](/products/affinidi-trust-fabric/agent-gateway/concepts/observability.md): Distributed traces, metrics, logs, and the other dashboard monitoring tools.

- [Credentials](/products/affinidi-trust-fabric/agent-gateway/concepts/credentials.md): How credential delegation works and where tokens are stored.

- [OPA policies](/products/affinidi-trust-fabric/agent-gateway/concepts/opa-policies.md): How the gateway evaluates Rego policies and what request context each policy receives.

- [Trust registries](/products/affinidi-trust-fabric/agent-gateway/concepts/connections/trust-registry.md): How the gateway queries external registries during trust checks and passes results to OPA as trust_check_results.