Trace One Protected Request
This tutorial shows how to prove what happened during one protected request. You will find the request, inspect the session context, review audit events, and trace the final decision.
The flow assumes you already completed Protect Your First Real API and Connect Your App with the SDK.
1. Find the Request
Section titled “1. Find the Request”Open the Console:
caracal consoleUse these Console entries:
| Entry | Use it for |
|---|---|
| audit | Find recent authorization and action-result events. |
| request trace | Explain one request ID. |
| agent session | Find the tracked agent session for the selected zone. |
| authority session | Inspect underlying authority sessions and parent relationships. |
Record the request ID from the SDK, Gateway, STS error, audit event, or Console trace.
2. Read the Audit Timeline
Section titled “2. Read the Audit Timeline”Open audit. The live audit view opens recent events immediately and supports request details, request tracing, advanced filters, reload, and pause/resume.
A Gateway-routed protected call usually produces:
| Event class | What it proves |
|---|---|
| Authorization event | STS evaluated policy for the app, resource, scopes, agent session state, and delegation context. |
| Action-result event | Gateway verified and routed the request, then recorded the upstream result. |
If you see authorization events without matching action-result events, check whether the call reached the Gateway. For connector-verified services, confirm the service writes its own result audit after mandate verification.
3. Trace the Decision
Section titled “3. Trace the Decision”Pick an audit event with a request ID. Press the trace action on the selected event in audit, or open request trace and paste the request ID.
The request trace should show:
- application and execution session;
- resource and requested scopes;
- policy set version and policy rules involved;
- allow, deny, or partial decision;
- diagnostics from policy evaluation;
- delegation edge constraints when present.
Use the request trace as the source of truth for why a request got its result. If an app behaves differently than expected, compare the trace against the active policy set, resource configuration, and runtime profile.
4. Check Delegation Context
Section titled “4. Check Delegation Context”If the request used delegated authority, open delegation and inspect the edge:
| Field | Why it matters |
|---|---|
| Source session | The session that granted authority. |
| Target session | The session allowed to use the delegated permission. |
| Scopes | The narrowed actions. |
| TTL and hop limits | The lifetime and graph depth of the permission. |
| Resource constraints | The targets the delegated permission can affect. |
Use Implement Multi-Agent Delegation when you need to design or debug delegation flows.
5. Check Revocation Behavior
Section titled “5. Check Revocation Behavior”Revoking a session, grant, delegation edge, or zone/application emergency state invalidates authority anchored to it. Gateway-routed calls check revocation before accepting a request and while streaming responses. Audit records revocation events and marks interrupted action results.
Wrap Up
Section titled “Wrap Up”You can now trace one protected request from application identity to policy decision, Gateway action, delegation context, and revocation state.
Next Step
Section titled “Next Step”Continue with Choose Your Production Integration Path.