Reconciliation

In Keel, reconciliation is the practice of relating an AI Permit decision to later closeout, cost or receipt evidence. The strength of that relationship depends on the route and the provenance of the later evidence. Reconciliation does not by itself prove that the ultimate external side effect occurred.

Reconciliation is delivered through three customer-facing tracks. The usage verification track attaches customer-supplied receipt or callback evidence to permit-first decisions. Pre-dispatch envelope reconciliation relates estimated cost reservations to cost observed on Keel-managed execution. The financial_reconciliation export packages recorded reconciliation rows as a signed bundle for external review.

Auditors expect to see decisions reconcile with outcomes. Finance teams expect to verify that spend reconciles with budgets. Compliance teams expect signed evidence bundles. The three tracks together produce records that answer all three.

The three tracks

The first two tracks are reconciliation operations — they produce reconciliation records as part of the request lifecycle. The third track is the export surface that packages those records for external review. The next three sections walk each track in turn.

Track 1 — Usage verification track

After caller-owned execution, callers can attach receipt or callback evidence to the Permit. Keel records the supplied material and its declared verification state. On this generic route, Keel does not directly observe the provider call or independently establish that the material originated with the provider.

The track is independent of permit completion state. A permit can be completed with caller-reported usage but unverified against provider receipts; later verification can promote it to verified or reconciled without changing the completion state. Verification tightens the evidence; it does not gate the permit.

Surface

POST /v1/permits/{permit_id}/usage/verify

Authentication: admin-scope project API key.

Verification methods

The public verify route accepts several method identifiers. The two commonly used external-evidence methods are:

• provider_receipt — the caller supplies a provider request ID plus receipt JSON, a receipt hash, or an evidence URL. Keel checks required fields and records the supplied material. This generic path does not authenticate provider origin.
• signed_callback — the caller supplies a provider request ID, signature, key ID and signing time. Keel checks that those fields are present and records them. This generic path does not itself cryptographically validate the signature.

Self-reported usage without verification material remains caller-asserted on the permit and does not advance verification state.

The request also carries the status to record. A verified or reconciled status is therefore a recorded workflow state, not a claim that this endpoint performed provider authentication. Use a specifically documented authoritative verification path before describing receipt origin as independently verified.

State machine

The verification state is recorded on the permit and progresses through:

unverified → pending → verified | rejected | reconciled

A Permit may receive additional verification records — for example, a supplied receipt followed by callback material. Each call updates the recorded state and appends to the Permit evidence.

accounting_disposition

Permits also carry an accounting_disposition field that captures the closeout outcome:

• A permit-first request that is never closed out is marked missing_usage_report. The governed-request count remains anchored to permit issuance, and the accounting record stays open for later closeout.
• A permit-first request that is closed out without verification material remains accounting_disposition-clean but verification.status = unverified.
• A permit that successfully verifies advances verification.status to verified (and optionally to reconciled); accounting_disposition is unaffected.

accounting_disposition and verification.status are different fields. The first describes the closeout state of the permit; the second describes the strength of the evidence backing that closeout.

Worked example

Attach provider-receipt material to a closed-out permit:

curl -sS -X POST https://api.keelapi.com/v1/permits/permit_01jyf4m3n8q2r6t9v1w5x7y0z/usage/verify \
  -H "Authorization: Bearer keel_sk_admin_project_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "provider_receipt",
    "status": "pending",
    "provider_request_id": "req_abc123",
    "receipt_json": {
      "request_id": "req_abc123",
      "object": "chat.completion"
    }
  }'

Response — the supplied evidence and requested state are recorded:

{
  "id": "5fdc3f3d-eefb-4a51-a749-0c9d98b21b87",
  "permit_id": "f5c1d85e-2a35-4d0c-8627-e9eb0f981c4d",
  "project_id": "c4b29f5e-0931-40ca-8713-0f54bcc73c71",
  "method": "provider_receipt",
  "status": "pending",
  "provider_request_id": "req_abc123",
  "receipt_json": {
    "request_id": "req_abc123",
    "object": "chat.completion"
  },
  "receipt_sha256": "d34db33fd34db33fd34db33fd34db33fd34db33fd34db33fd34db33fd34db33f",
  "signature_key_id": null,
  "signed_at": null,
  "evidence_url": null,
  "metadata": null,
  "reason": null,
  "created_at": "2026-04-25T18:00:00Z",
  "verified_at": null
}

There is no automatic provider-authentication step implied by this response. A later caller may submit another record with status: "verified" or status: "reconciled" only after the caller’s own supported validation workflow has established that state.

The permit’s audit record now carries the receipt material. Subsequent reads of the permit return the verification state on every permit detail and audit response.

Track 2 — Pre-dispatch envelope reconciliation

When budget envelopes are configured on a project, every execution-backed request reserves estimated cost before provider dispatch and reconciles to actual cost after the provider responds. The result is that reserved funds stay visible while a request is in flight, and the project’s spent total reflects observed provider cost rather than caller-reported numbers.

