> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# New account fraud

> Run the standalone new-account-fraud app and compare its starter and final versions.

## What you will build

One trial per Device ID. 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](https://github.com/ShieldLabs-ai/use-case-tutorials), then start this standalone application:

```sh theme={null}
git clone https://github.com/ShieldLabs-ai/use-case-tutorials.git
cd use-case-tutorials
git switch starter
cd new-account-fraud
npm ci --omit=dev
cp .env.example .env
npm run dev
```

Open [http://127.0.0.1:3000](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.

> [!NOTE]
>
> The completed application uses browser SDK `1.1.0` and Node SDK `1.3.0`. Its browser helper reads `result.identificationId`; `requestId` is the tutorial application's own submitted field. Its server reads a domain-scoped identification card and requires available risk and signal states before applying the action policy. An unavailable state is not a clean score or a negative signal. See [History](https://docs.shieldlabs.ai/api/history.md) for the response contract.

## Add the integration

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

**1. 1. Prepare the keys and HTTPS hostname**

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

```dotenv theme={null}
SHIELDLABS_PUBLIC_KEY=your-public-key
SHIELDLABS_API_KEY=sec_your_private_api_key
SHIELDLABS_DOMAIN_ID=your-domain-uuid
```

Get the public domain UUID for this hostname using `GET /api/v1/domains` with the Private API Key, or OAuth MCP `shieldlabs_list_domains`. Copy its `id` into `SHIELDLABS_DOMAIN_ID`; do not substitute the hostname.

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 `new-account-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. 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 Identification ID and send it with the action:

```js theme={null}
const requestId = await identification.take();
const data = await postJson('/api/signup', { username, password, requestId });
```

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

**3. 3. Verify it on the server**

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

**4. 4. Apply the new-account-fraud decision**

In [`server/accounts.js`](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/new-account-fraud/server/accounts.js), the scenario uses the verified Device ID:

```js theme={null}
if (db.prepare('SELECT 1 FROM accounts WHERE device_id = ?').get(deviceId)) {
  return { success: false, message: 'Signup refused: you already have a trial account.' };
}
```

A new username does not create another trial when the verified Device ID already belongs to a trial account.

**5. 5. Run the completed application**

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

```sh theme={null}
cd ..
git diff starter 1ce18350ce516183aea0bf1ea848fabf625f9cfe -- new-account-fraud
git switch --detach 1ce18350ce516183aea0bf1ea848fabf625f9cfe
cd new-account-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 [new-account-fraud application](https://github.com/ShieldLabs-ai/use-case-tutorials/tree/1ce18350ce516183aea0bf1ea848fabf625f9cfe/new-account-fraud). Read these files in order:

1. [Browser helper](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/new-account-fraud/public/shieldlabs.js): loads the installed SDK, serializes checks and returns an Identification ID.
2. [Server verification](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/new-account-fraud/server/shieldlabs.js): reads real History, checks the matching ID, waits within a bounded budget for pending results and rejects unusable or replayed checks.
3. [Scenario decision](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/new-account-fraud/server/accounts.js): applies this app's device or account rule and stores its teaching state.

The [finished application](https://github.com/ShieldLabs-ai/use-case-tutorials/tree/1ce18350ce516183aea0bf1ea848fabf625f9cfe/new-account-fraud) 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

1. Sign up with one invented username. The app should start the sample 14-day trial.
2. Sign up with a different username on the same observed device. The app should refuse another trial.
3. Check each signup Identification ID in History. The two attempts should refer to the same Device ID; clearing cookies alone is not evidence of a different device.

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. Check that the first account is stored with its Identification ID and Device ID, while the second username has no trial. Run `npm run check` and `npm test` from `new-account-fraud` to exercise the local behavior without making another identification.

For a real run, obtain fresh Identification IDs in the browser and confirm their Device IDs and signals in History. If identification returns HTTP 429, stop and respect the returned retry guidance; the status alone does not establish exhausted plan volume. 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 Identification IDs across all server instances. Review legitimate shared-device behavior before applying a device-based restriction. See [Acting on results](https://docs.shieldlabs.ai/guides/acting-on-risk-score.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.