Tail and Query the Audit Stream

Use Audit when a request is denied, Approval is required, Delegation behaves unexpectedly, or an operator needs evidence for a run.

Prerequisites

• A zone and known time window or request ID.
• A trusted Admin client for automation; application credentials cannot read zone audit.
• Durable event-ID deduplication if exporting continuously.

Web Console Workflow

1. Open the web console for your deployment.
2. Select Audit.
3. Filter by zone, decision, event type, or request ID.
4. Open the event detail to inspect metadata, determining policies, and diagnostics.
5. Open the decision trace from the event for a full request-level view.

Automation workflow

import { AdminClient } from '@caracalai/admin'

const admin = new AdminClient({
  apiUrl: process.env.CARACAL_API_URL!,
  adminToken: process.env.CARACAL_ADMIN_TOKEN!,
})

const events = await admin.audit.list(process.env.CARACAL_ZONE_ID!, {
  decision: 'deny',
  limit: 25,
})

const trace = await admin.audit.explain(process.env.CARACAL_ZONE_ID!, events[0].request_id!)
console.log(trace.final_decision, trace.denied)

Useful filters

Filter	Use it for
Request ID	Stitch together STS, Gateway, adapter, and explain events.
Decision	Find denies, allows, or partial decisions.
Event type	Focus on Policy, Session, Delegation, Approval, or admin changes.
Time window	Investigate a run, incident, or rollout.

Ship events to a SIEM

Poll admin.audit.list with a bounded time window and persist the last processed event identity. Caracal does not expose a supported external audit-stream subscription API; Redis topics are runtime internals, not an application integration contract. Use Admin API list/export surfaces and forward events after deduplication.

Field	Type	Meaning
id	string	Unique event id; use as the dedup key.
zone_id	string	Zone the event belongs to.
event_type	string	What happened: exchange, decision, replay_detected, revocation, lifecycle events.
request_id	string	null
decision	string	null
evaluation_status	string	null
metadata_json	object	null
occurred_at / ingested_at	string	Event time and audit-service ingest time (RFC 3339).

Event detail (admin.audit.explain) adds the determining policies, policy-set version, manifest hash, and diagnostics for decision events - fetch it lazily from the SIEM for alerts rather than shipping it wholesale. Alert first on decision: "deny" spikes, replay_detected, and delegation events for sessions outside your expected label set.

What to capture in incidents

• request ID;
• zone ID;
• application ID;
• resource identifier;
• requested scopes;
• final decision;
• determining policies;
• diagnostics;
• session or Delegation IDs when present.

Related page: Audit and Request Traces.

Validate the export

Generate one allow, deny, approval, Delegation, and Gateway result. Confirm request correlation, ordering in the destination, replay-safe deduplication by event ID, and credential redaction. Expected result: an operator can move from a SIEM alert to the Caracal request trace without querying internal Redis.

Failure point: polling cursor

Do not use wall-clock time alone as an exactly-once cursor. Re-read an overlap window and deduplicate by event ID so late ingestion does not create gaps.

Next Step

Use Debug Authorization Decisions to turn a correlated deny into a focused correction.