Decision Trace Headers
Scope
Reference for HTTP headers injected by the authorization gateway into upstream requests and responses. These headers carry decision metadata, trace identifiers, and diagnostic information used for observability and debugging.
Definitions
| Name | Description |
|---|---|
X-Decision-Id | Unique identifier for the authorization decision, usable for log correlation |
X-Decision-Result | The outcome of the authorization evaluation: allow, deny, or indeterminate |
X-Decision-Policy | The policy identifier that produced the final decision |
X-Decision-Duration-Ms | Wall-clock time in milliseconds for the decision evaluation |
X-Decision-Cache | Whether the decision was served from cache: hit or miss |
X-Decision-Trace | Comma-separated list of policy rule identifiers evaluated, in order |
X-Decision-Reason | Human-readable short reason for deny decisions |
Example
{
"X-Decision-Id": "dec_8f3a2b1c",
"X-Decision-Result": "deny",
"X-Decision-Policy": "policy:documents:write",
"X-Decision-Duration-Ms": "4",
"X-Decision-Cache": "miss",
"X-Decision-Trace": "rule:tenant-match,rule:role-check,rule:resource-owner",
"X-Decision-Reason": "subject lacks documents:write permission"
}
note
The X-Decision-Trace header records the policy rule evaluation order during an authorization decision. This is not an OpenTelemetry distributed trace. For distributed request tracing across services, see Traces and Root Cause Analysis. For the glossary distinction, see Decision Trace.