Skip to content
Volidator Docs

Installation

This page covers installing the SDK, configuring the client, and verifying the connection.

Install

Section titled “Install”
Terminal window
npm install @volidator/node

The package has no runtime dependencies. It uses Node.js built-in crypto for AES-256-GCM encryption and HMAC-SHA256 blind index generation.

Environment variables

Section titled “Environment variables”

Add the following to your .env file or secrets manager:

Terminal window
VOLIDATOR_API_KEY=         # API key from the Volidator dashboard
VOLIDATOR_ENCRYPTION_KEY=  # 32-character random string you generate

Generate an encryption key:

Terminal window
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Keep VOLIDATOR_ENCRYPTION_KEY secret and consistent across deployments. Changing it makes all previously encrypted logs unreadable.

Initialize the client

Section titled “Initialize the client”
import { VolidatorClient } from '@volidator/node';


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

Create one instance and export it. Do not create a new instance per request.

Constructor options

Section titled “Constructor options”
Name Type Required Default Description
apiKey string Yes Bearer token for the ingestion worker
encryptionKey string Yes AES-256-GCM encryption key
endpoint string No https://ingestion.volidator.com Ingestion worker URL
projectId string No Required only for generateEmbedToken()
clientSecret string No Required only for generateEmbedToken()
telemetry TelemetryConfig No { preset: 'standard' } IP, user-agent, and location collection settings
redactKeys string[] No [] Fields to redact before encryption
referenceKeys string[] No [] Fields to replace with [REF:id] before encryption (JIT Hydration)

Verify the connection

Section titled “Verify the connection”
const ok = await volidator.log({
  actor: 'setup-test',
  action: 'connection.verify',
  target: 'ingestion-worker',
});


console.log('Connected:', ok); // true = log accepted

If ok is false, check that VOLIDATOR_API_KEY matches an active project in the dashboard and that the ingestion worker is reachable.

Custom endpoint

Section titled “Custom endpoint”

If you are proxying ingestion requests through a custom gateway or domain (e.g. for private routing or compliance proxying), pass the endpoint option:

const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
  endpoint: 'https://logs-proxy.your-domain.com',
});
Section titled “Related”