Installation

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

Install

Node.js

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.

Python

pip install volidator-python

The package has a single core runtime dependency on the cryptography library for hardware-accelerated AES-256-GCM encryption. It uses standard library urllib for zero-dependency HTTP networking (with support for httpx if present).

Environment variables

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

VOLIDATOR_API_KEY=         # API key from the Volidator dashboard
VOLIDATOR_ENCRYPTION_KEY=  # 32-character random string you generate (64 hex chars prefixed with vol-dek-)

Generate an encryption key:

Node.js

node -e "const b=require('crypto').randomBytes(32);console.log('vol-dek-'+b.toString('hex'))"

Python

python -c "import os; print('vol-dek-' + os.urandom(32).hex())"

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

Initialize the client

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

Node.js

import { VolidatorClient } from '@volidator/node';

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

Python

import os
from volidator import VolidatorClient

volidator = VolidatorClient(
    api_key=os.environ["VOLIDATOR_API_KEY"],
    encryption_key=os.environ["VOLIDATOR_ENCRYPTION_KEY"]
)

Constructor options

The Python SDK parameters map exactly to Node.js options using idiomatic snake_case:

Node.js Name	Python Name	Type	Required	Default	Description
apiKey	api_key	string	Yes		Bearer token for the ingestion worker
encryptionKey	encryption_key	string	Yes		AES-256-GCM encryption key
keyring	keyring	object	No		Map of historic key IDs to key strings for rotation
activeEncryptionKeyId	active_encryption_key_id	string	No		Active write key ID when using a keyring
endpoint	endpoint	string	No	https://ingestion.volidator.com	Ingestion worker URL
projectId	project_id	string	No		Required only for generateEmbedToken()
clientSecret	client_secret	string	No		Required only for generateEmbedToken()
telemetry	telemetry	dict	No	{'preset': 'standard'}	IP, user-agent, and location settings
redactKeys	redact_keys	list	No	[]	Fields to redact before encryption
referenceKeys	reference_keys	list	No	[]	Fields to replace with [REF:id] (JIT Hydration)
maxMetadataSize	max_metadata_size	number	No	10240 (10KB)	Max size in bytes for metadata
maxRetries	max_retries	number	No	3	Maximum retry attempts for transient errors
onDeliveryFailure	on_delivery_failure	function	No		Callback fired when an event permanently fails

Verify the connection

Node.js

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

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

Python

ok = volidator.log({
    "actor": "setup-test",
    "action": "connection.verify",
    "target": "ingestion-worker",
})

print("Connected:", ok)  # True = log accepted

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

Custom endpoint

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

Node.js

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

Python

volidator = VolidatorClient(
    api_key=os.environ["VOLIDATOR_API_KEY"],
    encryption_key=os.environ["VOLIDATOR_ENCRYPTION_KEY"],
    endpoint="https://logs-proxy.your-domain.com"
)

Related

• Quickstart — minimal working example
• Telemetry — controlling what context data is collected