FraudSense Studio

FraudSense Studio is a no-code configuration dashboard at app.getfraudsense.com where you manage your entire fraud detection setup visually — without writing code after your initial SDK integration.

Studio pages

Logging in

Studio uses Clerk authentication. Sign in at app.getfraudsense.com/sign-in with Google, GitHub, or email and password. New accounts are linked to your workspace automatically after payment.

Roles & Permissions

Studio supports three role levels. Roles are enforced across all pages — viewers cannot make changes even if they navigate directly to a page.

Inviting a team member

Go to Team Members in the sidebar → click Invite member → enter their name, email, and role. They will receive a Clerk invitation email with a sign-up link. Once they complete sign-up, their role is active immediately.

Rule Builder

Rules override the default scoring engine using IF/THEN logic. When a rule fires, its actions execute immediately — for example, forcing a CRITICAL risk level regardless of the raw score.

Condition types

Action types

Testing a rule

Click ▶ Test rule on any rule card to open the rule tester. Select which signals are active, set a risk score using the slider, and click Run test. The result shows pass or fail with a per-condition breakdown explaining exactly why each condition matched or did not.

AI rule generation

Click the Claude AI assistant panel at the bottom of the Rule Builder page. Describe a fraud scenario in plain English — for example, "Block new SIM cards on rooted devices between 2am and 5am". Claude reads your active signals and generates a structured rule automatically. You can review it before applying.

Rule Versioning

Every time a rule is edited or toggled, FraudSense automatically saves a snapshot of the previous state. This gives you a full audit trail and the ability to roll back any change instantly.

How it works

• Up to 10 versions are stored per rule — oldest versions are pruned automatically
• Each version records the rule title, conditions, actions, enabled state, and timestamp
• Click the purple History button on any rule card to open the version drawer
• Only Admins can restore a previous version

Restoring a version

Open the History drawer → find the version you want → click ↩ Restore this version. Before restoring, Studio automatically saves the current state as a new version — so you can always undo a restore if needed.

Publishing Config

Changes you make in Studio — signal weights and score bands — do not affect the fraud API automatically. You need to publish them explicitly using the Publish to API button in the Signal Manager.

What gets published

• All enabled signal names and their current weights
• Score band thresholds (LOW/MEDIUM/HIGH/CRITICAL)

What does NOT need publishing

• Rules — these are evaluated automatically at score time
• Webhook endpoints — these fire based on live scores, no publish needed

Quick Start

Get from zero to a working risk score in under 10 minutes.

npm install fraudsense-sdk

npx expo install expo-battery expo-brightness expo-crypto expo-device \
  expo-location expo-network expo-screen-orientation \
  expo-secure-store expo-sensors

import FraudSense from 'fraudsense-sdk';

await FraudSense.init({
  apiKey:        'fs_live_xxxx',
  endpoint:      'https://api.getfraudsense.com',
  collectGPS:    true,
  trustedRegion: 'AE',  // reduces expat false positives
  debug:         false,
});

// At login, payment, or withdrawal
const report = await FraudSense.getReport();

// Use stableScore after 3+ reports (recommended)
const level = report.risk.isStable
  ? report.risk.stableLevel
  : report.risk.level;

if (level === 'CRITICAL') blockTransaction();
if (level === 'HIGH')     requireVerification();
if (level === 'MEDIUM')   requestOTP();
if (level === 'LOW')      allowTransaction();

// Plain English summary for your fraud team
console.log(report.risk.summary);

Authentication

FraudSense uses two authentication methods depending on the caller.

API Key — SDK and server-to-server calls

Pass your API key in the x-api-key header for all risk scoring and event endpoints.

x-api-key: fs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

JWT Token — dashboard and management

Use a Bearer token in the Authorization header for account management endpoints.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Get a JWT token

curl -X POST https://api.getfraudsense.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"yourpassword"}'

const res = await fetch('https://api.getfraudsense.com/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'you@company.com', password: 'yourpassword' }),
});
const { token } = await res.json();

SDK Installation

Requirements

Install via npm

npm install fraudsense-sdk

Install peer dependencies

