Summarize shadow-mode decision evaluation reports
Returns aggregate protocol-owned shadow report metrics for saved evaluate-decision records.
Authorization
ApiKeyAuth An organization API key. Its scopes decide what it may call;
decision:shadow is the narrowest: SHADOW evaluations through
POST /v1/authority/grants or its alias
POST /v1/authority/enforce-and-bind only (DECISION_SHADOW_MODE_DENIED
in any other mode; DECISION_SHADOW_FIELD_DENIED for a body carrying
context.decionis_policy, evidence or escalation), with no
integration dispatch. A key whose only scope is decision:shadow
(an AgentSafe hosted gateway's) reaches exactly those two,
POST /v1/auth/credential-context, POST /v1/hosted-gateway/keys/confirm
and POST /v1/hosted-gateway/keys/revoke-self; every other route
answers 403 HOSTED_GATEWAY_KEY_PATH_DENIED.
decision:enforce is an enforced hosted gateway's key: evaluations
in SHADOW or ENFORCEMENT through POST /v1/authority/grants or its
alias (400 DECISION_ENFORCE_FIELD_DENIED for a body carrying
context.decionis_policy; it never holds policy:write), and the
grants and managed escalations they bind. A key whose scopes are
decision:enforce (with or without decision:shadow) reaches exactly
POST /v1/authority/enforce-and-bind, POST /v1/authority/grants,
GET /v1/authority/grants/{grant_id},
POST /v1/authority/grants/{grant_id}/claims,
POST /v1/authority/grants/{grant_id}/receipts,
POST /v1/authority/grants/{grant_id}/reconciliations,
POST /v1/execution/verify-token, POST /v1/execution/claim-token,
POST /v1/execution/consume-token, POST /v1/execution/finalize-token,
GET /v1/authority/escalations/{escalation_id},
DELETE /v1/authority/escalations/{escalation_id},
POST /v1/auth/credential-context, POST /v1/hosted-gateway/keys/confirm
and POST /v1/hosted-gateway/keys/revoke-self, each id a UUID; every
other route answers 403 HOSTED_GATEWAY_KEY_PATH_DENIED.
In: header
Query Parameters
uuid"SHADOW"Value in
- "SHADOW"
- "PARALLEL"
- "ENFORCEMENT"
1 <= value <= 50050date-timeResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/protocol/shadow/evaluate-decision/reports/summary?org_id=497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "service": "string", "protocol_version": "string", "generated_at": "2019-08-24T14:15:22Z", "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b", "mode": "SHADOW", "since": "2019-08-24T14:15:22Z", "summary": { "total_evaluations": 0, "would_approve_count": 0, "would_block_count": 0, "would_escalate_count": 0, "review_required_count": 0, "non_approve_count": 0, "non_approve_rate": 0, "policy_mismatch_count": 0, "policy_mismatch_rate": 0, "near_miss_count": 0, "near_miss_rate": 0, "outcome_counts": { "property1": 0, "property2": 0 }, "top_decision_types": [ {} ], "top_reason_patterns": [ {} ] }}List shadow-mode decision evaluation reports GET
Returns protocol-owned shadow reports derived from saved evaluate-decision records. Reports summarize what Decionis would continue, stop, hand off, or review without exposing policy rules.
Evaluate and bind one exact agent action to a single-use execution grant POST
Deprecated alias of `POST /v1/authority/grants`: the same handler, kept registered so AgentSafe 0.3.8, the Go govern client and installed SDKs keep working byte-for-byte. Removal is a later, separate decision. Agent-Safe enforcement route. Decionis recomputes the SHA-256 hash of the canonical execution intent, evaluates policy in ENFORCEMENT mode, and issues a short-lived Ed25519 execution grant only for an ALLOW evaluated in ENFORCEMENT mode. SHADOW records the same exact intent and dossier evidence without issuing an execution grant. When Idempotency-Key is supplied, it must exactly match the intent_id embedded in the signed intent; intent_id is the grant issuance boundary. The intent's own `context.idempotency_key` is hashed into the intent and is not this header: any other header value answers 400 AUTHORITY_IDEMPOTENCY_KEY_MISMATCH, with a `message` saying so. ESCALATE, REVIEW_REQUIRED, BLOCK, dependency errors, and binding errors never receive a grant. A Presence approval is accepted only after Decionis verifies the action-bound request and sealed receipt directly with Presence; approval then becomes evidence for a fresh policy evaluation, not authority by itself. A presence attestation (`evidence.humanApproval.provider` `attestation`) is a presence provider's compact JWS, typ `decionis-presence-attestation+jwt`, verified against a key the organisation registered at `/v1/execution/provider-keys` with purpose `presence_attestation` (see PresenceAttestationClaims). On success its facts are written to `agent_safe.human_approval` (provider, verified, method, approver_role, subject, attestation_id, key_id, approved_action_digest, approved_at, expires_at, and token_match / network_validated when the provider sent them) for policy rules to match, and the resulting ExecutionBinding records the attested approval. An ESCALATE becomes an ALLOW only when the organisation's policy has a rule matching those facts. A refused attestation is a 409 with one of the PresenceAttestationRefusal codes, and no evaluation runs. A signed producer signal (`evidence.signals[].token`) is a producer's compact JWS, typ `decionis-signed-signal+jwt`, standing for up to thirty days and bound to no intent: a cardholder's delegation to an agent, say (see SignedSignalClaims). Each is verified before any evaluation against a key the organisation registered at `/v1/execution/provider-keys` with purpose `signed_signal`, or against the JWKS of an admitted presence provider, and its facts are written to `agent_safe.signed_signals.<name>` (verified, producer, method, subject, signal_id, key_id, issued_at, expires_at, evidence_digest, what it asserted, and `covers` / `covers_intent`: what of this intent it covers). A policy names the fact with `required_signals` as a dotted path (`agent_safe.signed_signals.card_delegation`) and decides with rules; the ExecutionBinding records the facts, and the claim rebuilds them and re-checks the key and the expiry. Signals may come with or without a human approval, in any mode, and beside a managed escalation. A refused signal is a 409 with one of the SignedSignalRefusal codes; no evaluation runs and no event fires. The token itself is never recorded, only its SHA-256 as `evidence_digest`. A runtime that read the target before asking states what it read in `context.agent_safe.precondition` (ExecutionTargetPrecondition: `version`, optional `state`, `source`, `read_at`), inside the intent hash. Policy reads it as `agent_safe.precondition`, and a bundle's `allowed_transitions` read its `state`; the grant binds `version` as `binding.expected_state_version`, and the claim's attestation carries it to a verifying provider, which refuses the write (`TARGET_STATE_CHANGED`) once the target has moved on. A malformed precondition is a 400 `INTENT_PRECONDITION_INVALID`, and nothing is evaluated. An ESCALATE in ENFORCEMENT, direct or managed, is queued to the organisation's event subscribers as `authority.escalation_required`, carrying the policy's selector and who proves the person (the `verification` block: `provider`, `methods`, `level`); and once the intent is presented again with human approval evidence, the answer is queued as `authority.escalation_resolved` (the fresh decision's outcome, or REFUSED with the refusal code), with the proof's facts and never the proof. Delivery never affects a decision. The same routing rides on an ESCALATE decision as `escalation_requirement` for the runtime from agent-safe-pipeline/0.3.7 on, and for no other client. The action space the deciding policy release was checked against rides on the decision as `action_manifest_digest` (the release's `actionManifestDigest`, or null when no governed release decided or its release attached no ActionManifest) for the runtime from agent-safe-pipeline/0.5.1 on, and for no other client. The runtime compares it with the action space it loaded and reports a difference; it changes nothing about the decision. When escalation.mode is MANAGED and policy returns ESCALATE, Decionis persists the original exact intent and orchestrates the policy-issued Presence ceremony. The response remains non-authorizing and carries a managed_escalation status locator; no ExecutionBinding or execution token exists until signed Presence evidence is independently verified and current policy is evaluated again. The decision carries the dossier's `verification` envelope (the same share-safe page `evaluate-decision` attaches) for a client that can read it: one identifying itself as `agent-safe-pipeline/0.2.0` or later, or as `govern/2.0.0` or later (the workflow gate), in its User-Agent. Every other client receives the decision exactly as before, so a gate that mirrors this schema strictly never meets a field it does not know. On this operation, a `context.decionis_policy` is treated as on evaluate-decision: its `sha256` must be the SHA-256 of its `content`, and one that asks for `enforce: true` has its policy file published as the workspace's enforced policy only when the key holds `policy:write`, `policy:*` or `org:*`; for any other key the decision is unaffected, nothing is published, and the response carries `x-decionis-warning: POLICY_ENFORCE_SCOPE_MISSING`. No other operation whose body or answer carries an execution intent (verify-token, consume-token, claim-token, or the execution grant of /v1/ucp/checkout/authorize) publishes a policy file or sends that header, whatever the key holds. A key whose only evaluation scope is `decision:shadow` (an AgentSafe hosted gateway's) runs SHADOW and nothing else: any other mode answers 403 DECISION_SHADOW_MODE_DENIED, a body carrying `context.decionis_policy`, `evidence` or `escalation` answers 400 DECISION_SHADOW_FIELD_DENIED (naming the `field`), and the evaluation is recorded and signed without dispatching to the organization's integrations. A key whose evaluation scope is `decision:enforce` (an enforced AgentSafe hosted gateway's) runs SHADOW or ENFORCEMENT, may open a managed escalation, and answers 400 DECISION_ENFORCE_FIELD_DENIED for a body carrying `context.decionis_policy`: it never publishes policy. The scopes each mode needs: SHADOW takes one of `decision:write`, `decision:run`, `decision:*`, `org:*`, `decision:shadow` or `decision:enforce`; PARALLEL and ENFORCEMENT take one of `decision:write`, `decision:*`, `org:*` or `decision:enforce`, so a key that runs SHADOW can still answer 403 FORBIDDEN in ENFORCEMENT. The workspace counts too: a provisional workspace that no owner has claimed, or an AWS service workspace, runs SHADOW only, and any other mode answers 403 PROVISIONAL_WORKSPACE_SHADOW_ONLY (or SERVICE_WORKSPACE_SHADOW_ONLY) whatever the key holds, with a `message`. An owner claims a provisional workspace through `POST /v1/orgs/{org_id}/claim/start` and `/claim/verify`; claiming does not widen a key's scopes. A SHADOW success therefore says nothing about whether ENFORCEMENT will be accepted. When a grant is issued under Protocol 1.1 and the intent named no `expected_effect_digest`, the decision is unchanged and `x-decionis-warning` carries EXPECTED_EFFECT_DIGEST_MISSING: that grant accepts no effect evidence at finalization or reconciliation, so its effect can never be confirmed. A held allowance (`/v1/authority/allowances`) is a named, organisation-scoped counter that policy draws on: the rule that approved the action names it in `then.allowance`, with the amount fixed or read from `action.parameters` by JSON pointer, and the ExecutionBinding records the draw as `allowance_draws`. A grant is issued only once that amount is reserved against the allowance, tied to the grant. When it cannot be, no grant is issued and the decision is `BLOCK` (`should_execute` false, `execution_eligible` false, `execution_binding_digest` null) with one of these reason codes after the evaluation's own: `ALLOWANCE_EXHAUSTED` (what remains, the limit less what unclaimed grants reserve, what open or unknown claims hold, and what committed claims consumed within the window, is less than the amount), `ALLOWANCE_UNDEFINED` (the organisation defines no allowance under that key) or `ALLOWANCE_AMOUNT_INVALID` (the parameters give no positive whole amount). It is a refusal and not an ESCALATE because no approval creates capacity: only raising the allowance's own limit does (a top-up, which needs `policy:write` or `org:*` and so never an agent's key), after which the action may be proposed again. The dossier keeps the evaluation as it was decided; the refusal is the authority's, at the moment of the grant. The claim converts the reservation in the transaction that consumes the grant, and finalization settles it: COMMITTED keeps it, FAILED releases it, INDETERMINATE holds it until reconciliation, and a grant never claimed releases it when it expires. An allowance is a counter and never a concurrency scope: grants drawing on one allowance are claimed and carried out concurrently while it has room.

