B2B Enterprise Use Cases & Integration Checklists

Integrating Volidator into your production software typically follows a standard checklist. Depending on your regulatory environment (e.g., SOC2, HIPAA, PCI-DSS) or presentation goals, some steps are strictly [Required] while others are [Optional].

This guide covers core design behaviors (header conversions and signed URLs) and walks through three comprehensive B2B enterprise integration scenarios.

---

Core System Behaviors

1. How metadata paths map to table headers

When you pin a dynamic decrypted metadata path inside your custom log table columns (e.g. specifying metadata.property_address), the Volidator dashboard UI automatically formats the column header for optimal readability on the client side:

• Prefix stripping: It removes the leading metadata. namespace.
• Symbol replacement: All underscores (_) and hyphens (-) are replaced with spaces.
• Title formatting: A capitalization transform is applied.
• Example: metadata.property_address automatically renders as Property Address in the table header.

2. Why Embed URLs are generated programmatically

Embed URLs are programmatically signed at runtime on your backend server using the SDK, rather than pre-generated statically in the dashboard.

• Session-bound security: Programmatic generation allows B2B platforms to dynamically bind logs to the active user’s session scope, restrict queries to specific tenants (tenantId), and sign short-lived tokens (e.g. expiring in 15 minutes) for maximum security.
• Zero-knowledge isolation: The backend SDK generates and signs these tokens server-side, appending the decryption key hash fragment only at the end of the client-side URL. This prevents keys from ever touching Volidator’s network.

---

The Standard Integration Checklist

Step	Type	Purpose
1. SDK Installation	[Required]	Installs the open-source client utility into your backend.
2. Client Initialization	[Required]	Configures API credentials and client-side Encryption Keyrings.
3. IAM Middleware Context	[Optional]	Hooks authentication flows to auto-extract IP, browser, and device telemetry.
4. Logging Compliance Events	[Required]	Ingests cryptographically sealed events with custom metadata.
5. PHI/PII Redaction Rules	[Optional]	Configures client-side patterns to redact or mask names/IDs before ingestion.
6. Scoped Embed URL Generation	[Optional]	Programmatically signs scoped token parameters at runtime.
7. Iframe Portal Rendering	[Optional]	Embeds the zero-knowledge decryption widget inside your tenant dashboard.
8. SIEM Pipeline Sync	[Optional]	Integrates real-time feeds to external platforms (Splunk, Datadog).

---

Use Case 1: Property Management B2B Portal

Goal: Let property landlords review key-box checkouts and lease transactions on a dashboard table showing only relevant property dimensions.

🛠️ Step-by-Step Integration

1. SDK Installation [Required]

Add the SDK to your node backend server:

npm install @volidator/sdk

2. Client Initialization [Required]

Initialize the Volidator client with your credentials and the encryption key:

import { VolidatorClient } from "@volidator/sdk";

const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
  projectId: process.env.VOLIDATOR_PROJECT_ID!,
  clientSecret: process.env.VOLIDATOR_CLIENT_SECRET!,
});

3. IAM Middleware Context [Optional]

For web actions, capture network telemetry automatically before logging:

// Express middleware example
app.use((req, res, next) => {
  req.auditContext = volidator.extractContext(req);
  next();
});

4. Logging Compliance Events [Required]

Log critical actions with property parameters placed under metadata:

await volidator.log({
  action: "KEYBOX.UNLOCKED",
  actor: "[email protected]",
  target: "lockbox_unit_4b",
  tenant: "landlord_inc_corp",
  context: req.auditContext, // Optional captured network telemetry
  metadata: {
    property_name: "Oakridge Estates",
    property_address: "742 Evergreen Terrace",
    current_zip: "90210",
    currently_living: "Homer Simpson",
    contract_expires_at: "2027-06-30"
  }
});

5. PHI/PII Redaction Rules [Optional]

(Not needed for basic property logs. Skip.)