npx expo install expo-battery expo-brightness expo-crypto expo-device \
  expo-location expo-network expo-screen-orientation \
  expo-secure-store expo-sensors

Add permissions (iOS) — app.json

{
  "expo": {
    "plugins": [
      ["expo-location", {
        "locationWhenInUsePermission": "Used to verify transaction safety."
      }]
    ]
  }
}

Initialization

Call FraudSense.init() once at app startup — ideally on the splash screen before navigating to login.

import FraudSense from 'fraudsense-sdk';

await FraudSense.init({
  apiKey:        'fs_live_xxxx',                      // Required
  endpoint:      'https://api.getfraudsense.com',       // Required
  collectGPS:    true,                                 // Optional — default false
  trustedRegion: 'AE',                                 // Optional — ISO country code
  autoFlush:     true,                                 // Optional — default true
  flushInterval: 30000,                               // Optional — ms, default 30s
  debug:         false,                               // Optional — console logs
});

Configuration options

Behavior Hooks

Wire up these hooks in your components to collect behavioral signals. The more hooks you add, the more accurate the interactionScore becomes.

Tap recording

import BehaviorCollector from 'fraudsense-sdk/collectors/BehaviorCollector';

<TouchableOpacity
  onPress={(e) => {
    BehaviorCollector.recordTap(e.nativeEvent.locationX, e.nativeEvent.locationY);
    handleAction();
  }}
/>

Text change / paste detection

Paste detection works automatically via text length jump analysis — no onPaste prop needed.

<TextInput
  onChangeText={(text) => {
    BehaviorCollector.recordTextChange('email', text); // auto-detects paste
    setEmail(text);
  }}
/>

<TextInput
  onChangeText={(text) => {
    BehaviorCollector.recordTextChange('password', text);
    setPassword(text);
  }}
/>

Scroll recording

<ScrollView
  onScroll={(e) => BehaviorCollector.recordScroll(e.nativeEvent.contentOffset.y)}
  scrollEventThrottle={16}
>

Screen transition recording

useEffect(() => {
  BehaviorCollector.recordScreenTransition('PaymentScreen');
}, []);

SDK Methods

getReport()

Returns a full risk report for the current session. Use risk.stableScore and risk.stableLevel after 3+ reports for more accurate scoring.

const report = await FraudSense.getReport();

console.log(report.risk.stableScore);   // 0–100, averaged over last 3
console.log(report.risk.stableLevel);   // LOW / MEDIUM / HIGH / CRITICAL
console.log(report.risk.isStable);      // true after 3+ reports
console.log(report.risk.summary);       // plain English verdict
console.log(report.risk.triggered);     // array of fired signals with reasons
console.log(report.risk.patternsDetected); // number of combined patterns fired

getRiskScore()

Returns just the score and level. Lighter than getReport() if you only need the number.

const { score, level, triggered } = await FraudSense.getRiskScore();

getDeviceId()

Returns the stable SHA-256 device fingerprint. Persists via secure storage across sessions.

const deviceId = FraudSense.getDeviceId();
// Returns: "fs_a3f9b2c1d4e5..."

Other methods

Event Hooks

Subscribe to real-time events from the SDK using FraudSense.on(). Returns an unsubscribe function.

// Fires when SDK is initialized
FraudSense.on('ready', ({ deviceId, version }) => {
  console.log('SDK ready', deviceId);
});

// Fires after every getReport() call
FraudSense.on('report', (report) => {
  setRiskBadge(report.risk.stableLevel);
});

// Fires after every flush attempt
FraudSense.on('flush', ({ success, response }) => {
  if (!success) console.warn('Flush failed');
});

// Unsubscribe when component unmounts
const unsub = FraudSense.on('report', handler);
return () => unsub();

Auth Endpoints

Register

{
  "email":       "you@company.com",
  "password":    "SecurePass1!",
  "companyName": "Acme Bank"
}

{
  "token":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "apiKey": "fs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "client": {
    "id":          "uuid...",
    "email":       "you@company.com",
    "companyName": "Acme Bank",
    "plan":        "free"
  }
}

Events Endpoint

The SDK automatically posts to this endpoint on every flush. You can also call it directly for server-side integrations.

Request body

