Documentation

Integration Guide

Learn how to integrate the Eyes SDK into your application. Add browser fingerprinting and fraud detection in under 5 minutes.

5KB
SDK Size
<50ms
Latency
99.9%
Uptime

Quick Start

Get up and running in 2 minutes with our CDN-hosted SDK. No build tools required.

1

Get your API key

Sign up for a free account and copy your API key from the dashboard.

Create free account
2

Add the script and analyze visitors

Add the SDK to your HTML and call analyze() to get a risk assessment.

index.html
1<!-- Add to your <head> or before </body> -->
2<script src="https://cdn.theallseeingeyes.org/sdk/v1/eyes.min.js"></script>
3
4<script>
5 // Initialize Eyes
6 const eyes = new Eyes({
7 apiKey: 'eye_live_your_api_key_here'
8 });
9
10 // Analyze visitor on page load
11 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);
15
16 // Take action based on risk level
17 if (result.risk?.level === 'critical') {
18 showCaptcha();
19 }
20 }).catch(error => {
21 console.error('Eyes error:', error);
22 });
23</script>

That's it!

You're now collecting browser fingerprints and getting risk scores for every visitor. Check your dashboard to see visitor analytics in real-time.

Installation

Choose your preferred installation method. The SDK works with any JavaScript framework.

CDN (Recommended for quick start)

๐ŸŒHTML
<!-- 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

Terminal
npm install @allseeingeyes/sdk

TypeScript Support

The @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.

index.html
<!-- Add to your <head> or before </body> -->
<script src="https://cdn.theallseeingeyes.org/sdk/v1/eyes.min.js"></script>
<script>
// Initialize Eyes
const eyes = new Eyes({
apiKey: 'eye_live_your_api_key_here'
});
// Analyze visitor on page load
eyes.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 level
if (result.risk?.level === 'critical') {
showCaptcha();
}
}).catch(error => {
console.error('Eyes error:', error);
});
</script>

Pro tip: Cache the visitor ID

Store the 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

Never expose your eye_secret_* key in client-side code. It should only be used on your server for verification.
server.js
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 visitor
async 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 errors
next();
}
}
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 Docs
new Eyes(options)Constructor

Creates a new Eyes client instance.

Options

apiKey
requiredYour API key (starts with eye_live_ or eye_test_)
endpoint
optionalCustom API endpoint (defaults to production)
eyes.analyze(): Promise<AnalyzeResponse>Method

Collects browser signals and returns a fraud risk assessment.

Collected Signals

๐ŸŽจCanvas
๐Ÿ–ผ๏ธWebGL
๐Ÿ”ŠAudio
๐ŸงญNavigator
๐Ÿ“บScreen
๐Ÿ•Timezone
๐Ÿ“กWebRTC
๐Ÿค–Bot signals

REST API Examples

Analyze endpoint
# 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 endpoint
# Verify a visitor server-side
curl -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

๐Ÿ“‹JSON
{
"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

๐Ÿ“‹JSON
{
"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

๐Ÿค–
isBot

Automation detected

๐Ÿ”’
isVPN

VPN detected

๐Ÿง…
isTor

Tor exit node

๐Ÿ”€
isProxy

Proxy server

๐Ÿข
isDatacenter

Datacenter IP

๐Ÿ‘ป
isHeadless

Headless browser

โฐ
hasInconsistentTimezone

TZ/IP mismatch

๐ŸŽจ
hasCanvasAnomaly

Canvas anomaly

Error Handling

Handle errors gracefully to ensure your app continues working.

Error Codes

Fail-Open Design

Always implement a fail-open strategy. If Eyes encounters an error, allow the user to proceed rather than blocking them. Use fraud detection to add friction (CAPTCHA, verification), not to deny access entirely.

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.