Skip to content
Documentation

Developer Docs

Everything you need to integrate device fingerprinting into your application.

Overview

Getting Started

Lightning Research identifies unique devices using 42+ browser and hardware signals — GPU rendering, WebGL capabilities, audio context, canvas fingerprinting, 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 collects signals client-side 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

All API requests require an API key passed via the X-API-Key header. You can find your API key in the dashboard under Settings.

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

Keep your API key secret

Never expose your API key in client-side code. Use the SDK on the client and verify on your backend with the API key.

Quick Start

Quick Start

Get device fingerprinting running in under 5 minutes.

Client-Side — Initialize and Identify

app.ts
import { LightningResearch } from '@lightningresearch/sdk'

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

const result = await lr.identify()
console.log(result.deviceId)    // "d_8f3k..."
console.log(result.confidence)  // 0.995
console.log(result.riskScore)   // "low"

Server-Side — Verify the Fingerprint

server.ts
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 (or http://localhost:3000 for local development).

POST/api/device-id

Submit 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.

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.

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.new
device.risk_change
device.suspicious
session.anomaly
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

12 KB gzipped, no external deps

TypeScript First

Full type definitions included

Framework Agnostic

React, Vue, Angular, vanilla JS

Privacy Compliant

GDPR consent mode support

advanced-config.ts
const lr = new LightningResearch({
  apiKey: 'lr_live_...',
  endpoint: 'https://api.lrdefender.lightningresearch.ai',
  timeout: 5000,
  signals: {
    canvas: true,
    webgl: true,
    audio: true,
    fonts: true,
  },
  privacy: {
    respectDoNotTrack: true,
    consentRequired: false,
  },
})

Ready to integrate?

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

Try Demo