Integration Guide
Learn how to integrate the Eyes SDK into your application. Add browser fingerprinting and fraud detection in under 5 minutes.
Quick Start
Get up and running in 2 minutes with our CDN-hosted SDK. No build tools required.
Get your API key
Sign up for a free account and copy your API key from the dashboard.
Create free accountAdd the script and analyze visitors
Add the SDK to your HTML and call analyze() to get a risk assessment.
1<!-- Add to your <head> or before </body> -->2<script src="https://cdn.theallseeingeyes.org/sdk/v1/eyes.min.js"></script>34<script>5 // Initialize Eyes6 const eyes = new Eyes({7 apiKey: 'eye_live_your_api_key_here'8 });910 // Analyze visitor on page load11 eyes.analyze().then(result => {12 console.log('Visitor ID:', result.visitorId);13 console.log('Risk Score:', result.riskScore);14 console.log('Risk Level:', result.risk?.level);1516 // Take action based on risk level17 if (result.risk?.level === 'critical') {18 showCaptcha();19 }20 }).catch(error => {21 console.error('Eyes error:', error);22 });23</script>
That's it!
Installation
Choose your preferred installation method. The SDK works with any JavaScript framework.
CDN (Recommended for quick start)
<!-- Primary CDN --><script src="https://cdn.theallseeingeyes.org/sdk/v1/eyes.min.js"></script><!-- Alternative: jsDelivr CDN --><script src="https://cdn.jsdelivr.net/npm/@allseeingeyes/sdk"></script>
Package Manager
npm install @allseeingeyes/sdk
TypeScript Support
@allseeingeyes/sdk package ships with full TypeScript definitions. No additional @types packages needed.Client Integration
Integrate Eyes into your frontend application using your preferred framework.
<!-- Add to your <head> or before </body> --><script src="https://cdn.theallseeingeyes.org/sdk/v1/eyes.min.js"></script><script>// Initialize Eyesconst eyes = new Eyes({apiKey: 'eye_live_your_api_key_here'});// Analyze visitor on page loadeyes.analyze().then(result => {console.log('Visitor ID:', result.visitorId);console.log('Risk Score:', result.riskScore);console.log('Risk Level:', result.risk?.level);// Take action based on risk levelif (result.risk?.level === 'critical') {showCaptcha();}}).catch(error => {console.error('Eyes error:', error);});</script>
Pro tip: Cache the visitor ID
visitorId in sessionStorage after the first call. You don't need to re-fingerprint the same visitor multiple times per session.Server Integration
Verify visitors server-side using your secret API key. Prevents client-side tampering.
Use your secret key server-side
eye_secret_* key in client-side code. It should only be used on your server for verification.import express from 'express';import fetch from 'node-fetch';const app = express();app.use(express.json());const EYES_SECRET_KEY = process.env.EYES_SECRET_KEY;const API_URL = 'https://api.theallseeingeyes.org';// Middleware to verify visitorasync function verifyVisitor(req, res, next) {const { visitorId, requestId } = req.body;if (!visitorId) {return res.status(400).json({ error: 'visitorId required' });}try {const response = await fetch(`${API_URL}/v1/verify`, {method: 'POST',headers: {'Authorization': `Bearer ${EYES_SECRET_KEY}`,'Content-Type': 'application/json',},body: JSON.stringify({ visitorId, requestId }),});const verification = await response.json();req.eyes = verification;next();} catch (error) {console.error('Verification failed:', error);// Fail open - don't block on verification errorsnext();}}app.post('/api/checkout', verifyVisitor, (req, res) => {const { risk } = req.eyes || {};if (risk?.level === 'critical') {return res.status(403).json({error: 'Transaction blocked for security reasons'});}if (risk?.level === 'high') {return res.status(428).json({requiresVerification: true});}// Process checkout...res.json({ success: true });});app.listen(3000);
API Reference
Complete reference for the Eyes API endpoints.
For interactive API documentation with a "Try it" feature, check out our OpenAPI reference:
View Interactive API Docsnew Eyes(options)ConstructorCreates a new Eyes client instance.
Options
apiKeyeye_live_ or eye_test_)endpointeyes.analyze(): Promise<AnalyzeResponse>MethodCollects browser signals and returns a fraud risk assessment.
Collected Signals
REST API Examples
# Analyze a visitor (client-side SDK does this automatically)curl -X POST https://api.theallseeingeyes.org/v1/analyze \-H "Content-Type: application/json" \-H "X-API-Key: eye_live_your_api_key_here" \-d '{"signals": {"userAgent": "Mozilla/5.0...","language": "en-US","platform": "MacIntel","screenResolution": "1920x1080","timezone": "America/New_York","canvas": "abc123...","webgl": "def456..."}}'
# Verify a visitor server-sidecurl -X POST https://api.theallseeingeyes.org/v1/verify \-H "Content-Type: application/json" \-H "Authorization: Bearer eye_secret_your_secret_key" \-d '{"visitorId": "fp_a1b2c3d4e5f6g7h8i9j0","requestId": "req_xyz123abc456"}'
Response Format
Understanding the API response structure and risk signals.
Low Risk Response
{"visitorId": "fp_a1b2c3d4e5f6g7h8i9j0","riskScore": 35,"risk": {"level": "low","signals": {"isBot": false,"isVPN": false,"isTor": false,"isProxy": false,"isDatacenter": false,"isHeadless": false,"hasInconsistentTimezone": false,"hasCanvasAnomaly": false}},"confidence": 0.95,"requestId": "req_xyz123abc456"}
High Risk Response
{"visitorId": "fp_suspicious123456","riskScore": 85,"risk": {"level": "critical","signals": {"isBot": true,"isVPN": true,"isTor": false,"isProxy": false,"isDatacenter": true,"isHeadless": true,"hasInconsistentTimezone": true,"hasCanvasAnomaly": false}},"confidence": 0.88,"requestId": "req_abc789xyz123"}
Response Fields
visitorIdstringUnique fingerprint hash. Stable across sessions.riskScorenumberRisk score from 0 (safe) to 100 (high risk).risk.levelstring"low" (0-25), "medium" (26-50), "high" (51-75), "critical" (76-100)risk.signalsobjectIndividual detection flags (bot, VPN, Tor, etc.)confidencenumberFingerprint confidence from 0 to 1.requestIdstringUnique ID for debugging and server verification.Risk Signals
isBotAutomation detected
isVPNVPN detected
isTorTor exit node
isProxyProxy server
isDatacenterDatacenter IP
isHeadlessHeadless browser
hasInconsistentTimezoneTZ/IP mismatch
hasCanvasAnomalyCanvas anomaly
Error Handling
Handle errors gracefully to ensure your app continues working.
Error Codes
Fail-Open Design
Best Practices
Tips for getting the most out of Eyes.
When to call analyze()
Call on page load for tracking, or just before critical actions (checkout, signup) for targeted protection.
Cache the visitorId
Store the visitorId in sessionStorage. Don't re-fingerprint the same visitor multiple times.
Protect your keys
Publishable key (eye_live_*) is safe client-side. Keep secret key (eye_secret_*) on server only.
Rate Limits
100 requests/minute per key. Implement caching and upgrade your plan for high traffic.
Monitor your dashboard
Watch for unusual patterns - sudden spikes in high-risk visitors may indicate an attack.
Verify server-side
For critical operations (payments, signups), always verify the visitor on your backend.
Ready to see everything?
Create a free account and start protecting your application in minutes.