6. Scoped Embed URL Generation [Optional]

Generate a scoped URL. Exclude developer columns like actor and timestamp to show only landlord fields:

const { embedUrl } = await volidator.generateEmbedToken({
  tenantId: "landlord_inc_corp",
  scope: "tenant",
  expiresIn: "30m",
  view: {
    columns: [
      "metadata.property_name",
      "metadata.property_address",
      "metadata.current_zip",
      "metadata.currently_living",
      "metadata.contract_expires_at"
    ]
  }
});

7. Iframe Portal Rendering [Optional]

Render the iframe widget in your portal:

<iframe src={embedUrl} width="100%" height="600" style={{ border: 'none' }} />

8. SIEM Pipeline Sync [Optional]

(Not required for landlords. Skip.)

---

Use Case 2: Healthcare PHI / HIPAA Audit Trail (EMR Portal)

Goal: Capture access to Electronic Medical Records. Maintain zero-knowledge encryption of patient health identifiers (PHI) and render a strict clinician compliance audit log.

🛠️ Step-by-Step Integration

1. SDK Installation [Required]

npm install @volidator/sdk

2. Client Initialization [Required]

Use active keyrotation keyrings for HIPAA-compliant key separation:

const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  activeEncryptionKeyId: "v2",
  keyring: {
    "v2": "new-encryption-key-entropy...",
    "v1": "past-encryption-key-entropy..."
  },
  projectId: process.env.VOLIDATOR_PROJECT_ID!,
  clientSecret: process.env.VOLIDATOR_CLIENT_SECRET!,
});

3. IAM Middleware Context [Optional]

Ensure all clinic network and clinician session variables are captured:

app.use((req, res, next) => {
  req.clinicContext = volidator.extractContext(req);
  next();
});

4. Logging Compliance Events [Required]

Log clinician views of patient charts:

await volidator.log({
  action: "PATIENT_RECORD.VIEWED",
  actor: "[email protected]",
  target: "patient_alice_jones",
  context: req.clinicContext,
  metadata: {
    clinic_name: "Princeton-Plainsboro Teaching Hospital",
    reason_for_access: "Emergency Triage Consultation",
    patient_ssn: "000-12-3456", // PHI field that needs redaction/encryption
    patient_diagnosis: "Lupus"
  }
});

5. PHI/PII Redaction Rules [Optional]

Developers can choose where to store sensitive PHI/PII fields (like SSNs, patient names, or medical diagnostics):

• Host in Your Database (JIT Hydration): Keep the plaintext PII in your own backend database and store only a reference key in Volidator. The browser client pulls the JIT data securely directly from your database on load.
• Host in Volidator’s Vault (Zero-Knowledge Ciphertext): Pass the fields directly inside the metadata object. The SDK encrypts them client-side before ingestion, meaning Volidator only stores secure, unreadable ciphertext.
• None (Redact / Mask Completely): Mask or redact the PII completely client-side before transmission. Any omitted or redacted fields will render as a secure placeholder (e.g. [REDACTED], XXX-XX-1234, or —) inside the audit table.

Example client-side masking helper:

// Custom client-side masking filter
const clientMasker = (key: string, value: any) => {
  if (key === "patient_ssn") return "XXX-XX-" + value.slice(-4);
  return value;
};
// Integrate clientMasker logic in your logging pipelines to scrub PHI payloads.

6. Scoped Embed URL Generation [Optional]

Create an embed URL for clinic auditing. Keep timestamps, show clinician action details, and pin the hospital department:

const { embedUrl } = await volidator.generateEmbedToken({
  actorId: "[email protected]",
  scope: "actor",
  expiresIn: "15m",
  view: {
    columns: [
      "timestamp",
      "action",
      "metadata.clinic_name",
      "metadata.reason_for_access"
    ]
  }
});

7. Iframe Portal Rendering [Optional]

<iframe src={embedUrl} width="100%" height="500" style={{ border: 'none' }} />

