Developer Docs
Everything you need to integrate device fingerprinting into your application.
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
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
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.
Installation
The fastest way to get started is the CDN script tag: no build step, no package manager. It exposes the SDK as the LightningResearchSDK browser global.
Recommended: CDN script tag
<!-- Recommended: load the SDK via CDN, no build step -->
<script src="https://lrdefender.lightningresearch.ai/sdk/v1/lr.min.js"></script>
<script>
// sessionToken is minted by your server and sent to the browser
const lr = new LightningResearchSDK.LightningResearch({ sessionToken })
lr.identify().then((r) => console.log(r.deviceId))
</script>
Alternative: npm (bundler / TypeScript apps)
Using a bundler or TypeScript? Install the package via your preferred package manager.
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.
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
import { LightningResearch } from '@lightningresearch/sdk'
// Your backend should mint the session token (see Server-Side tab below)
// and pass it to the client via your own API route.
const { sessionToken } = await fetch('/your-backend/get-lr-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
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: class="text-accent">120,
maxUses: class="text-accent">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()
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.
/api/device-idSubmit 90+ browser signals and receive a device ID with confidence score, risk level, and match metadata.
/api/device/:idRetrieve device details including fingerprint history, visit count, and associated risk data.
/api/v1/bot/checkBot detection with behavioral biometrics, headless checks, and automation framework detection.
/api/v1/threat/assessThreat assessment for IPs: proxy, VPN, Tor, datacenter detection with risk scoring.
/api/analyticsAggregated analytics: device counts, browser distributions, screen resolutions, and behavioral data.
/api/security-analysisThreat intelligence: risk distributions, flagged devices, and detection breakdown.
/api/realtime-monitoringReal-time metrics: active sessions, request volume, and average response times.
/api/compliance/consentRecord 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.
Error Codes
All errors return a JSON body with error and message fields.
Webhooks
Receive HMAC-signed notifications when important events occur. Configure webhook URLs in your dashboard.
device.newdevice.risk_changedevice.suspicioussession.anomalybot.detectedapp.post('/webhooks/fingerprint', (req, res) => {
const signature = req.headers['x-signature']
const isValid = verifyHmac(signature, req.body, webhookSecret)
if (!isValid) return res.status(class="text-accent">401).end()
const { event, data } = req.body
switch (event) {
case 'device.suspicious':
alertSecurityTeam(data)
break
case 'device.new':
trackNewDevice(data)
break
}
res.status(class="text-accent">200).json({ received: true })
})
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
const lr = new LightningResearch({
sessionToken,
endpoint: 'https://api.lrdefender.lightningresearch.ai',
timeout: class="text-accent">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.