Documentation

Developer Docs

Everything you need to integrate device fingerprinting into your application.

Introduction

What is LRDefender?

LRDefender identifies devices visiting your website. It works like a digital fingerprint — collecting hardware and browser signals to create a unique ID for each device, without cookies.

How it works

1. Your website loads our SDK

2. SDK collects 90+ signals

3. API returns a Device ID

Who is this for?

Fraud Teams

Detect repeat offenders, bot attacks, and account takeover attempts.

Product Teams

Understand device landscapes, enforce paywalls, and prevent multi-accounting.

Engineers

Simple SDK, REST API, webhooks, and full TypeScript support.

What can you do with it?

Detect when the same device creates multiple accounts or abuses free trials
Block bots, scrapers, and headless browsers before they reach your application
Identify returning visitors even after they clear cookies or switch browsers
Score login risk by recognizing trusted vs. unknown devices

Overview

Getting Started

Lightning Research identifies unique devices using 90+ browser, hardware, and behavioral signals — GPU rendering, WebGL pipelines, canvas fingerprinting, audio context, lies detection, headless checks, behavioral biometrics, and more. Unlike cookie-based solutions, our identifiers persist across browsers, incognito sessions, and VPNs.

Use it for fraud prevention, account security, bot detection, and device analytics. The SDK v1.2.1 collects signals client-side — including optional behavioral biometrics — and sends them to our API, which returns a stable device ID with confidence score and risk assessment.

Setup

Installation

Install the SDK via your preferred package manager.

terminal

$ npm install @lightningresearch/sdk

Security

Authentication

Server-to-server API requests require an API key passed via the X-API-Key header. Keep it in your backend secret manager and never expose it to the browser.

authenticated-request.sh

curl -X POST https://api.lrdefender.lightningresearch.ai/api/device-id \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_server_side_api_key_here" \
  -d '{"userAgent":"...","screenWidth":1920}'

Keep your API key secret

Never expose your API key in client-side code. Issue a short-lived collector session from your backend and keep the API key server-side only. Browser integrations should use the web origin's `/api/collector/session` proxy, while server-side systems can call the backend route directly.

Quick Start

Get device fingerprinting running in under 5 minutes.

Client-Side — Use a short-lived collector session

app.ts

import { LightningResearch } from '@lightningresearch/sdk'

const { sessionToken } = await fetch('/api/collector/session', {
  method: 'POST',
}).then((res) => res.json())

const lr = new LightningResearch({
  sessionToken,
  endpoint: 'https://api.lrdefender.lightningresearch.ai',
})

// Enable behavioral biometrics (optional, improves accuracy)
lr.startBehavioralTracking()

// Collects 90+ signals + behavioral data automatically
const result = await lr.identify()
console.log(result.deviceId)    // "d_8f3k..."
console.log(result.confidence)  // 0.995
console.log(result.risk.level)  // "low"

// Bot detection (includes behavioral data if tracking active)
const bot = await lr.bot.detect()
console.log(bot.isBot, bot.botScore)

Server-Side — Mint the collector session and verify

server.ts

const collectorSession = await fetch(
  'https://api.lrdefender.lightningresearch.ai/api/collector/session',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.LR_API_KEY,
    },
    body: JSON.stringify({
      ttlSeconds: 120,
      maxUses: 1,
      origin: 'https://app.example.com',
    }),
  }
).then((res) => res.json())

const response = await fetch(
  'https://api.lrdefender.lightningresearch.ai/api/device-id',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.LR_API_KEY,
    },
    body: JSON.stringify({ fingerprint: clientFingerprint }),
  }
)

const { deviceId, confidence, risk } = await response.json()

Endpoints

API Reference

Base URL: https://api.lrdefender.lightningresearch.ai for server-side integrations. Browser flows should mint collector sessions through the web origin and then call the proxied /api/v1/* surface; local development uses http://localhost:3000 for the API and http://localhost:3001 for the web proxy.

POST/api/device-id

Submit 90+ browser signals and receive a device ID with confidence score, risk level, and match metadata.

GET/api/device/:id

Retrieve device details including fingerprint history, visit count, and associated risk data.

POST/api/v1/bot/check

Bot detection with behavioral biometrics, headless checks, and automation framework detection.

POST/api/v1/threat/assess

Threat assessment for IPs: proxy, VPN, Tor, datacenter detection with risk scoring.

GET/api/analytics

Aggregated analytics: device counts, browser distributions, screen resolutions, and behavioral data.

GET/api/security-analysis

Threat intelligence: risk distributions, flagged devices, and detection breakdown.

GET/api/realtime-monitoring

Real-time metrics: active sessions, request volume, and average response times.

POST/api/compliance/consent

Record user consent for privacy compliance tracking.

Rate Limits: Defaults are deployment-configurable (commonly 100 req/min per API key). Rate limit headers (X-RateLimit-Remaining) are included when enabled. Use the web proxy for browser-issued collector sessions and the backend API for server-to-server calls.

Errors

Error Codes

All errors return a JSON body with error and message fields.

Code

Description

400

Bad Request — Missing or invalid parameters. Check the request body format.

401

Unauthorized — Invalid or missing API key. Verify your X-API-Key header.

403

Forbidden — API key does not have permission for this resource.

404

Not Found — The requested device or resource does not exist.

429

Rate Limited — Too many requests. Back off and retry with exponential delay.

500

Internal Error — Something went wrong on our end. Contact support if persistent.

Events

Webhooks

Receive HMAC-signed notifications when important events occur. Configure webhook URLs in your dashboard.

device.newA new device was identified for the first time

device.risk_changeA device's risk level changed (e.g. low → high)

device.suspiciousSuspicious activity detected (bot, proxy, anomaly)

session.anomalyBehavioral anomaly detected in an active session

bot.detectedBot or automation framework detected via behavioral analysis

webhook-handler.ts

app.post('/webhooks/fingerprint', (req, res) => {
  const signature = req.headers['x-signature']
  const isValid = verifyHmac(signature, req.body, webhookSecret)

  if (!isValid) return res.status(401).end()

  const { event, data } = req.body

  switch (event) {
    case 'device.suspicious':
      alertSecurityTeam(data)
      break
    case 'device.new':
      trackNewDevice(data)
      break
  }

  res.status(200).json({ received: true })
})

Client Libraries

SDKs

Official SDKs for JavaScript, with full TypeScript support.

Zero Dependencies

Lightweight, no external deps

TypeScript First

Full type definitions included

90+ Signals

Full engine with 30+ collection modules

Framework Agnostic

React, Vue, Angular, vanilla JS

Behavioral Biometrics

Mouse, keyboard, scroll, touch tracking

Privacy Compliant

GDPR consent mode support

advanced-config.ts

const lr = new LightningResearch({
  sessionToken,
  endpoint: 'https://api.lrdefender.lightningresearch.ai',
  timeout: 10000,
  signals: {
    canvas: true,
    webgl: true,
    webglTasks: true,
    audio: true,
    fonts: true,
    gpuTiming: true,
    wasmTiming: true,
    webrtc: true,
    domRect: true,
    math: true,
    cssMedia: true,
    storage: true,
    adBlock: true,
  },
  privacy: {
    respectDoNotTrack: true,
    consentRequired: false,
  },
})

// Enable behavioral biometrics (opt-in)
lr.startBehavioralTracking()

const result = await lr.identify()
console.log(result.deviceId, result.confidence)

// Bot detection with behavioral data
const bot = await lr.bot.detect()
console.log(bot.isBot, bot.botScore)

Ready to integrate?

Try the live demo to see fingerprinting in action, then follow the quick start guide.

Try Demo