Tail and Query the Audit Stream

Use audit when a request is denied, step-up is triggered, delegation behaves unexpectedly, or an operator needs evidence for a run.

Web Console Workflow

1. Open caracal web.
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, connector, and explain events.
Decision	Find denies, allows, or partial decisions.
Event type	Focus on policy, session, delegation, step-up, or admin changes.
Time window	Investigate a run, incident, or rollout.

What to capture in incidents

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

Related page: Audit and Request Traces.