Query a delegation chain
Goal: given one logged action, get the full chain of delegation back to the human who consented to it.
Look up the chain for an action
Every allow/deny decision has an action_id (returned by POST /v1/authorize and present on
each audit row). Query its chain:
curl -sS localhost:8000/v1/audit/actions/$ACTION_ID/chain \
-H "Authorization: Bearer $ADMIN_TOKEN"
Expected response: a RootConsent (the human, the scope, when they consented) and an
ordered list of ChainHop entries — each with its own hop number, acting_agent, target,
data_class, decision, and (for a deny) deny_reason.
Check whether the chain is complete
The response reports complete: true, or names exactly where it broke:
| Break reason | What it means |
|---|---|
LEGACY_TOKEN | The token predates chain tracking — no action_id to link from |
PARENT_NOT_FOUND | The named parent action doesn't exist |
PARENT_MISMATCH | A parent exists but doesn't actually link to this hop |
PARENT_INCOMPLETE | The break is inherited from further up the chain |
LEGACY_RECORD | The row predates full field capture; hops are rebuilt from the token's act chain, with unavailable: true on fields that weren't captured |
A chain never silently reports complete when it isn't — a break is always a specific,
at_hop-located reason, not a generic "unknown."
Browse decisions instead of looking up one action
If you don't have an action_id yet — for example, investigating "what did this session do" —
page through the raw decision log first:
curl -sS "localhost:8000/v1/audit/decisions?session_id=$SESSION&outcome=deny" \
-H "Authorization: Bearer $ADMIN_TOKEN"
Then take any action_id from the results into the chain query above.
GET /v1/decisions (no /audit prefix) still exists but is deprecated — use
GET /v1/audit/decisions. See Reference → Audit API.
Related
- Delegation-Chain Query API — why this is a single-row read, not a walk
- The delegation-chain audit model
- Reference → Audit API