Skip to main content
This page walks through a single authority verification flow from end to end: sending a request, receiving an attestation, verifying it, and looking up the audit record.

​
Prerequisites

  • Parmana server running at http://localhost:3000 (see Quick Start)
  • Node.js 18+

​
Install the client SDK

npm install @parmanasystems/sdk-client
@parmanasystems/sdk-client is an HTTP client that calls the running Parmana server. If you want to run the governance engine directly in your Node.js process without a server, use @parmanasystems/core instead. See SDK Installation.

​
Step 1 — Create the client

import { ParmanaClient } from "@parmanasystems/sdk-client";

const client = new ParmanaClient({
  baseUrl: "http://localhost:3000",
  apiKey: process.env.PARMANA_API_KEY,
});
ParmanaClientOptions:
FieldTypeRequiredDescription
baseUrlstringYesBase URL of the Parmana server
apiKeystringNoBearer token — required when the server has PARMANA_API_KEY set

​
Step 2 — Check the runtime

const health = await client.health();
console.log(health.status);          // "ok"
console.log(health.audit_db);        // true — Postgres connected
console.log(health.signing_mode);    // "env" — key loaded from environment
Do not proceed if health.status !== "ok".

​
Step 3 — Verify authority before execution

import type { ExecutionAttestation } from "@parmanasystems/sdk-client";

const attestation: ExecutionAttestation = await client.execute({
  executionId: "claim-2024-00441",    // your business transaction ID — must be unique
  policyId: "claims-approval",
  policyVersion: "1.0.0",
  signals: {
    claimAmount: 1200,
    customerTier: "gold",
    priorFraudSignals: false,
  },
});

console.log(attestation.decision);
// {
//   action: "approve",
//   requires_override: false,
//   reason: "Standard approval: claim within tier limit"
// }

console.log(attestation.execution_state);
// "completed"  (or "pending_override" if requires_override is true)

console.log(attestation.execution_fingerprint);
// "a3f8d2..." — SHA-256 of canonical signals; the semantic identity of this decision

​
What executionId means

executionId identifies your business transaction. You choose it — typically a claim ID, transaction ID, or request UUID from your system. The governance runtime will reject any subsequent request with the same executionId (replay protection).

​
What execution_fingerprint means

execution_fingerprint is computed by the runtime: a SHA-256 hash of the canonical form of { policyId, policyVersion, signals }. Two requests with different executionId values but identical signals and policy will produce the same execution_fingerprint. This is the semantic identity of the decision, independent of which transaction triggered it.

​
Step 4 — Handle the execution state

if (attestation.execution_state === "completed") {
  // Decision is final. Check the action before proceeding.
  if (attestation.decision.action === "approve") {
    console.log("Authorized to proceed");
    console.log(`Reason: ${attestation.decision.reason}`);
  } else {
    console.log(`Decision: ${attestation.decision.action}`);
    console.log(`Reason: ${attestation.decision.reason}`);
  }

} else if (attestation.execution_state === "pending_override") {
  // Decision requires human review before execution can proceed.
  // Store the attestation. Route to your review queue.
  console.log("Execution blocked — pending human override");
  console.log(`executionId: ${attestation.executionId}`);
}

​
Step 5 — Verify the attestation

Verification is stateless. It requires only the attestation and the runtime’s public key — no database, no network call to your infrastructure. 
import type { VerificationResult } from "@parmanasystems/sdk-client";

const result: VerificationResult = await client.verify(attestation);

console.log(result.valid);
// true

console.log(result.checks);
// {
//   signature: "verified",
//   runtime: "verified",
//   schema: "verified"
// }
If result.valid is false, do not proceed with the action. A failed verification means the attestation has been tampered with, was produced by an untrusted runtime, or the signature does not match the public key.
After you execute the authorized action in your system, confirm it against the attestation. This creates a post-execution integrity record that proves the action taken matches what was authorized. 
const proof = await client.confirmExecution({
  attestation,
  executedAction: {
    actionType: "claim_payment",
    actionId: "claim-2024-00441",
    actionTimestamp: new Date().toISOString(),
    actionDetails: {
      amount: 1200,
      currency: "USD",
      recipient: "policy-holder-7821",
    },
  },
  timeWindowSeconds: 300,  // action must have occurred within 5 minutes of the decision
});

console.log(proof.matched);
// true — the executed action matches the authorized decision

​
Step 7 — Look up the audit record

const record = await client.audit.decision("claim-2024-00441");

console.log(record.decision);           // "approved"
console.log(record.execution_state);    // "completed"
console.log(record.verification_valid); // true
console.log(record.signature_verified); // "verified"
console.log(record.executed_at);        // "2024-01-15T10:23:44.000Z"

​
Complete example

import { ParmanaClient } from "@parmanasystems/sdk-client";

async function governedClaimApproval(
  claimId: string,
  signals: Record<string, unknown>
) {
  const client = new ParmanaClient({
    baseUrl: process.env.PARMANA_URL ?? "http://localhost:3000",
    apiKey: process.env.PARMANA_API_KEY,
  });

  // 1. Execute
  const attestation = await client.execute({
    executionId: claimId,
    policyId: "claims-approval",
    policyVersion: "1.0.0",
    signals,
  });

  // 2. Verify immediately
  const verification = await client.verify(attestation);
  if (!verification.valid) {
    throw new Error(`Attestation verification failed for ${claimId}`);
  }

  // 3. Handle state
  if (attestation.execution_state === "pending_override") {
    return { status: "pending_override", executionId: claimId };
  }

  // 4. Take the authorized action
  if (attestation.decision.action === "approve") {
    await processClaim(claimId, signals);
  }

  return {
    status: attestation.decision.action,
    attestation,
    verification,
  };
}

​
What you have proven

After completing this flow, you have a cryptographic record that proves:
  1. The claim was evaluated against policy claims-approval version 1.0.0
  2. The exact signals submitted (their canonical hash)
  3. The runtime version and binary hash that produced the decision
  4. The policy bundle content hash
  5. The decision outcome and matched rule
  6. That none of the above was modified after signing
This record can be verified by any party with the public key, years in the future, without access to your database or runtime.

​
Troubleshooting

execute() throws ParmanaApiError with status 422 Check the error message:
  • [INV-013@replay] — executionId already used. Each business transaction must have a unique ID.
  • Policy not found — bundle not deployed at policies/claims-approval/1.0.0/.
  • Signals validation failed — signals do not match the policy’s signalsSchema.
verify() returns valid: false Do not proceed. Check result.checks to identify which check failed:
  • signature: "failed" — attestation was modified after signing.
  • runtime: "failed" — attestation from a different runtime version.
  • schema: "failed" — schema version incompatibility.
audit.decision() returns 404 The decision was not recorded in Postgres. Check health.audit_db — if false, Postgres was not connected when the execution ran.