> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# First Authority Verification

> Walk through the complete flow — request, decision, attestation, verification — using the SDK

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](/getting-started/quickstart))
* Node.js 18+

***

## Install the client SDK

```bash theme={null}
npm install @parmanasystems/sdk-client
```

<Note>
  `@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](/sdk/installation).
</Note>

***

## Step 1 — Create the client

```typescript theme={null}
import { ParmanaClient } from "@parmanasystems/sdk-client";

const client = new ParmanaClient({
  baseUrl: "http://localhost:3000",
  apiKey: process.env.PARMANA_API_KEY,
});
```

`ParmanaClientOptions`:

| Field     | Type     | Required | Description                                                       |
| --------- | -------- | -------- | ----------------------------------------------------------------- |
| `baseUrl` | `string` | Yes      | Base URL of the Parmana server                                    |
| `apiKey`  | `string` | No       | Bearer token — required when the server has `PARMANA_API_KEY` set |

***

## Step 2 — Check the runtime

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
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"
// }
```

<Warning>
  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.
</Warning>

***

## Step 6 — Confirm execution (optional but recommended)

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.

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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.

***

<Cards>
  <Card title="SDK Installation" href="/sdk/installation">
    All packages and installation options
  </Card>

  <Card title="SDK Examples" href="/sdk/examples/insurance-claims">
    Insurance, payments, healthcare — complete TypeScript examples
  </Card>

  <Card title="POST /execute" href="/api/execute">
    Full execute endpoint reference
  </Card>

  <Card title="Override Workflow" href="/override/pending">
    What happens when execution\_state is pending\_override
  </Card>
</Cards>