PBI
Presence-Bound Identity
Official SDK · Node/TypeScript

Integrate PBI in minutes with presencebound-sdk.

A production-grade client for PresenceBound Identity (PBI): typed methods, consistent error semantics, and a clean, audit-friendly integration surface. Built for enterprise systems where correctness and traceability matter.

npm package End-to-end exampleAPI docsClient portal
Compatibility
Runtime + module support
Designed for modern server runtimes and enterprise deploy pipelines.
Supported environments
RuntimeSupportedNotes
Node.js18+Uses built-in fetch / URL / AbortController
ESMYesStandard import syntax
CommonJSYesrequire() supported via CJS build
BrowsersNot targetedCORS + credential ceremony is application-specific
Need Node 16? Polyfill fetch (e.g. undici) before importing the SDK.
Install
Start here
Copy/paste paths that work in real production repos.
Install the SDK
npm i presencebound-sdk
Configure environment
# Required
PRESENCEBOUND_API_KEY=replace_me

# Optional
PRESENCEBOUND_BASE_URL=https://api.kojib.com
Create API keys in the client portal. Keys are shown once.
Quickstart
Minimal client
Create a challenge, verify presence, and persist receipts for audit.
ESM (recommended)
import { PresenceBound, PresenceBoundError } from "presencebound-sdk";

const client = new PresenceBound({
  apiKey: process.env.PRESENCEBOUND_API_KEY ?? "",
  baseUrl: "https://api.kojib.com",
  timeoutMs: 15000,
  userAgent: "your-app/1.0.0"
});

async function run() {
  const challenge = await client.createChallenge({
    actionHashHex: "a".repeat(64),
    purpose: "ACTION_COMMIT"
  });

  console.log("challengeId:", challenge.data.id, "requestId:", challenge.requestId);

  // Auto-pagination
  for await (const item of client.iterateReceipts({ limit: 100, order: "desc" })) {
    console.log(item.receipt.id, item.receipt.decision);
  }
}

run().catch((err) => {
  if (err instanceof PresenceBoundError) {
    console.error({ status: err.status, requestId: err.requestId, details: err.details });
    process.exit(1);
  }
  throw err;
});
CommonJS
const { PresenceBound, PresenceBoundError } = require("presencebound-sdk");

const client = new PresenceBound({
  apiKey: process.env.PRESENCEBOUND_API_KEY || "",
  timeoutMs: 15000,
  userAgent: "your-app/1.0.0"
});

(async () => {
  try {
    const r = await client.createChallenge({
      actionHashHex: "a".repeat(64),
      purpose: "ACTION_COMMIT"
    });
    console.log("challengeId:", r.data.id, "requestId:", r.requestId);
  } catch (err) {
    if (err instanceof PresenceBoundError) {
      console.error({ status: err.status, requestId: err.requestId, details: err.details });
      process.exit(1);
    }
    throw err;
  }
})();
Errors
Consistent semantics (enterprise friendly)
Non-2xx responses throw a typed PresenceBoundError.
PresenceBoundError
Use requestId to correlate incidents across app logs, webhook deliveries, and support. Structured server errors are available under details when present.
try {
  await client.verifyChallenge({ challengeId, assertion });
} catch (err) {
  if (err instanceof PresenceBoundError) {
    // Correlate incidents via requestId when present
    console.error({
      status: err.status,
      requestId: err.requestId,
      message: err.message,
      details: err.details
    });
  }
}
Fields:
- status: number
- requestId?: string
- details?: { error: string; issues?: Record<string, unknown>[] }
Surface area
What the SDK covers
A single client that cleanly maps to the PBI API surface without hiding semantics.
Core PBI
Challenge issuance, verification, receipts listing, and receipt verification.
client.createChallenge(...)
client.verifyChallenge(...)
client.listReceipts(...)
client.iterateReceipts(...)
client.getReceipt(...)
client.verifyReceipt(...)
Compliance / Evidence
Export signed evidence packs (ZIP) for offline audit and investigation workflows.
client.exportReceipts(...) -> Uint8Array (zip)
Billing
Retrieve usage and invoices for governance and finance workflows.
client.getUsage(month?)
client.listInvoices()
Examples
End-to-end demo
The fastest route to first verified receipt.
Node + Express + WebAuthn
A complete example that creates challenges on the server, performs WebAuthn in the browser, and verifies via PBI.
./packages/presencebound-sdk/examples/node-sdk/
Operational guidance
Production notes
What enterprise reviewers expect: decision gating, hashing discipline, and traceable operations.
Decision gate
Proceed only when decision === "PBI_VERIFIED". Treat all other decisions as “do not execute”.
Action hashing
Hash the exact irreversible action (actor, target, amounts, policy). Canonicalize encoding and version your action schema.
Request correlation
Log requestId and attach it to incident tickets. It’s the fastest route to root-cause and audit reconstruction.
Timeouts
Use timeouts in all clients and treat retries as idempotent-only unless your action is designed for retry.