Receipt fields

A receipt is a signed record of how one protected action ended. K-Block stores each receipt as an evidence bundle (a .kbundle file) and keeps a summary record of it for listing and searching.

This page describes the fields you see: in the Cloud API, on the dashboard's Receipts pages, in the answer an agent gets, and inside the bundle. It describes the current Protocol v0.1 format and does not change it. For what these fields prove, see What a receipt proves; to check a bundle yourself, see Verify a receipt.

Where receipts come from

A receipt exists only for actions that reached certain final states:

Every receipt is signed by K-Block's Gateway identity, the identity whose KID is the Gateway KID. See Action statuses for the details.

Summary fields

The receipt list (GET /api/v1/orgs/<org-id>/receipts) and the receipt detail (GET /api/v1/orgs/<org-id>/receipts/<receipt-id>, under receipt) share these fields. Management keys need the receipts:read scope.

The list adds, per receipt:

• action: the action's id, current status, execution (gateway, or caller for decision only), agent (id, name), tool and action name, or null;
• policy: the policy decision behind the action (see below), or null when no policy version decided it.

The list accepts an outcome filter (?outcome=succeeded). Rejection and cancellation receipts are stored with outcome final, so ?outcome=rejected matches nothing: filter by final instead.

Receipt detail fields

Once a receipt's hosted copy was deleted after the retention period, the detail, the bundle download and the decision check answer 410 with the code EVIDENCE_EXPIRED and, in details, the receipt's receipt_id, receipt_object_id, protected_action_id, outcome, bundle_sha256, bundle_size, issued_at and evidence_deleted_at. The receipt is not invalid: verify a copy you downloaded before then.

The receipt detail re-reads the stored bundle on every request and checks it against bundle_sha256. The verification report is computed from those bytes; the Cloud API reuses a report it already computed for the same bytes while the trusted attesters and the signers' stored identity documents are unchanged. Besides receipt it returns:

verification.valid is true only when every check passed and no signer's identity has equivocated.

The policy decision

policy describes the policy version that decided the action, as recorded on the action:

GET /api/v1/orgs/<org-id>/receipts/<receipt-id>/decision-check re-evaluates the stored policy document with the digest signed into the TASK and reports whether it still gives the signed decision. See Versions.

In the dashboard

The Receipts page lists receipts with the columns Receipt, Outcome, Agent and Issued, plus Issuer when the listed receipts have more than one issuer. For a rejection or cancellation receipt, the Outcome column shows the action's status (Rejected or Cancelled) instead of final.

A receipt's page shows:

• the Receipt card: Action, Outcome (for final, also the action's status), Result when it differs from the outcome, Issuer, Issued at and Workflow;
• Identifiers: Receipt object, Thread (task), Head object, Result digest, Workflow digest, Bundle SHA-256 and Bundle size;
• Signed steps: the thread in order and who signed each step;
• Participants: each signer, which steps they signed, and their KID;
• the buttons Verify in this browser and Download .kbundle.

The page header shows the action's status for a final outcome, and so does the Receipt card on the action page.

What the agent gets

When a call completes, the Gateway adds receipt identifiers to the tool result under _meta.kblock:

Refusals of actions that ended with a receipt (rejected, cancelled, failed) carry the receipt IDs in _meta.kblock too. The TypeScript client and the Python client expose them on their results.

Summary keys

The summary is derived from the signed steps, never copied from the issuer. Its keys depend on which steps are on the path:

The …_by key holds the signer's KID, the second key the step's object ID, and …_on_behalf_of the KID the step acted for, when it did. steps lists every step in order with its type, id, actor and, when present, on_behalf_of and delegations. result_digest is a digest of the RESULT's payload, not of the upstream system's state.

A cancellation receipt covers the path TASK → CANCELLATION only: a proposal or approval that existed beside it is not on the path and not in its summary.

Bundle structure

A .kbundle file is JSON with this shape:

{
  "kblock_bundle": "0.1",
  "receipt": { /* the signed RECEIPT object */ },
  "objects": [ /* every signed object the receipt covers */ ],
  "identities": [ /* identity documents of every signer, including the issuer */ ]
  // "disclosures": [ … ]  only when an encrypted payload is revealed
}

The Cloud API serves the bundle at GET /api/v1/orgs/<org-id>/receipts/<receipt-id>/bundle, with content type application/vnd.kblock.bundle+json, the file name receipt-<receipt_object_id>.kbundle, and the header x-kblock-bundle-sha256. It serves the bytes only after checking them against the recorded hash.

What these fields do not tell you

• A receipt is about the steps on its path. A cancellation receipt says nothing about an approval that existed beside it.
• For an ordinary upstream server, the RESULT is the Gateway's own statement of what the upstream returned. Only an attestation from a K-Block-aware upstream adds the upstream's signature.
• An interrupted execution has outcome failed although its real outcome is unknown; check the action's error_code (INTERRUPTED).
• The tool's binding pin (credential version, input schema, amount mapping) is checked by the Gateway against the tool's authorized binding stored in K-Block, and is not part of the signed evidence.
• Times such as issued_at are written by the signer; the receipt does not prove them independently.