Audit Event Schema

Every TealTiger decision generates a structured audit event. These events provide complete transparency into what happened, why it happened, and who initiated it.

Why audit events matter

Audit events give you:

Compliance evidence - Prove your AI is governed for auditors
Incident response - Investigate security issues with complete context
Cost tracking - Know exactly what each decision cost
Debugging - Understand why a decision was made
Traceability - Link decisions across distributed systems

Quick example

Here’s what a real audit event looks like:

{
  "schema": {
    "name": "tealtiger.audit_event",
    "version": "1.1.0"
  },
  "event": {
    "id": "evt_01HTY8K1W7Q9K9P7J9D1Y6S2ZZ",
    "type": "policy.decision",
    "timestamp": "2026-02-23T07:01:23.456Z",
    "severity": "INFO",
    "outcome": "ALLOW"
  },
  "actor": {
    "type": "user",
    "id": "user-123",
    "display_name": "[email protected]"
  },
  "policy": {
    "policy_id": "pol_cost_guardrails_001",
    "mode": "enforce",
    "decision": "ALLOW"
  },
  "signals": {
    "cost": {
      "estimated_usd": 0.0031,
      "tokens": {
        "input": 421,
        "output": 180
      }
    }
  },
  "reason_codes": [
    "COST.QUOTA.OK_WITHIN_LIMIT"
  ]
}

This event tells you: User [email protected] made a request that cost $0.0031, was allowed by policy pol_cost_guardrails_001, and stayed within budget limits.

Purpose

TealTiger v1.1.0 audit events make policy decisions:

Transparent - See exactly what happened
Explainable - Understand why through reason codes
Traceable - Link events across systems with correlation IDs
Auditable - Reproducible evidence for compliance

Audit events record:

Policy evaluation inputs and outputs (without leaking secrets)
Actions executed and their outcomes
Reason codes and risk scores for explainability
Correlation data for distributed tracing
Cost and performance metrics

Schema Overview

machine_spec:
  version: v1.1.0
  id: tealtiger.audit_event.schema
  type: audit_event_schema
  schema:
    name: tealtiger.audit_event
    version: "1.1.0"
  event_types:
    - policy.decision
    - policy.action
    - policy.error
    - policy.metric
  required_top_level_fields:
    - schema
    - event
    - correlation
    - actor
    - execution
    - policy
    - reason_codes
    - actions
    - redaction
    - extensions
  stability:
    promise: stable_within_v1_1_x
    breaking_changes: forbidden
    extensibility:
      allowed_namespace: extensions
      rule: additions_only

Schema identity

Each audit event includes schema identifiers for compatibility:

schema.name: fixed logical name for this schema
schema.version: semantic version of the event schema (v1.1.0 here)
event.type: event category (decision/action/error/metric)

Event Structure

machine_spec:
  version: v1.1.0
  id: tealtiger.audit_event.required_fields
  type: required_fields
  schema_fields:
    schema.name: string
    schema.version: string
    event.id: string
    event.type: string
    event.timestamp: string
    event.severity: string
    event.outcome: string
    correlation.trace_id: string
    correlation.span_id: string
    policy.policy_id: string
    policy.policy_version: string
    policy.mode: string
    policy.decision: string

This is the canonical event shape emitted by the SDK/runtime.
Your implementation may add fields under extensions.* as needed, without breaking compatibility.

Canonical JSON Shape (Conceptual)

{
  "schema": {
    "name": "tealtiger.audit_event",
    "version": "1.1.0"
  },
  "event": {
    "id": "evt_01HTY8K1W7Q9K9P7J9D1Y6S2ZZ",
    "type": "policy.decision",
    "timestamp": "2026-02-23T07:01:23.456Z",
    "severity": "INFO",
    "outcome": "ALLOW"
  },
  "correlation": {
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "span_id": "00f067aa0ba902b7",
    "request_id": "req_01HTY8JY2K3QJ9N8R4M8K2FZ1A",
    "session_id": "ses_9b0d9f2e3d1e4ac9",
    "parent_event_id": null
  },
  "actor": {
    "type": "service",
    "id": "svc_orders_api",
    "display_name": "orders-api",
    "tenant_id": "tenant_123",
    "org_id": "org_abc",
    "ip": "203.0.113.10",
    "user_agent": "tealtiger-sdk/1.1.0"
  },
  "execution": {
    "environment": "prod",
    "region": "ap-south-1",
    "runtime": "nodejs",
    "runtime_version": "20",
    "host": "ip-10-0-12-34",
    "deployment": "[email protected]"
  },
  "ai": {
    "provider": "openai",
    "model": {
      "name": "gpt-4.1-mini",
      "version": "2026-02-01"
    },
    "parameters": {
      "temperature": 0.2,
      "max_output_tokens": 512
    }
  },
  "policy": {
    "policy_id": "pol_cost_guardrails_001",
    "policy_version": "1",
    "mode": "enforce",
    "decision": "ALLOW",
    "matched": true,
    "matched_rules": [
      "rule_budget_soft_limit"
    ]
  },
  "signals": {
    "risk": {
      "score": 18,
      "level": "LOW",
      "version": "1.1.0",
      "domain_scores": {
        "security": 10,
        "cost": 20,
        "governance": 5,
        "reliability": 8
      }
    },
    "cost": {
      "estimated_usd": 0.0031,
      "tokens": {
        "input": 421,
        "output": 180,
        "total": 601
      },
      "budget": {
        "limit_usd": 10.0,
        "remaining_usd": 9.21,
        "window": "daily"
      }
    }
  },
  "reason_codes": [
    "COST.QUOTA.OK_WITHIN_LIMIT"
  ],
  "actions": [
    {
      "name": "log",
      "status": "SUCCESS",
      "details": {
        "destination": "stdout"
      }
    }
  ],
  "redaction": {
    "applied": true,
    "strategy": "metadata-only",
    "fields_redacted": [
      "input.prompt",
      "output.completion"
    ]
  },
  "error": null,
  "extensions": {}
}

Decision lifecycle: /concepts/decision-lifecycle
Author policies: /policy/policy-authoring-guide
Logging rules: /audit/logging-behavior
Cost attributes: /audit/cost-metadata

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Why audit events matter

Quick example

Purpose

Schema Overview

Schema identity

Event Structure

Canonical JSON Shape (Conceptual)

​Why audit events matter

​Quick example

​Purpose

​Schema Overview

​Schema identity

​Event Structure

​Canonical JSON Shape (Conceptual)

​Related Reading

Why audit events matter

Quick example

Purpose

Schema Overview

Schema identity

Event Structure

Canonical JSON Shape (Conceptual)

Related Reading