8. SIEM Pipeline Sync [Optional]

(Not configured. Skip.)

---

Use Case 3: B2B Fintech Payments Ledger (PCI Audits)

Goal: Audit administrative setting adjustments and high-volume payouts. Forward logs to an enterprise Splunk SIEM for threat detection and compliance checks.

🛠️ Step-by-Step Integration

1. SDK Installation [Required]

npm install @volidator/sdk

2. Client Initialization [Required]

const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
  projectId: process.env.VOLIDATOR_PROJECT_ID!,
  clientSecret: process.env.VOLIDATOR_CLIENT_SECRET!,
});

3. IAM Middleware Context [Optional]

Capture fintech API caller credentials:

app.use((req, res, next) => {
  req.fintechContext = volidator.extractContext(req);
  next();
});

4. Logging Compliance Events [Required]

Log critical administrative events:

await volidator.log({
  action: "API_KEY.CREATED",
  actor: "api_service_account_9",
  target: "payment_routing_rules",
  tenant: "fintech_client_corp",
  context: req.fintechContext,
  metadata: {
    authorized_by: "[email protected]",
    transaction_limit: "5000000",
    currency: "USD"
  }
});

5. PHI/PII Redaction Rules [Optional]

(Not configured. Skip.)

6. Scoped Embed URL Generation [Optional]

(Internal developers monitor logs via the primary dashboard settings interface. Skip embed.)

7. Iframe Portal Rendering [Optional]

(Skip embed.)

8. SIEM Pipeline Sync [Optional]

Configure the SIEM sync pipeline inside the Volidator settings dashboard:

• Set up a forwarding pipeline pointing to your corporate Splunk HEC or Datadog Ingestion HTTP gateway.
• Volidator securely forwards raw encrypted tags and cryptographic hashes to your enterprise SIEM, triggering alerts on unauthorized setting modifications.

---

Use Case 4: Autonomous AI Agent Orchestration (E2EE Tool & Reasoning Logs)

Goal: Track system prompts, reasoning steps, tool calls, and model outputs dynamically without sending raw PII or proprietary prompts to Volidator.

How PII/PHI is Scrubbed in AI Workflows

When auditing AI agents, prompts and tool responses often contain sensitive user names, medical symptoms, or financial values. Logging these prompts directly in plaintext to a logging server makes your audit logging pipeline a major security and compliance risk.

Volidator resolves this by scrubbing or replacing sensitive fields strictly on your backend server (inside the SDK process) before any logs are encrypted and dispatched:

1. Scrubbing Schedule: The SDK applies your PII/PHI scrubbing filters (via redactKeys or referenceKeys) on the metadata payload after the AI model processes the request, but before serialization and network transmission. The raw prompt goes to the LLM as needed, but the copy stored in your audit log is cleaned.
2. Dynamic Redaction Options:
   • Static Redaction (redactKeys): Instantly replaces specified keys (e.g. metadata.user_email) with a secure generic placeholder like [REDACTED:email].
   • Reference-Based Redaction (referenceKeys): Replaces sensitive details with an internal identifier (e.g., mapping [email protected] to [REF:usr_890]). The blind index is computed for secure exact-match queries, but only the reference token is encrypted and sent to Volidator.
   • Browser-Only Hydration: When viewing logs in the dashboard, the user’s browser decrypts the reference token locally and queries your database via a postMessage handshake to show the real email. Volidator’s databases and downstream AI analytics never see the plaintext values.

🛠️ Step-by-Step Integration

1. SDK Installation [Required]

npm install @volidator/sdk

2. Client Initialization [Required]

import { VolidatorClient } from "@volidator/sdk";

const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
  projectId: process.env.VOLIDATOR_PROJECT_ID!,
  clientSecret: process.env.VOLIDATOR_CLIENT_SECRET!,
});

3. Log Ingestion in Agent Workflow [Required]