{
  "deviceId":    "fs_a3f9b2c1...",
  "sessionId":   "1744123456789",
  "deviceProfile": {
    "model":      "iPhone 17 Pro Max",
    "os":         "iOS",
    "timezone":   "Asia/Dubai",
    "locale":     "en-US",
    "isEmulator": false,
    "isRooted":   false
  },
  "events": [{
    "type":             "RISK_REPORT",
    "riskScore":        17,
    "riskLevel":        "LOW",
    "triggeredSignals": [],
    "fingerprint":      "fs_xyz...",
    "sdkVersion":       "1.2.0",
    "timestamp":        1744123456789
  }]
}

Device History

curl https://api.getfraudsense.com/v1/risk/history/fs_abc123 \
  -H "x-api-key: fs_live_xxxx"

API Keys

Dashboard

Risk Signal Catalogue

FraudSense v1.2.0 evaluates 44 signals per session across 8 categories. Each signal includes a confidence rating and plain English reason returned in the report.

Device signals (9)

Security signals (3)

Network signals (5)

Behavior signals (12)

Sensor signals (5)

Location signals (3)

Battery signals (3)

Combined Pattern Detection

Beyond individual signals, FraudSense detects 4 combined attack patterns. Patterns fire when multiple correlated signals appear together — they carry extra weight because combinations are far more reliable than single signals.

Risk Labels

High-level labels explain why a device scored HIGH — more actionable than a raw score alone. Returned in risk.byCategory and the risk.summary field.

Response Format

Risk levels

Risk object schema (v1.2.0)

Triggered signal object

IP Intelligence

Collected automatically via ipapi.co on every session. No extra configuration needed.

Device History

Every device that calls the API gets a persistent history record. Accessible via /v1/risk/history/:deviceId.

Status Codes

Changelog

SDK v1.2.0 — April 2026

• Signal count expanded from 18 to 44 signals across 8 categories
• Added SecurityCollector — emulator detection with confidence score, root/jailbreak heuristics, proxy detection
• Added 4 combined pattern detectors — automation, location hiding, credential stuffing, device farm
• Added confidence labels (HIGH/MEDIUM/LOW) and plain English reasons per signal
• Added stableScore — averages last 3 reports to eliminate first-load spikes
• Added trustedRegion config — reduces expat false positives for UAE and MENA markets
• Added summary field — plain English verdict for fraud teams
• Added byCategory — signals grouped by category for easier client integration
• Added paste detection via text length jump analysis (no onPaste prop required)
• Added device integrity scoring — model vs OS cross-validation
• Added locale vs timezone mismatch signal
• Added region vs IP country mismatch signal
• Improved VPN detection — confidence score 0–1 instead of boolean, cross-checks carrier country vs IP country
• Improved NetworkCollector — live IP intelligence via ipapi.co (country, city, org, datacenter flag)
• Fixed battery level comparison (was checking 0–1 float, now correctly checks 0–100 integer)
• Fixed all collector export issues — added collect() method to SensorCollector, BatteryCollector, LocationCollector
• Fixed locale/timezone collection via getLocales()/getCalendars() for newer Expo versions

SDK v1.1.0 — April 2026

• Initial public release on npm as fraudsense-sdk
• 6 collectors: Device, Sensor, Location, Battery, Network, Behavior
• 18 signals in RiskEngine
• SHA-256 device fingerprinting via expo-secure-store
• Singleton pattern throughout SDK

API v1.0.0 — March 2026

• Initial launch at api.getfraudsense.com
• JWT authentication, email verification, API key management
• Free tier — 1,000 calls/month
• Admin panel with suspend/activate/email/usage controls
• AI chatbot (Claude Haiku) for developer support
• /demo interactive fraud scenarios
• Railway deployment with PostgreSQL and Prisma

Support

Contact

Email: support@getfraudsense.com

GitHub Issues: github.com/getfraudsense/fraudsense-api

Before reaching out

• Check the Status Codes section for common errors
• Verify your API key is active in the developer portal
• Make sure deviceId and sessionId are included in every request
• For SDK issues, enable debug: true and check console logs
• Use the AI chatbot on the portal for instant answers