Audit & Evidence

Evidence is an immutable record of every authorization decision. It enables auditing, compliance, and debugging.

What is Evidence?

Evidence records every time AuthBoundry makes an authorization decision:

  • Who requested it (principal_id)
  • What they requested (capability)
  • What the decision was (ALLOW or DENY)
  • Why (which policy granted or denied it)
  • When (timestamp)
  • From where (application, tenant)

Evidence Structure

{
  "principal_id": "alice",
  "capability": "invoice.refund",
  "decision": "ALLOW",
  "reason": "Policy v3 grants invoice.refund",
  "timestamp": "2026-09-16T14:30:00Z",
  "application": "billing",
  "tenant_id": "acme-corp",
  "metadata": {
    "invoice_id": "INV-12345"
  }
}

Evidence Properties

Immutable

Evidence cannot be modified or deleted after creation.

Comprehensive

Every decision—ALLOW and DENY—is recorded.

Queryable

You can query evidence by principal, capability, application, time range, and decision.

Auditable

Use evidence to audit who did what, when, and why.

Querying Evidence

Common queries:

By Principal

Find all decisions for principal alice

By Capability

Find all invoice.delete requests (to see who has this capability)

By Decision

Find all DENY decisions in the last 24 hours (to see what was blocked)

By Application

Find all decisions in the billing application (to audit one app)

Use Cases for Evidence

Compliance Audit

"Who accessed customer data and when?"

Query evidence for data-related capabilities over a date range.

Incident Investigation

"Did this principal attempt to perform this action?"

Query evidence for specific principal + capability combinations.

Privilege Review

"What capabilities does each principal actually use?"

Query evidence to identify unused permissions. Remove unnecessary policies.

Security Investigation

"What actions were denied?"

Query evidence for DENY decisions. Investigate why they were denied.

Retention & Compliance

Retention Policy

Evidence is retained indefinitely unless you configure a retention policy.

Common retention periods:

  • 7 years (legal/compliance)
  • 1 year (operational)
  • 90 days (short-term audit)

Export & Reporting

Export evidence for compliance reports:

  • SOC 2 audits
  • GDPR access requests
  • Security incident reports

Evidence vs Logs

Don't confuse evidence with application logs:

  • Evidence: AuthBoundry's authorization decision log (immutable, comprehensive)
  • Logs: Application logs of what actually happened

Use both:

  • Evidence answers: "Was this allowed?"
  • Logs answer: "What did the application do?"

Privacy Considerations

Evidence records principal_id and capability, but not business data.

Example:

  • Evidence records: alice requested invoice.read
  • Evidence does NOT record: which specific invoices were read

Next Steps