Quickstart

This page covers installation, client initialization, and sending your first log. The entire integration takes under 5 minutes.

Install

Node.js

npm install @volidator/node

Python

pip install volidator-python

Initialize the client

Create one client instance per application and reuse it. Initializing per-request is wasteful.

The apiKey authenticates requests to the ingestion worker. The encryptionKey is the AES-256-GCM key you generate to encrypt log payloads client-side before they leave your server (Volidator never holds this key).

You must generate a secure 32-byte (64 hex characters) key. You can generate one using:

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())"

Initialize the client like so:

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"]
)

Store both values as environment secrets. Never commit them. Changing the encryption key later will make existing encrypted logs unreadable unless you use keyring rotation.

Send a log

Node.js

await volidator.log({
  actor: 'user_abc123',
  action: 'invoice.download',
  target: 'invoice_789',
  metadata: {
    invoiceNumber: 'INV-2024-001',
    amount: 4900,
  },
});

Python

volidator.log({
    "actor": "user_abc123",
    "action": "invoice.download",
    "target": "invoice_789",
    "metadata": {
        "invoiceNumber": "INV-2024-001",
        "amount": 4900,
    }
})

log() returns true if the log was accepted by the ingestion worker, false otherwise. It does not throw.

Add request context

Pass the HTTP request object directly. The SDK extracts IP, user-agent, and geolocation headers automatically.

Node.js

// In a Next.js route handler / Express route:
await volidator.log({
  actor: session.userId,
  action: 'settings.update',
  req: request,
});

Python

# In a FastAPI route / Django view / Flask route:
volidator.log({
    "actor": session_user_id,
    "action": "settings.update",
    "req": request,  # Supports Starlette/FastAPI Request, Django Request, Flask Request
})

Next steps

• Read Installation for the full constructor option table.
• Read Telemetry to control what context data is collected.
• Read PII Redaction if you need HIPAA or GDPR compliance out of the box.