Reconciliation

In Keel, reconciliation is the practice of binding decisions to outcomes. Every governance decision Keel issues — a permit, a cost reservation, an evidence claim — is followed by a record that reconciles what was promised against what actually happened. Those reconciliation records are themselves auditable evidence.

Reconciliation is delivered through three customer-facing tracks. The usage verification track binds permit-first decisions to provider execution evidence. Pre-dispatch envelope reconciliation binds estimated cost reservations to actual provider cost. The financial_reconciliation export packages reconciliation records 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

When a permit-first execution completes, callers can attach stronger receipt evidence to the permit so the audit record carries provider-side proof, not just self-reported usage. The verification track is the surface for that attachment.

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 two methods, both of which require evidence that the provider actually responded:

• provider_receipt — caller supplies the provider’s request id and receipt JSON. Keel records the receipt material and the verification state advances when the receipt is accepted.
• signed_callback — caller supplies signed-callback material that proves the provider response was received. Keel records the callback material and the verification state advances when the signature validates.

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

State machine

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

unverified → pending → verified | rejected | reconciled

A permit may be re-verified — for example, attaching a provider receipt first, then a signed callback later. Each call updates the verification state and appends to the permit’s reconciliation 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",
    "provider_request_id": "req_abc123",
    "receipt_json": {
      "request_id": "req_abc123",
      "object": "chat.completion"
    }
  }'

Initial response — verification accepted, state advances to pending:

{
  "permit_id": "permit_01jyf4m3n8q2r6t9v1w5x7y0z",
  "verification": {
    "method": "provider_receipt",
    "status": "pending",
    "updated_at": "2026-04-25T18:00:00Z"
  }
}

After processing — state advances to verified:

{
  "permit_id": "permit_01jyf4m3n8q2r6t9v1w5x7y0z",
  "verification": {
    "method": "provider_receipt",
    "status": "verified",
    "updated_at": "2026-04-25T18:00:12Z"
  }
}

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 an execution-backed request, just as the policy decision and routing record do. Verification material can be attached to that same permit later through the verify route, layering provider-side receipt evidence on top of envelope-observed cost. 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