approval-engine/docs/approval-consumption.md

Approval consumption API

Status: implemented under Gate House decision GH-DEC-2026-003.

The normative protocol is gate-house/docs/contracts/approval-consumption.md. This document records the approval-engine implementation surface; it does not redefine the protocol.

Endpoint

POST /v1/approvals/{id}/consume

{
  "request_digest": "sha256:<64 lowercase hex>",
  "decision_id": "decision:optional-provenance"
}

The caller is the PEP that is about to perform the protected side effect. It calls consume after an ALLOW and before that side effect. request_digest is the canonical digest from the PDP decision binding, not a newly serialized request and not approval-engine's native binding digest.

Results

• First valid consume: atomically stores the digest, changes approved to consumed, and inserts one approval.use outbox row in the same transaction.
• Same digest after consumption: 200 idempotent success and no second outbox row.
• Different digest after consumption: 409 conflict; the PEP must not act.
• Revoked, superseded, expired, outside-window, requested, or unknown object: conflict or not-found; the PEP must not act.
• Outbox insert/store failure: 503; the transaction rolls back and the PEP must not act.

There is no unconsume, release, or reserve. If the protected side effect fails after consumption, the approval remains spent and a retry needs a new approval.

The response is mutation evidence, not a permission decision. It contains no effect, allow, deny, or decision result.