Approval and Rejection

How to approve or reject a pending override using POST /override

The override request

All pending overrides are resolved via POST /override. The approved field determines whether the override is approved or rejected.

Required fields:

Field	Type	Description
executionId	string	Matches the executionId from the original execute request
approved	boolean	true = approve, false = reject
approvedBy	string	Identifier of the reviewer — recorded in the override audit record
approverRole	string	Role of the reviewer — recorded in the override audit record
reason	string	Human-readable reason — part of the signed override record

All five fields are required regardless of whether the override is being approved or rejected.

---

Approval

const approval = await client._request<{
  status: "approved";
  overrideId: string;
  resolution: {
    status: string;
    execution_fingerprint: string;
    signature: string;
  };
}>("/override", {
  method: "POST",
  body: JSON.stringify({
    executionId: "claim-CLM-2024-00443",
    approved: true,
    approvedBy: "adjuster-sarah-chen",
    approverRole: "senior_adjuster",
    reason: "Verified documentation supports claim. Approved for payment.",
  }),
});

console.log(approval.status);                        // "approved"
console.log(approval.overrideId);                    // cryptographic override record ID
console.log(approval.resolution.status);             // "executed"
console.log(approval.resolution.execution_fingerprint); // fingerprint of the override execution
console.log(approval.resolution.signature);          // Ed25519 signature of the override-authorized execution

---

Rejection

const rejection = await client._request<{
  status: "rejected";
  executionId: string;
}>("/override", {
  method: "POST",
  body: JSON.stringify({
    executionId: "claim-CLM-2024-00443",
    approved: false,
    approvedBy: "adjuster-sarah-chen",
    approverRole: "senior_adjuster",
    reason: "Documentation insufficient. Claim does not meet coverage criteria.",
  }),
});

console.log(rejection.status);      // "rejected"
console.log(rejection.executionId); // "claim-CLM-2024-00443"

When rejected, the execution remains blocked. No action is taken. The audit record is updated to resolution_status: "rejected".

---

curl — approval

curl -s -X POST http://localhost:3000/override \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PARMANA_API_KEY" \
  -d '{
    "executionId": "claim-CLM-2024-00443",
    "approved": true,
    "approvedBy": "adjuster-sarah-chen",
    "approverRole": "senior_adjuster",
    "reason": "Verified documentation. Approved."
  }' | jq .

---

curl — rejection

curl -s -X POST http://localhost:3000/override \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PARMANA_API_KEY" \
  -d '{
    "executionId": "claim-CLM-2024-00443",
    "approved": false,
    "approvedBy": "adjuster-sarah-chen",
    "approverRole": "senior_adjuster",
    "reason": "Documentation insufficient."
  }' | jq .

---

What the server does on approval

1. Loads the pending override record from audit_overrides — returns 404 if not found
2. Checks that resolution_status === "pending" — returns 409 if already resolved
3. Calls approveOverride() to create a signed override authorization record
4. Calls resolveOverrideFromContext() to re-evaluate the authority verification outcome under override authority
5. Transitions replay state in Redis to OVERRIDDEN
6. Updates audit_overrides to resolution_status: "approved"
7. Returns { status: "approved", overrideId, resolution }

What the server does on rejection

1. Loads the pending override record — returns 404 if not found
2. Checks that resolution_status === "pending" — returns 409 if already resolved
3. Updates audit_overrides to resolution_status: "rejected" (no execution occurs)
4. Returns { status: "rejected", executionId }

---

The overrideId

When an override is approved, the server returns an overrideId — a cryptographic identifier for the override authorization record. This ID is stored in audit_overrides.

The overrideId is the SHA-256 of the canonical override payload (including executionId, approved_by, approver_role, reason, and a timestamp). It is reproducible and unique.

---

Auditing who approved what

Override records include approvedBy and approverRole. Your system should:

• Authenticate reviewers before allowing them to call POST /override
• Pass the authenticated user’s ID as approvedBy
• Store the override record ID (overrideId) in your business system alongside the claim/transaction

This creates a complete chain: decision → override request → named approver → signed resolution.

---

Troubleshooting

404 “Pending override not found” — Verify:

• The original execution returned execution_state: "pending_override"
• audit_db is true in /health — without Postgres, overrides cannot be stored
• The executionId matches exactly (no prefix differences)

409 “Override already resolved” — Check the audit record:

const record = await client.audit.decision(executionId);
console.log(record.execution_state); // "completed" or "pending_override"

503 — The signer or replay store is not configured. Both are required for override resolution.