Capture prompt logs, reasoning states, and final actions in your LLM chain or agent step execution loop:

import { volidator } from "@/lib/volidator";

// Inside your agent tool executor
async function handleSavingsTransfer(agentId: string, amount: number, userId: string) {
  // 1. Perform transaction
  const tx = await db.transfers.create({ from: "savings", to: "checking", amount });

  // 2. Ingest audit event. Sensitive properties are encrypted on-process.
  await volidator.log({
    actor: agentId, // e.g. "agent_financial_advisor_v3"
    action: "AI_AGENT.TOOL_CALL",
    target: tx.id,
    tenant: userId,
    metadata: {
      model: "gpt-4o",
      user_prompt: `Transfer $${amount} to checking`,
      reasoning: "User verified identity via passkey, proceeding with bank API transfer",
      tool_name: "bank_ledger_transfer",
      tokens_used: 480,
      confidence_score: 0.99
    }
  });
}

4. Scoped Embed URL Generation [Optional]

Let users view their autonomous agent’s activity history without exposing system prompts or token details:

const { embedUrl } = await volidator.generateEmbedToken({
  tenantId: "usr_alice_991",
  scope: "tenant",
  expiresIn: "30m",
  view: {
    columns: [
      "timestamp",
      "action",
      "metadata.tool_name",
      "metadata.user_prompt"
    ]
  }
});

---

Use Case 5: Installed Software Client (Desktop/Mobile/CLI App) with Server Gateway

Goal: Collect audit logs from an offline-first desktop client application without exposing your primary Volidator write-keys inside the installed application binary.

🛠️ Step-by-Step Integration

1. Setup a Backend Ingestion Gateway [Required]

Do not call the Volidator API directly from your desktop or mobile code. Route log traffic through a secure backend proxy on your own server.

// Your server-side API Route: POST /api/audit-logs
export async function POST(req: Request) {
  const session = await getSession(req);
  if (!session) return new Response("Unauthorized", { status: 401 });

  const body = await req.json();

  // The server-side SDK acts as the gateway to Volidator
  await volidator.log({
    actor: session.userId,
    action: body.action, // e.g., "DESKTOP_CLIENT.BACKUP_COMPLETED"
    target: body.target, // e.g., "backup_archive_991"
    metadata: {
      client_version: body.clientVersion,
      os: body.os,
      device_id: body.deviceId,
      total_files: body.totalFiles,
      data_size_bytes: body.sizeBytes
    }
  });

  return new Response(JSON.stringify({ success: true }));
}

2. Local Client Event Logging [Required]

From your installed Electron, React Native, or Tauri client, make simple HTTP posts to your proxy gateway:

async function logBackupCompleted(backupId: string, fileCount: number, bytes: number) {
  await fetch("https://api.yourservice.com/api/audit-logs", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      action: "DESKTOP_CLIENT.BACKUP_COMPLETED",
      target: backupId,
      clientVersion: "v2.1.0",
      os: "macOS Sonoma",
      deviceId: "dev_mac_studio_991",
      totalFiles: fileCount,
      sizeBytes: bytes
    })
  });
}

3. Zero-Knowledge Local Decryption [Optional]

To show log history securely inside the installed client without letting Volidator read the events, perform the following steps:

1. Generate an embed token on your backend server scoped to the client user.
2. Return the embedUrl (which contains the decryption keyring strictly inside the #hash parameter) to the client.
3. The installed app displays the iframe locally. Keys stay in the client window sandbox.

// Backend:
const { embedUrl } = await volidator.generateEmbedToken({
  actorId: "usr_alice_991",
  scope: "actor",
  expiresIn: "1h",
  view: {
    columns: ["timestamp", "action", "metadata.client_version", "metadata.data_size_bytes"]
  }
});

// Frontend (Desktop Client):
// Render the signed edge URL inside a webview or iframe component
<iframe src={embedUrl} width="100%" height="450" style={{ border: 'none' }} />