This track runs automatically on POST /v1/executions, POST /v1/execute, and POST /v1/proxy/* whenever the project has budget envelopes configured. There is no separate API to invoke envelope reconciliation — it is part of the request lifecycle.

How envelope reconciliation runs

Before provider dispatch, Keel estimates the request cost from the request’s token estimates and locks that amount against the envelope’s remaining budget. The request proceeds with the estimate held; the envelope’s remaining budget excludes that lock. After the provider responds, the lock is released, the actual cost is recorded as spent, and any surplus is returned to the envelope.

If the envelope’s remaining budget cannot cover the estimate, the request denies before provider dispatch with budget.envelope_exhausted. Reconciliation only runs when the lock succeeded.

Accounting fields

The envelope record carries the running totals:

• total_budget — the configured cap.
• reserved — funds locked by in-flight requests, not yet adjusted.
• spent — funds consumed by completed requests.
• remaining = total_budget - reserved - spent.

All values are denominated in microdollars (USD × 10⁶) to avoid floating-point rounding in budget accounting.

When verification and envelope co-occur on a permit

Envelope reconciliation runs on the Permit that backs a managed execution request, just as the policy decision and routing record do. Supplied receipt evidence can be attached to that same Permit later through the verify route. The two tracks are different evidence layers on the same Permit and are not mutually exclusive.

For the full envelope contract — failure modes, paused envelopes, providing estimates — see Budget Envelopes.

Track 3 — Financial-reconciliation export

Auditors and finance teams can request a signed bundle of every reconciliation row a project produced over a window. The bundle is delivered through the compliance export surface and verifies independently using the same Ed25519 manifest as every other Keel signed export.

This track is the export-surface companion to Tracks 1 and 2. It does not produce reconciliation records on its own — it packages records that the verification track and the envelope track wrote into the project’s evidence stream.

Surface

POST /v1/compliance/exports

with export_type: "financial_reconciliation".

Authentication: admin-scope project API key.

Bundle contents

The financial_reconciliation export bundles usage and billing reconciliation rows for the requested window. Each row carries the permit identifier, the per-permit reconciliation evidence (verification state, envelope reconciliation outcome, actual usage), and the cost values used for billing.

The bundle is signed with Ed25519 and ships with the same manifest used by every Keel signed export. Independent verification follows the standard verifier flow — see Verifying Keel Evidence.

Sister export types

Two export types ship alongside financial_reconciliation and are commonly used in the same audit workflow:

• access_review — a signed zip of CSVs covering users, organization members, team members, API keys, provider keys, and approver groups. Raw key material and key hashes are never included.
• incident_evidence — a signed zip with governance events, permits, admin actions, and bracket checkpoints (the last externally-anchored checkpoint before the incident window and the first after it) plus incident metadata. The bracket pair provides forward and backward tamper-evidence for the incident window.

For the full export-type table including these and the other compliance export types, see Signed Exports.

How to choose between tracks

The three tracks share the project’s reconciliation evidence stream. Choosing between them is a question of integration shape and review need:

• You control the provider call (permit-first). Use the usage verification track to attach receipt evidence to the permit. The track is independent of completion state, so you can verify after closeout.
• Keel makes the provider call (execution-backed surfaces). Envelope reconciliation runs automatically when budget envelopes are configured. No additional integration is required to produce the reconciliation rows.
• An auditor or finance reviewer needs a signed bundle of reconciliation evidence over a window. Request the financial_reconciliation export. The bundle pulls from records produced by the other two tracks.

The verification track and envelope reconciliation are not mutually exclusive. A permit produced by an execution-backed route is reconciled by the envelope and can additionally have verification material attached. The audit record carries both layers of evidence on the same permit.

What this surface does and does not claim

• The verification track narrows the permit-first trust gap by binding the permit to receipt evidence. It does not remove the gap. Keel still does not directly observe the provider call on permit-first flows; verification material is the customer-supplied bridge.
• Envelope reconciliation reflects Keel-observed actual cost from execution-backed dispatch. It is not a reconciliation against provider-side billing events; if a provider issues a corrected invoice later, that correction is not automatically merged into the envelope.
• The financial_reconciliation export is a signed bundle of records as Keel persisted them. Like all signed exports, the signature attests the bundle has not been modified; it does not attest the bundle is complete relative to all reconciliation events ever written for the project. See Verifying Keel Evidence for the precise scope of what the verifier proves.
• Verification states (verified, rejected, reconciled) describe the strength of receipt evidence attached to the permit. They do not describe the policy decision — that is captured by the permit’s decision and reason_code.
• Reconciliation does not retroactively change permit decisions. A verified permit that was originally an allow remains an allow; a rejected verification on a previously-allowed permit does not retroactively deny it.

Plan tier availability

Sister export types in the same audit workflow:

For the full per-tier feature matrix, see Plans & Entitlements.

Related pages

• Permits — the canonical decision-record key that reconciliation evidence attaches to
• Budget Envelopes — the full envelope contract that Track 2 runs inside
• Signed Exports — the export surface that delivers Track 3
• Verifying Keel Evidence — independent verification of the signed bundle
• Plans & Entitlements — full plan-tier entitlement matrix