---
title: "Evaluate and bind authority for one UCP checkout completion"
method: POST
path: "/v1/ucp/checkout/authorize"
---

# Evaluate and bind authority for one UCP checkout completion

`POST /v1/ucp/checkout/authorize`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/ucp/checkout/authorize`
- Auth: HTTP bearer

Accepts a complete UCP checkout response envelope negotiated at either
2026-04-08 or 2026-08-25. The seven UCP top-level checkout fields are
required and extension members remain open. August responses must also
carry ucp.payment_handlers; line items retain their official required
fields and quantity floor; checkout totals contain exactly one subtotal
and one total. Historical April callers retain the original adapter's
optional payment-handler compatibility. Missing, ambiguous, or
unsupported material fails before policy evaluation.

Decionis authorizes; the connected merchant system remains responsible
for execution. An ALLOW decision is not itself an execution grant. An
authoritative response may carry an exact-action grant that must be
claimed immediately before the merchant commits the checkout, then
finalized as COMMITTED, FAILED, or INDETERMINATE.

## Headers

- `Idempotency-Key` string

## Request body

- UcpCheckoutAuthorizeRequest
  - `org_id` string, uuid: Optional when the authenticated API key is organization-bound.
  - `checkout` UcpCheckoutSession, required: Validated core checkout response plus any negotiated extensions. The seven top-level required members are common to UCP 2026-04-08 and 2026-08-25; the version conditional below additionally requires the August response payment-handler registry.
    - `ucp` UcpCheckoutEnvelope, required
      - `version` '2026-04-08' | '2026-08-25', required: UCP releases whose checkout response envelopes this adapter validates.
      - `status` 'success' | 'error'
      - `capabilities` object: Negotiated UCP capabilities keyed by reverse-domain identifier. A capability is active only through a matching versioned reference; key presence or an empty array is not negotiation.
      - `payment_handlers` object
    - `id` string, required
    - `line_items` UcpCheckoutLineItem[], required
      - `id` string, required
      - `quantity` integer, required
      - `item` object, required
        - `id` string, required
        - `title` string, required
        - `price` integer, required: ISO 4217 minor units.
      - `totals` UcpCheckoutTotal[], required
        - `type` string, required
        - `amount` integer, required: ISO 4217 minor units.
        - `display_text` string
    - `status` 'incomplete' | 'requires_escalation' | 'ready_for_complete' | 'complete_in_progress' | 'completed' | 'canceled', required
    - `currency` string, required: ISO 4217 List One code with a numeric minor unit, pinned to the maintenance-agency list published 2026-01-01. Unknown codes and entries whose minor unit is N.A. are rejected before evaluation.
    - `totals` UcpCheckoutTotal[], required
      - `type` string, required
      - `amount` integer, required: ISO 4217 minor units.
      - `display_text` string
    - `links` UcpCheckoutLink[], required
      - `type` string, required
      - `url` string, uri, required
      - `title` string
    - `signals` object
    - `ap2` object
      - `checkout_mandate` string
      - `merchant_authorization` string
  - `agent` object
    - `id` string
    - `human_present` boolean
    - `environment` string: Merchant execution environment committed into the signed downstream target, for example base-sepolia or production.
  - `approval_url` string, uri
  - `mode` 'SHADOW' | 'PARALLEL' | 'ENFORCEMENT'
  - `grant_ttl_seconds` integer
  - `idempotency_key` string
  - `degradation_mode` 'fail_closed': Compatibility field. Execution authority always fails closed; caller-selected fail-open is rejected.

## Response `200`

UCP-shaped authority result; execution authority remains fail-closed

- UcpCheckoutAuthorizeResponse
  - `service` 'decionis', required
  - `ucp` object, required
    - `version` '2026-04-08' | '2026-08-25', required: UCP releases whose checkout response envelopes this adapter validates.
    - `status` 'success' | 'error', required
  - `checkout_id` string
  - `mode` 'SHADOW' | 'PARALLEL' | 'ENFORCEMENT'
  - `enforcing` boolean
  - `authority_classification` 'AUTHORITATIVE' | 'OBSERVATIONAL': Authority possessed by an artifact, independent of its verdict. Only AUTHORITATIVE artifacts may become execution-eligible.
  - `evaluation_mode` 'SHADOW' | 'PARALLEL' | 'ENFORCEMENT': Present on some fail-closed evidence errors; normal results use mode.
  - `execution_eligible` boolean: True only for an AUTHORITATIVE ALLOW carrying an exact-action execution grant. Signature validity alone does not make a response execution-eligible.
  - `dossier_id` string, nullable
  - `status` string, nullable
  - `continue_url` string, uri
  - `error` object
  - `actions` UcpActions
    - `com.decionis.authority.review` UcpAuthorityReviewAction[], required
      - `id` string, required
      - `config` UcpAuthorityReviewActionConfig, required
        - `continue_url` string, uri, required
        - `reason_codes` string[]
        - `expires_at` string, date-time
  - `messages` UcpMessage[]
    - `type` 'info' | 'warning' | 'error', required
    - `content_type` 'plain' | 'markdown', required
    - `content` string, required
  - `fallback` UcpAuthorityFallback
    - `degraded` true, required
    - `mode` 'fail_closed', required
    - `reason` string, required
    - `circuit_open` boolean, required
  - `com.decionis.commerce.execution_authority` union: Version-dispatched response union. The exact negotiated extension release determines which immutable member schema applies; this union preserves historical 2026-09-05 and additive 2026-09-06 responses while making 2026-09-07 Protocol 1.1 evidence strict.
    - UcpExecutionAuthorityPayloadLegacy: Exact response projection for extension 2026-09-05.
      - `decision` 'ALLOW' | 'ESCALATE' | 'BLOCK', required
      - `authoritative` boolean, required: Legacy compatibility flag; authority_classification is normative in Protocol 1.1.
      - `evaluation_id` string, required
      - `dossier_id` string, required
      - `policy_version` string, required
      - `reason_codes` string[], required
      - `required_presence` boolean, required
      - `verification_url` string, uri, nullable, required
      - `evaluated_at` string, date-time, required
      - `dossier_sha256` string, nullable, required
    - UcpExecutionAuthorityPayloadPrevious: Additive Protocol 1.1 response projection for extension 2026-09-06.
      - `decision` 'ALLOW' | 'ESCALATE' | 'BLOCK', required
      - `authoritative` boolean, required: Legacy compatibility flag; authority_classification is normative in Protocol 1.1.
      - `evaluation_id` string, required
      - `dossier_id` string, required
      - `policy_version` string, required
      - `reason_codes` string[], required
      - `required_presence` boolean, required
      - `verification_url` string, uri, nullable, required
      - `evaluated_at` string, date-time, required
      - `authority_classification` 'AUTHORITATIVE' | 'OBSERVATIONAL': Authority possessed by an artifact, independent of its verdict. Only AUTHORITATIVE artifacts may become execution-eligible.
      - `evaluation_mode` 'SHADOW' | 'PARALLEL' | 'ENFORCEMENT'
      - `execution_eligible` boolean
      - `policy_reference` PolicyReference
        - `policy_id` string, required
        - `revision_id` string, required
        - `version` string, required
        - `digest` string, required
      - `evaluation_semantics` EvaluationSemantics
        - `protocol_version` '1.1', required
        - `evaluator_version` string, required
        - `policy_schema_version` string, required
        - `canonicalization` 'RFC8785/JCS', required
        - `digest_algorithm` 'SHA-256', required
        - `signal_normalization_version` string, required
      - `input_snapshot_digest` string
      - `execution_binding_digest` string, nullable
      - `dossier_sha256` string, nullable, required
    - UcpExecutionAuthorityPayloadCurrent: Strict Protocol 1.1 response projection for extension 2026-09-07.
      - `decision` 'ALLOW' | 'ESCALATE' | 'BLOCK', required
      - `authoritative` boolean, required: Legacy compatibility flag; authority_classification is normative in Protocol 1.1.
      - `evaluation_id` string, required
      - `dossier_id` string, required
      - `policy_version` string, required
      - `reason_codes` string[], required
      - `required_presence` boolean, required
      - `verification_url` string, uri, nullable, required
      - `evaluated_at` string, date-time, required
      - `authority_classification` 'AUTHORITATIVE' | 'OBSERVATIONAL', required: Authority possessed by an artifact, independent of its verdict. Only AUTHORITATIVE artifacts may become execution-eligible.
      - `evaluation_mode` 'SHADOW' | 'PARALLEL' | 'ENFORCEMENT', required
      - `execution_eligible` boolean, required
      - `policy_reference` PolicyReference, required
        - `policy_id` string, required
        - `revision_id` string, required
        - `version` string, required
        - `digest` string, required
      - `evaluation_semantics` EvaluationSemantics, required
        - `protocol_version` '1.1', required
        - `evaluator_version` string, required
        - `policy_schema_version` string, required
        - `canonicalization` 'RFC8785/JCS', required
        - `digest_algorithm` 'SHA-256', required
        - `signal_normalization_version` string, required
      - `input_snapshot_digest` string, required
      - `execution_binding_digest` string, nullable, required
      - `dossier_sha256` string, nullable, required
  - `verification` UcpMandateVerification
    - `verified` boolean, required: Compatibility rollup; use status to distinguish inapplicable from unverified.
    - `status` 'VERIFIED' | 'UNVERIFIED' | 'NOT_APPLICABLE', required
    - `checked` string[], required
    - `not_checked` string[], required
  - `escalation` object, nullable
    - `override_id` string, required
    - `status` 'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED' | 'EXPIRED'
  - `execution_grant` UcpExecutionGrant
    - `token` string, required
    - `jti` string, required
    - `key_id` string, required
    - `expires_at` string, date-time, required
    - `intent_hash` string, required
    - `execution_binding_digest` string, required
    - `execution_correlation_id` string, required
    - `claim_path` '/v1/execution/claim-token', required
    - `finalize_path` '/v1/execution/finalize-token', required
    - `intent` ExecutionIntentBinding, required
      - `protocol_version` 'agent-safe.intent/1', required
      - `tenant_id` string, uuid, required
      - `intent_id` string, uuid, required
      - `captured_at` string, date-time, required
      - `expires_at` string, date-time, required: Must be later than captured_at and no more than five minutes after it.
      - `actor` ExecutionIntentActor, required
        - `id` string, required
        - `type` string, required
        - `runtime` string
        - `trust_level` string
      - `action` ExecutionIntentAction, required
        - `type` string, required
        - `resource` string, required
        - `parameters` object, required
      - `context` object, required: The trusted runtime's context, entirely inside the canonical intent hash. Open by design, with three reserved keys. `idempotency_key` is required and carries the retry identity. `enforcement_boundary` and `workload` are what an enforcement boundary reports about itself and about the software that proposed the action; each is validated against its schema when present, and an absent signal is an answer rather than a placeholder, so a policy that requires provenance refuses on its absence. `runtime_attribution` is reserved for Decionis, which computes it from those reports, and a request that supplies it is refused.
        - `enforcement_boundary` EnforcementBoundarySignal: Which enforcement boundary admitted the intent. The identity is of the configured logical boundary, not of the process running it: a restart, a rescheduling or a scale-out leaves it unchanged, and the container, pod and node are deliberately absent, so an effect's evidence names the door rather than whichever instance was alive at the time.
          - `boundary_id` string, required: What the operator calls this boundary, or a stable id derived from its configuration.
          - `agentsafe_version` string, required
          - `protocol_version` 'agent-safe.intent/1', required
          - `deployment_type` string, required: What the boundary was installed as, for example docker, kubernetes or linux.
          - `environment` string
          - `conformance_version` string
          - `placement` object: Stable placement only. It survives a restart and is what a policy means by an environment and a region.
            - `cluster_id` string
            - `namespace` string
            - `region` string
            - `workload_id` string
        - `workload` WorkloadSignal: What software proposed the action, as a runtime reported it. Decionis records the report and does not establish it: image digests, provenance attestations and publisher verification belong to the container and OCI tooling that produced them. Every field is optional but `provenance`, because a workload cannot be expressed without saying who reported it and how far that report goes.
          - `runtime` string
          - `artifact_type` string
          - `image` string
          - `digest` string
          - `publisher` string
          - `provenance` object, required
            - `source` string, required: Who reported it, for example docker, kubernetes or operator.
            - `trust_level` 'unverified' | 'supplied' | 'observed' | 'verified', required: How far the producer said its report goes. It is the producer's claim, recorded as such: Decionis neither raises nor lowers it. A policy that means the platform checked something matches on the decision's `runtime_attribution.platform_verified` instead, which Decionis computes and a caller cannot assert.
      - `downstream_target` ExecutionDownstreamTarget, required
        - `system` string, required
        - `operation` string, required
        - `environment` string
        - `endpoint` string
      - `policy_projection` ExecutionPolicyProjection: Exact policy-routing vocabulary committed into the intent. Protocol adapters use it when their evaluated decision type differs from the executable action type; legacy generic callers may omit it.
        - `decision_type` string, required
        - `transaction_type` string, nullable, required
        - `workflow_key` string, nullable, required
        - `channel` string, nullable, required
      - `expected_effect_digest` string: Digest-only commitment to the expected downstream state.
  - `requires_human_approval` boolean
  - `reason_codes` string[]

## Other responses

- `400`: Invalid or unsupported UCP checkout envelope or mandate evidence
- `401`: Structured API error
- `403`: Policy refused the completion or the credential lacks authority
- `409`: The supplied or retained authority material conflicts with the exact checkout action
- `429`: Structured API error
- `503`: Authority unavailable; no execution is authorized

---

[API](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/revisions/357f5e459d0c?raw)