---
title: "Finalize a claimed downstream commit attempt"
method: POST
path: "/v1/execution/finalize-token"
deprecated: true
---

# Finalize a claimed downstream commit attempt

`POST /v1/execution/finalize-token`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/execution/finalize-token`
- Auth: HTTP bearer

> **Deprecated.**

Deprecated alias of `POST /v1/authority/grants/{grantId}/receipts`:
the same handler.

Records COMMITTED, FAILED, or INDETERMINATE. INDETERMINATE effects must
be reconciled and are never safe for automatic retry. A COMMITTED claim
proves an attempt was finalized, but an effect is confirmed only when
digest-bound `effect_evidence` with status CONFIRMED is accepted. If the
signed grant expires after a successful claim, finalization may continue
only while the exact persisted claim token, nonce, correlation, and
database claim lease remain valid. An expired unclaimed grant is never
execution-eligible. A finalize request at or after the database-clock
lease boundary fails closed and atomically records the claim as
INDETERMINATE.

A verifying provider's signed effect receipt (Verifying Provider
Profile, VP-3) may accompany the finalization as `effect_receipt`. It
is verified against the organisation's registered provider keys and
recorded in the commit evidence as presented, verified or not; it is
never a reason to refuse the finalization. When the grant named the
effect it expected and the verified receipt carries an effect digest,
the receipt is also read as `SIGNED_RECEIPT` effect evidence, and
confirms the effect only when the digests agree and the outcome is
COMMITTED. An explicit `effect_evidence` takes precedence.

## Request body

- ExecutionFinalizeRequest
  - `execution_token` string, required
  - `claim_token` string, required
  - `outcome` 'COMMITTED' | 'FAILED' | 'INDETERMINATE', required
  - `commit_correlation_id` string, required
  - `downstream_evidence` object: Free-form legacy evidence; never interpreted as effect confirmation.
  - `native_receipt` NativeReceipt: What a permit-style platform recorded when it carried the action out (a posted journal, an acknowledged order). Recorded as `downstream_evidence.native_receipt`, replacing any value the executor put there; the executor's report of the attempt, never effect confirmation by itself.
    - `platform` string, required
    - `kind` string, required
    - `reference` string, required
    - `status` string, required
    - `observed_at` string, date-time, required
    - `digest` string
  - `effect_evidence` union: When effect evidence is present for a Protocol 1.1 grant it must use the Protocol 1.1 shape. Effect confirmation remains optional. The legacy shape remains accepted only for historical grants and keeps its original verification semantics.
    - EffectEvidence: Optional Protocol 1.1 observation evidence. COMMITTED remains an executor-reported finalization state and is not CONFIRMED without a qualifying record. Raw provider responses should remain outside the evidence artifact; use commitments and immutable references.
      - `version` '1.0', required
      - `status` 'CONFIRMED' | 'UNCONFIRMED', required
      - `observation_method` 'DOWNSTREAM_ACK' | 'READ_AFTER_WRITE' | 'EVENT_CONFIRMATION' | 'STATE_RECONCILIATION' | 'SIGNED_RECEIPT' | 'EXTERNAL_ATTESTATION' | 'HUMAN_VALIDATION', required: Versioned identifier for how the downstream effect was observed. DOWNSTREAM_ACK is weak evidence and cannot independently confirm an effect.
      - `observer` object, nullable, required
        - `id` string, required
        - `version` string, nullable, required
      - `expected_effect_digest` string, required
      - `observed_effect_digest` string, nullable, required: For CONFIRMED evidence, must equal expected_effect_digest.
      - `observed_at` string, date-time, nullable, required
      - `evidence_digest` string, nullable, required
      - `evidence_reference` string, nullable, required
      - `execution_correlation_id` string, required: Must exactly equal the bound commit correlation identifier.
    - ExecutionEffectEvidence: Deployed pre-Protocol-1.1 effect record. It remains accepted and verifiable for grants issued under its original request/outcome-binding rules. Protocol 1.1 grants reject this shape to prevent an evidence semantics downgrade. New integrations should emit EffectEvidence.
      - `effect_schema_version` '1.0', required
      - `status` 'CONFIRMED' | 'FAILED' | 'INDETERMINATE', required: CONFIRMED means the execution gate directly observed a digestible response.
      - `request_digest` string, required: Must equal the execution payload digest signed into the grant.
      - `response_digest` string, nullable, required: Required when status is CONFIRMED; null otherwise.
      - `digest_algorithm` 'SHA-256', required
      - `canonicalization_profile` string, required: Canonicalization profile for the response digest when present; otherwise the request digest profile.
      - `external_reference` string, nullable, required
      - `observation_mode` 'GATE_OBSERVED' | 'RUNTIME_REPORTED', required
      - `observer` object, required
        - `id` string, required
        - `version` string, required
      - `observed_at` string, date-time, required
      - `metadata_digest` string, nullable, required
  - `effect_receipt` string: A verifying provider's effect receipt, forwarded by the executor exactly as the provider returned it: a compact EdDSA JWS whose protected header `typ` is `decionis-effect-receipt+jwt` and whose payload is `EffectReceiptClaims`. Verified against the organisation's registered provider keys and recorded whatever the verdict; never a reason to refuse the finalization.

## Response `200`

Claim finalized and commit evidence recorded or queued for recovery

- ExecutionFinalizeResponse
  - `finalized` boolean, required
  - `outcome` 'COMMITTED' | 'FAILED' | 'INDETERMINATE'
  - `evidence_recorded` boolean: Compatibility field reporting immediate Decision Chain acknowledgement.
  - `evidence_durably_queued` boolean: True when commit evidence was persisted transactionally with the terminal claim state, including lease-expiry INDETERMINATE.
  - `decision_chain_evidence_recorded` boolean: True when the Protocol Decision Chain had already acknowledged the commit evidence when this response was formed; false is delivered asynchronously from the durable outbox.
  - `effect_evidence_recorded` boolean
  - `effect_confirmation` 'CONFIRMED' | 'UNCONFIRMED'
  - `effect_receipt` object: Present when the request carried an `effect_receipt`.
    - `verified` boolean, required: True when the receipt's signature verified under a registered provider key and its claims describe this grant and this claim.
    - `verification_code` 'EFFECT_RECEIPT_VERIFIED' | 'EFFECT_RECEIPT_MALFORMED' | 'EFFECT_RECEIPT_KEY_UNKNOWN' | 'EFFECT_RECEIPT_SIGNATURE_INVALID' | 'EFFECT_RECEIPT_BINDING_MISMATCH' | 'EFFECT_RECEIPT_KEYS_UNAVAILABLE', required
    - `provider_key_id` string, nullable, required: The `kid` the receipt named, when it named one.
    - `recorded` boolean, required: True when the receipt was persisted in the commit evidence, which is whenever the claim finalized.
  - `reason_codes` string[], required

## Other responses

- `400`: Invalid finalization or effect-evidence shape
- `401`: Structured API error
- `403`: Structured API error
- `409`: Invalid, replayed, non-claimed, or lease-expired authorization. An expired claim reports outcome INDETERMINATE and CLAIM_LEASE_EXPIRED. A corrupt claim missing its claimed scope is also forced INDETERMINATE and reports CLAIM_SCOPE_INVARIANT_VIOLATION.

---

[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)