> ## 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.

# Paywall enforcement

> Run the standalone paywall app and compare its starter and final versions.

## What you will build

Two distinct free articles per device per day. 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 paywall
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 these changes, then run the complete implementation from the `final` branch.

**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 app's hostname in **Integration > Domains**. Put its matching Public Key and Private API Key in the private `paywall/.env` as `SHIELDLABS_PUBLIC_KEY` and `SHIELDLABS_API_KEY`. Resolve that hostname through `GET /api/v1/domains` with the Private API Key, or OAuth MCP `shieldlabs_list_domains`, and set its public UUID as `SHIELDLABS_DOMAIN_ID`. Serve this app through HTTPS on that registered hostname. The Private API Key stays on the server; a customer key does not automatically authorize localhost.

**2. 2. Identify the action in the browser**

The protected page loads the locally served JS SDK. In `public/article.js`, each article read takes a fresh Identification ID and sends it with the action:

```js theme={null}
const requestId = await identify();
const response = await fetch(`/api/articles/${encodeURIComponent(articleId)}/read`, {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ requestId }),
});
```

Only the Identification ID goes to the server; the browser does not supply the risk result.

**3. 3. Verify the identification on the server**

`server/shieldlabs.js` uses `@shieldlabs-ai/node` and the Private API Key to find that exact Identification ID in History. The action route passes it to `server/articles.js`, where `verifyIdentification(identificationId)` rejects missing, stale, replayed, automated or unusable checks before this scenario's rule is applied.

**4. 4. Apply the one free article rule**

This excerpt from [`server/articles.js`](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/paywall/server/articles.js) shows the decision's core:

```js theme={null}
return db.prepare('SELECT DISTINCT article_id FROM article_views WHERE device_id = ? AND created_at >= ?').all(deviceId, since).map((row) => row.article_id);
```

`public/article.js` identifies each article view. `server/articles.js` meters distinct article IDs per verified Device ID within 24 hours. Reopening an already counted article is different from opening a new one.

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

From the repository root, compare the two versions and start the final app:

```sh theme={null}
cd ..
git diff starter 1ce18350ce516183aea0bf1ea848fabf625f9cfe -- paywall
git switch --detach 1ce18350ce516183aea0bf1ea848fabf625f9cfe
cd paywall
npm ci --omit=dev
npm start
```

A fresh clone has the remote `origin/final` ref even before its local `final` branch exists. Open the completed app through the registered HTTPS hostname. The Node server listens on `127.0.0.1:3000` behind your reverse proxy.

## Follow the integration code

The completed source is in the [paywall application](https://github.com/ShieldLabs-ai/use-case-tutorials/tree/1ce18350ce516183aea0bf1ea848fabf625f9cfe/paywall). Read these files in order:

1. [Browser helper](https://github.com/ShieldLabs-ai/use-case-tutorials/blob/1ce18350ce516183aea0bf1ea848fabf625f9cfe/paywall/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/paywall/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/paywall/server/articles.js): applies this app's rule using the verified identification and stores its sample state.

The [finished application](https://github.com/ShieldLabs-ai/use-case-tutorials/tree/1ce18350ce516183aea0bf1ea848fabf625f9cfe/paywall) keeps its browser, server and SQLite state inside this folder. The tests use synthetic History responses; the normal server does not manufacture a successful identification.

## Try the completed application

1. Open the first two distinct sample articles. Both are readable.
2. Open a third distinct article from the same observed device. The app locks it behind the example paywall.
3. Reopen one of the previously read articles; that does not consume a third distinct view.

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**, inspect the /api/articles/{id}/read request and copy its `requestId`. Find the article-view Identification IDs in History and confirm the same Device ID. The local `article_views` table counts distinct article IDs, not browser cookies. Run `npm run check` and `npm test` from `paywall` to exercise failure cases locally without making more identifications.

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.