Authorize request/decision schema

See Authorize API for the full endpoint reference; this page is the schema detail.

`AuthorizeRequest`

Field	Type	Notes
`session_id`	`str`
`caller`	`str` (max 255)	`agent://<name>`, or `user:<sub>` at hop 1
`target`	`str` (max 512)	`mcp://host/tool`, or `agent://<name>`
`data_class`	`str` (max 128)	Exactly one data class
`taint`	`Taint \| null`	`trusted_internal` \| `untrusted_external`
`enforced`	`bool` (default `true`)	Reported by the caller; never affects the decision

There is deliberately no hop_count field — depth is derived from the presented token's verified act chain.

`AuthorizeDecision`

Field	Type	Notes
`outcome`	`"allow" \| "deny"`
`hop`	`int` (≥1)	Derived from the verified `act` chain
`policy_version`	`int`
`session_id`	`str`
`reason`	`DenyReason \| null`	Present only on deny
`recoverable`	`bool \| null`	A property of the reason, not the call
`target`	`str \| null`
`taint`	`Taint \| null`
`message`	`str \| null`	Human-readable; never the machine contract
`action_id`	`UUID \| null`	The audit row this decision was recorded under
`acting_agent`	`str \| null`	The verified token holder
`recorded`	`bool` (default `true`)	Whether the audit row was committed before this response

`DenyReason`

OUT_OF_SCOPE · HOP_BUDGET_EXCEEDED · EDGE_NOT_IN_DAG · SCOPE_NOT_CONSENTED · PDP_UNAVAILABLE · TOKEN_SERVICE_UNAVAILABLE · AUDIT_UNAVAILABLE

Every reason is classified as exactly one of Policy (OUT_OF_SCOPE, HOP_BUDGET_EXCEEDED, EDGE_NOT_IN_DAG, SCOPE_NOT_CONSENTED) or Infrastructure (PDP_UNAVAILABLE, TOKEN_SERVICE_UNAVAILABLE, AUDIT_UNAVAILABLE) — observe mode may let a policy reason through (that's its purpose) but must never let an infrastructure reason through, since that would forward an outage as if it were a policy prediction.