Understand Decisions and Findings

An authorization record is APF’s evidence for one decision on one request. It says whether the request was allowed, why, under which policy, what policy observed in it, and what policy changed before it went out.

An Example

This is the shape of the record the middleware writes when the demo bundle redacts a secret from a plain HTTP request. Values are illustrative.

{
  "schema_version": "apf.audit.event.v1",
  "event_id": "<uuid>",
  "timestamp": "2026-10-07T10:15:02.118Z",
  "event_type": "authorization",
  "correlation_id": "<OpenShell request ID>",
  "enforcement_point_id": "apf-policy-gateway:middleware",
  "runtime_substrate": "openshell",
  "component": {
    "name": "apf-policy-gateway-middleware",
    "version": "0.1.0",
    "instance_id": "apf-policy-gateway:middleware@<host>"
  },
  "session_id": "<sandbox ID>",
  "bundle_digest": "<digest of the policy set the evaluator was built from>",
  "policy_revision": 2,
  "trust_root_id": "apf-policy-service:signing",
  "resource": { "type": "openshell.egress", "id": "httpbin.org" },
  "verb": "http.post",
  "decision": "allow",
  "decision_id": "<id>",
  "reason_code": "middleware.allowed_with_findings",
  "findings": [
    { "kind": "secret_detected", "label": "demo_secret", "severity": "critical" }
  ],
  "effects": {
    "payload_replaced": true,
    "header_mutations": [
      { "name": "x-openshell-middleware-apf-event", "action": "set" }
    ]
  }
}

Decision, Verdict, and Outcome

Three fields describe how something went. They are independent.

Where the Record Comes From

On a denial, error.code repeats the reason code, and error.message carries the policy’s own reason, such as security-content-gate/deny-secret or no grant for github_repo_write. A denial by a fail-closed policy information provider carries pip_<status>:<provider> there.

When the Enrichment stage ran, the record also carries extensions.x_apf_pip, with one entry per provider: its domain, which is the registration’s context, its provider name, status, whether it degraded, cached, which is always false in this release, its age_seconds, its evidence_ref, and its latency_ms. Refer to Policy Information Providers.

Refer to Supervisor Middleware for every middleware deny code.

Findings and Effects

Findings record what policy observed. Effects record what policy did.

effects is omitted when the request was not changed.

A finding does not change the decision, unless it cannot be resolved or the findings exceed the limits, which denies the request. A redaction record carries both: the finding that a secret was seen, and the effect that the body was replaced. Together they show the request was allowed, flagged, and neutralized.

Which Policy Decided

Each component names the policy it used by the digest of the document it actually used.

To join records across components for the same bundle, use policy_revision. Only the policy service records bundle_id. The gateway’s revision stays at the previous value when a bundle changes no rules, annotators, effects, or findings, and the interceptor’s provider and proposal governance records omit the revision.

Next Steps

• To trace a sandbox to its signed bundle, refer to Trace Policy Provenance.
• To walk a denial back to its rule, refer to Investigate a Denied Request.