Referral fraud

What you will build

Same-device referrals earn no reward. This is an illustrative application policy, not a default rule that ShieldLabs applies to every customer.

Run the starting application

You need Node.js 22 or later. The starter runs without ShieldLabs keys; the final version needs a registered HTTPS hostname and matching keys. Clone the public tutorial repository, then start this standalone application:

git clone https://github.com/ShieldLabs-ai/use-case-tutorials.git
cd use-case-tutorials
git switch starter
cd referral-fraud
npm ci --omit=dev
cp .env.example .env
npm run dev

Open http://127.0.0.1:3000. The starter has no ShieldLabs dependency or identification check. Its own SQLite state is separate from every other tutorial.

Add the integration

Stop the starter server. Follow the changes below. The final branch contains the complete runnable implementation.

1. Prepare the keys and HTTPS hostname

The .env copied from starter contains no key entries yet. Add the two lines below with this domain’s real values:

SHIELDLABS_PUBLIC_KEY=your-public-key
SHIELDLABS_API_KEY=sec_your_private_api_key

Register the hostname for this app in Integration > Domains. Put its matching Public Key and Private API Key from Integration > API keys in your private referral-fraud/.env as SHIELDLABS_PUBLIC_KEY and SHIELDLABS_API_KEY. The Private API Key belongs on the server. Serve the Node process through HTTPS on the registered hostname; a customer key does not automatically authorize localhost.

2. Identify the action in the browser

The finished public/index.html loads the locally served SDK and public configuration. public/shieldlabs.js starts the check when the signup form receives focus and queues checks. In public/index.js, take the fresh request ID and send it with the action:

const requestId = await identification.take();
const data = await postJson('/api/signup', { email, referralCode, requestId });

The browser sends only the request ID. It does not send a Risk Score or the Private API Key.

3. Verify it on the server

server/shieldlabs.js reads History through @shieldlabs-ai/node using that exact request ID and the Private API Key. server/server.js passes the ID to server/accounts.js, where verifyIdentification(requestId) refuses missing, stale, reused, automated or unusable checks before the business rule runs.

4. Apply the referral-fraud decision

In server/accounts.js, the scenario uses the verified Device ID:

if (code && !referrer) {
  message = 'Account created. That referral code was not recognized.';
} else if (referrer && referrer.device_id === deviceId) {
  message = 'Account created. No referral reward: you referred yourself.';
} else if (referrer) {
  creditCents = REWARD_CENTS;
  creditAccount(referrer.email, REWARD_CENTS);
  message = 'Account created. You and your friend both earned $10 for the referral.';
}

The same Device ID for a referrer and a new account marks a self-referral. The account can be created, but the example does not award the referral credit.

5. Run the completed application

From the repository root, compare the files and switch to the version with the integration:

cd ..
git diff starter origin/final -- referral-fraud
git switch final
cd referral-fraud
npm ci --omit=dev
npm start

origin/final is available immediately after a fresh clone; your local final branch is created by git switch final. Open the completed app through your registered HTTPS hostname. Its server listens on 127.0.0.1:3000 behind your reverse proxy.

Follow the integration code

The completed source is in the referral-fraud application. Read these files in order:

Browser helper: loads the installed SDK, serializes checks and returns a request ID.
Server verification: reads real History, checks the matching ID, rereads delayed results and rejects unusable or replayed checks.
Scenario decision: applies this app’s device or account rule and stores its teaching state.

The finished application keeps its browser, server and SQLite state inside this folder. Follow the linked files above if you are adapting the idea to your own application.

Try the completed application

Create an invented referrer account and copy its demo referral code.
Sign out. On the same observed device, create another demo account using that code. The new account is created without referral credit.
Repeat from a separately observed device to see the simulated reward path. No real money is paid.

Use Reset demo DB with DEMO_ALLOW_RESET=1 to repeat the exercise. These controls are for a disposable demonstration, not production authorization.

Check your result

In DevTools Network, open the action’s /api/signup request and copy its requestId. Find that ID in History and compare the Device ID with the decision shown in the app. Compare the referrer and new account’s Device IDs in History. Credit is withheld only when the IDs match. Run npm run check and npm test from referral-fraud to exercise the local behavior without making another identification. For a real run, obtain fresh request IDs in the browser and confirm their Device IDs and signals in History. If identification returns HTTP 429, stop and check your account limits before retrying. A cookie change does not prove that the Device ID changed: compare the History rows.

Adapt it to your product

This example is a starting point, not a production-ready authorization system. Bind each action to an authenticated session where appropriate, authorize administration screens, persist state and atomically consume request IDs across all server instances. Review legitimate shared-device behavior before applying a device-based restriction. See Acting on results.

Overview

Runnable examples

Accounts and applications

Payments and rewards

Experience and traffic

Investigate

Accounts

Promotions and rewards

Payments and content

Traffic and experience

What you will build

Run the starting application

Add the integration

Follow the integration code

Try the completed application

Check your result

Adapt it to your product

​What you will build

​Run the starting application

​Add the integration

​Follow the integration code

​Try the completed application

​Check your result

​Adapt it to your product

What you will build

Run the starting application

Add the integration

Follow the integration code

Try the completed application

Check your result

Adapt it to your product