Fingerprint

View saved version →

---
name: fingerprint-angular
description: Integrate Fingerprint device identification into an Angular app — initialize the agent and get the visitor's visitor_id and event_id.
---

# Fingerprint — Angular

Integrate Fingerprint into an Angular app to identify visitors: register the provider once at
startup, then ask it for the visitor's `visitor_id` and a single-use `event_id` wherever you need
it (on load, or on an action like login or checkout).

> Docs: https://docs.fingerprint.com/docs/angular · JS Agent v4: https://docs.fingerprint.com/reference/js-agent-v4

## Package
`@fingerprint/angular` — install the latest version.

## Env var
- `FINGERPRINT_PUBLIC_API_KEY` — the public key, safe to ship to the browser.

> Angular has no `.env` at runtime — config is baked in at build time. Put the public key and
> region in `src/environments/environment.ts` (and `environment.prod.ts` for production, swapped in
> via `fileReplacements`) and read them from there. Never put the secret key in `environment.ts` —
> it ships to the browser.

## Steps

1. **Install** `@fingerprint/angular`.

2. **Initialize once at the app root.** Register `provideFingerprint`, passing the public key and
   region (`us` | `eu` | `ap`, matching the workspace) via `startOptions`. For a standalone app
   this goes in `src/app/app.config.ts`. See `snippets/app.config.ts`.

3. **Get the identification where you need it.** Inject `FingerprintService` and call
   `getVisitorData()` on the action you care about; it returns `{ visitor_id, event_id, ... }`. See
   `snippets/login.component.ts`.

4. **Verify it works.** Disable your ad blocker, run the dev server, trigger the call, and confirm
   a `visitor_id` is logged in the browser console (or that the event appears on the dashboard
   Events page).

## Notes
- Region must match the workspace (`us` | `eu` | `ap`).
- Register `provideFingerprint` once at the app root; don't re-provide it per component.
- `getVisitorData()` is async — await it inside the action handler and handle errors so a failed
  identify doesn't break the flow.
- **Production:** protect the agent from ad blockers with a custom subdomain or proxy —
  https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers.
- Don't use legacy `@fingerprintjs/fingerprintjs-pro`, `FingerprintJS.load()`, or `scriptUrlPattern`.

Referenced files: 3

View saved version →

---
name: fingerprint-get-started
description: Guide the user through the full Fingerprint Get Started flow — detect the project's tech stack, install frontend identification, add the server-side API verification step, then walk the remaining protection steps, applying the matching skill for each. Use when the user wants to add Fingerprint to an app, get started with Fingerprint, or set up device identification and fraud protection end to end.
---

# Fingerprint — Get Started

Walk the user through the complete Fingerprint **Get Started** flow (the same checklist as the
dashboard), from first install to production-grade protection. Detect what's already done, then
apply or guide the matching skill for each remaining step. Do the steps in order; don't skip ahead
unless the user asks.

This skill is an **orchestrator** — its job is to detect the stack and delegate to the per-stack
and feature skills below. The actual SDK setup lives in those skills. In Claude Code, invoke a
skill with the Skill tool; in other agents, load and follow the named skill.

## How to run
1. **Audit the project first.** Grep for existing Fingerprint usage so you don't redo finished
   work: look for `@fingerprint/`, `fingerprint-server-sdk`, `FingerprintProvider`,
   `useVisitorData`, `getEvent`, `FINGERPRINT_*` env var names, `tag` / `linkedId`. Build a quick
   status of which steps below are done.
2. **Report the checklist** with each step marked done / not done.
3. **Walk the not-done steps in order.** For each, explain what it does, then apply the matching
   skill and follow it. Steps that are dashboard-only (rules, request filtering, ad-blocker config,
   team invites) can't be done from code — give the user the exact dashboard actions and offer to
   make any companion code change.
4. **After each step, tell the user how to verify it** (the dashboard Get Started page checks the
   same conditions — e.g. a received event, a Server API call, a tagged event).

## Detect the stack (before steps 1–2)
Read the project's manifests (don't guess from directory names):
- **Node**: `package.json` `dependencies` + `devDependencies`.
- **Python**: `requirements.txt`, `pyproject.toml`.
- **No manifest at all**: an `index.html` is a static site — still a supported frontend, with no
  build step and no env vars (the public key goes in the agent's CDN import URL).
- Check up to ~2 levels deep for monorepos (`apps/`, `packages/`, `pnpm-workspace.yaml`); a repo
  can have a separate frontend and backend.

Map detected frameworks to skills:

| Detected | Skill | Role |
| --- | --- | --- |
| `next` | `fingerprint-nextjs` | fullstack (covers both halves) |
| `react`, `react-native` | `fingerprint-react` | frontend |
| `vue`, `nuxt` | `fingerprint-vue` | frontend |
| `@angular/core` | `fingerprint-angular` | frontend |
| `svelte` (incl. SvelteKit) | `fingerprint-svelte` | frontend |
| `solid-js`, `lit`, `alpinejs`, `htmx.org`, `jquery` | `fingerprint-javascript` | frontend |
| `express`, `fastify`, `koa`, `@nestjs/core`, `@hapi/hapi` | `fingerprint-node` | backend |
| `fastapi`, `django`, `flask` | `fingerprint-python` | backend |
| *(no dependency matched above)* an `index.html` entry — plain HTML/JS, or a Vite/Webpack vanilla template | `fingerprint-javascript` | frontend |

- If you detect **Next.js**, `fingerprint-nextjs` covers both the install and server steps.
- Otherwise pick **one frontend** skill for step 1 and **one backend** skill for step 2.
- Match on dependencies first. The last row is a fallback: only use it once you've confirmed none
  of the packages above are present. When several match (jQuery inside a React app), the framework
  SDK wins — it wraps the same agent with framework-native APIs.
- A frontend with no framework SDK still has a curated skill — use `fingerprint-javascript` rather
  than the docs fallback.
- If nothing matches a curated skill, fall back to the docs (start at
  `https://docs.fingerprint.com/llms.txt`).

## The checklist

### Quick start
1. **Install Fingerprint (frontend)** — add visitor identification to the client and capture the
   first event.
   → Apply the matching frontend skill: `fingerprint-react` / `fingerprint-vue` /
   `fingerprint-angular` / `fingerprint-svelte` / `fingerprint-javascript` (no framework SDK), or
   `fingerprint-nextjs` (which also covers step 2).
   *Done when the client calls `getData()` and an event is received.*
2. **Access detailed insights (backend / Server API)** — verify the event server-side and read
   Smart Signals.
   → Apply the matching backend skill: `fingerprint-node` / `fingerprint-python` for the
   verification flow, then `fingerprint-smart-signals` to act on the full signal set.
   *Done when the server calls `getEvent` and reads signals.*

   > **Strongly recommended for security-sensitive actions** (login, signup, checkout): the client
   > only identifies — a real trust decision needs the server to verify the event. This is the
   > recommended next step, not a hard requirement (Next.js does both in one skill).

3. **Protect against ad blockers** — first-party custom subdomain or proxy integration.
   → Apply `fingerprint-proxy-integration`. *Done when the agent loads from your own domain.*

### Beyond the basics
4. **Build your first rule** — no-code automatic protection via the Rules Engine.
   → Apply `fingerprint-rules-engine` (dashboard setup + optional code to honor outcomes).
5. **Tag an event with your data** — attach user/account/order IDs to events.
   → Apply `fingerprint-tagging`. *Done when a tagged event is received.*
6. **Protect your public API key** — request filtering / allowed origins.
   → Apply `fingerprint-request-filtering` (dashboard setup; enumerate the app's real origins).
7. **Invite your team members** — dashboard-only. Point the user to the dashboard team settings;
   there's nothing to change in code. Pricing isn't seat-based, so they can invite freely.
8. **Upgrade to Pro Plus** — dashboard-only. New accounts trial **Fingerprint Pro Plus**; once the
   trial ends, the account is downgraded to the **Free** plan. If they want to keep Pro Plus
   features, point them to the dashboard billing/plan settings to upgrade before the trial ends.

## How to verify the install (after steps 1–2)
- **Preview the app**, trigger the action you wired up (e.g. load the page, submit a login/signup),
  and check that a new event appears on the **Events page in the Fingerprint dashboard**
  (https://dashboard.fingerprint.com). An event with an `event_id` confirms identification works
  end to end.
- If no event shows up, the usual cause is an **ad blocker** eating the request during testing —
  disable it and retry. For production accuracy, do step 3.

## Rules
- Step 1 is complete once identification works (an event is received). The later steps are
  recommendations, not mandatory gates — for security-sensitive actions, strongly recommend step 2
  (server-side verification), but don't block step 1 on it.
- Never read/print `.env`; reference env vars by name. Never put the secret key in client code.
- Match the existing code style; make minimal, focused edits. Tell the user which packages to
  install rather than pinning versions yourself.
- Region must match the workspace region (`us` | `eu` | `ap`) on every side.
- If the user only wants one step, jump straight to that step's skill.

Referenced files: 1

View saved version →

---
name: fingerprint-javascript
description: Integrate Fingerprint device identification into a vanilla JavaScript or plain HTML app with the JS Agent (@fingerprint/agent, npm or CDN) — initialize the agent and get the visitor's visitor_id and event_id. Use when there's no framework SDK — Vite, Webpack, a plain script tag, Solid, Lit, Alpine, htmx, or jQuery.
---

# Fingerprint — JavaScript

Integrate Fingerprint into a vanilla JavaScript app with the JS Agent directly: initialize the
agent once at startup, then ask it for the visitor's `visitor_id` and a single-use `event_id`
wherever you need it (on load, or on an action like login or checkout).

Use this skill when there is no framework SDK to use. For React (or Preact), Vue, Angular, Svelte,
or Next.js, use `fingerprint-react` / `fingerprint-vue` / `fingerprint-angular` /
`fingerprint-svelte` / `fingerprint-nextjs` instead — they wrap this same agent with
framework-native APIs and built-in caching.

> Docs: https://docs.fingerprint.com/docs/javascript-quickstart · JS Agent v4: https://docs.fingerprint.com/reference/js-agent-v4

## Package
`@fingerprint/agent` — install the latest version. The npm package is a **loader**: it downloads
the current agent from the CDN at runtime rather than bundling the fingerprinting logic, so don't
vendor or self-host the agent bundle. With no build step, skip the install and import from the CDN
instead — see `snippets/cdn.html`.

> Fingerprint's CDN serves the agent at `/v4/<PUBLIC_API_KEY>`. A custom subdomain or proxy serves
> it one level down, at `/web/v4/<PUBLIC_API_KEY>` — `/web/` is the path prefix the proxy uses to
> separate agent downloads from identification requests on your own host, so the two URLs are
> meant to differ. See `fingerprint-proxy-integration`.

## Env var
- `FINGERPRINT_PUBLIC_API_KEY` — the public key, safe to ship to the browser.

> Bundlers only expose prefixed vars to client code — map the key to the bundler's convention:
> - Vite: `VITE_FINGERPRINT_PUBLIC_API_KEY` → `import.meta.env.VITE_...`
> - Webpack: inject with `DefinePlugin` / `EnvironmentPlugin` → `process.env.FINGERPRINT_...`
> - No bundler: there is no env-var mechanism — the key goes in the CDN import URL and ships in the
>   HTML. That's fine for a public key; restrict it with `fingerprint-request-filtering`.
> Never expose `FINGERPRINT_SECRET_API_KEY` to the frontend.

## Steps

1. **Install** `@fingerprint/agent` — or, with no build step, skip the install and import from the
   CDN (`snippets/cdn.html`) instead of adding a `package.json` the project doesn't have.

2. **Initialize once at app startup.** Call `Fingerprint.start()` with the public key and region
   (`us` | `eu` | `ap`, matching the workspace), and export the instance so the rest of the app
   reuses it. `start()` returns the agent synchronously — the agent script downloads in the
   background and `get()` waits for it. Client-side only. See `snippets/fingerprint.js`.

   Prefer `import * as Fingerprint from '@fingerprint/agent'` over a default import — the namespace
   import tree-shakes better.

3. **Get the identification where you need it.** Call `fp.get()`, which resolves to
   `{ visitor_id, event_id, ... }`. Each call is a billable identification event, so call it on the
   action you care about rather than on every page view. It accepts `{ tag, linkedId, timeout }`.
   See `snippets/identify.js`.

4. **Verify it works.** Disable your ad blocker, run the dev server, trigger the call, and confirm
   a `visitor_id` is logged in the browser console (or that the event appears on the dashboard
   Events page).

## Notes
- Region must match the workspace (`us` | `eu` | `ap`).
- Call `start()` once for the whole app; don't re-start per page or per action. In a SPA, keep the
  agent at module level so it survives client-side route changes — the deprecated
  `fingerprintjs-pro-spa` wrapper is not needed.
- Don't block the UI on identification. `get()` rejects when the agent is blocked, offline, or
  times out — catch it, use `isFingerprintError(error)` and `error.code` to log the cause, and let
  the flow continue.
- Caching is **off** by default. If you enable the `cache` option, a cache hit returns the *same*
  `event_id` (with `cache_hit: true`), which fails server-side freshness and one-time-use checks —
  keep `get()` uncached for security-relevant actions.
- Don't run the agent in a sandboxed iframe; it isn't supported.
- **Production:** protect the agent from ad blockers with a custom subdomain or proxy —
  https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers.
- Don't use legacy `@fingerprintjs/fingerprintjs-pro`, `FingerprintJS.load()`, or `scriptUrlPattern`.

Referenced files: 4

View saved version →

---
name: fingerprint-nextjs
description: Add Fingerprint to a fullstack Next.js (App Router) app — identify visitors in the browser with the React SDK and verify the event_id server-side with the node SDK in a Route Handler or Server Action.
---

# Fingerprint — Next.js

Integrate Fingerprint into a Next.js (App Router) app. Next.js does both halves in one codebase:
the **client identifies** the visitor (producing a single-use `event_id`) and the **server**
fetches that event from the Server API to read the verified identification and Smart Signals. The
browser never holds the secret key and never makes trust decisions — the server does, using the
checks below.

> Docs: React SDK https://docs.fingerprint.com/docs/react · Node Server SDK https://docs.fingerprint.com/reference/node-server-sdk · event schema: OpenAPI (https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi) or the Fingerprint MCP event-schema resource.

## Packages
- `@fingerprint/react` — browser identification (client components). Install the latest version.
- `@fingerprint/node-sdk` — Server API verification (Route Handlers / Server Actions). Install the latest version.

## Env vars
Next.js only exposes env vars prefixed with `NEXT_PUBLIC_` to the browser bundle. Everything else
stays server-only.

- `NEXT_PUBLIC_FINGERPRINT_PUBLIC_API_KEY` — public key, shipped to the browser (safe).
- `NEXT_PUBLIC_FINGERPRINT_REGION` — workspace region for the client (`us` | `eu` | `ap`), shipped
  to the browser.
- `FINGERPRINT_SECRET_API_KEY` — secret key. **Server-only**; the missing `NEXT_PUBLIC_` prefix
  keeps it out of the client bundle. Never reference it from a client component.
- `FINGERPRINT_REGION` — workspace region for the server (`us` | `eu` | `ap`).

> Read public values via `process.env.NEXT_PUBLIC_*`; they are inlined into client code. Read the
> secret only inside server code (Route Handlers, Server Actions, server components). If you ever
> see `FINGERPRINT_SECRET_API_KEY` referenced from a `'use client'` file, that's a leak.

## Steps

### Client — identify
1. **Install** `@fingerprint/react`.

2. **Wrap the app in `FingerprintProvider`.** The provider is a client component, so put it in a
   small `'use client'` wrapper and render that wrapper inside `app/layout.tsx` around `{children}`.
   Pass the public key and region from the `NEXT_PUBLIC_` vars. See `snippets/provider.tsx` and
   `snippets/layout.tsx`.

3. **Identify on sensitive actions, not on every render.** In a client component, use
   `useVisitorData({ immediate: false })` and call `getData()` at the moment of a security-relevant
   action (login, signup, checkout, password reset). See `snippets/identify-on-action.tsx`.

4. **Send the `event_id` to the server** with the action request. `getData()` returns
   `{ visitor_id, event_id }`; send the **`event_id`** (single-use, server-verifiable). Do not trust
   the client `visitor_id` — the server re-derives it from the Server API.

### Server — verify
5. **Install** `@fingerprint/node-sdk`.

6. **Create one client** with the secret key and region (`Region.Global` | `Region.EU` |
   `Region.AP`, mapped from `FINGERPRINT_REGION`). Next.js loads `.env.local` automatically, so no
   `dotenv` is needed. See `snippets/fingerprint-server.ts`.

7. **Verify the `event_id`** before running the sensitive handler: call `client.getEvent(eventId)`
   and apply the checks below. Use it from either a Route Handler (`app/api/.../route.ts`) or a
   Server Action (`'use server'`). See `snippets/route-handler.ts` and `snippets/server-action.ts`.

## Verification checks (do all of them)
- **Found:** `event.identification.visitor_id` exists.
- **Replay / freshness:** reject if `event.replayed === true`, or if `event.timestamp` is older than
  your window (e.g. 2 minutes) — prevents reuse of an old `event_id`.
- **Confidence:** require `event.identification.confidence.score >= 0.9` for the action.
- **Smart signals** (fail-closed for high-risk actions): `event.bot !== "not_detected"`,
  `event.vpn`, `event.proxy`, `event.tampering`.
- **Identity match:** bind `visitor_id` ↔ user on first trusted use; re-check on later actions.

## v4 event shape (flat — per the Server API event schema)
`getEvent` returns the event object directly:
- `event.identification.visitor_id` — the trusted visitor id
- `event.identification.confidence.score` — 0..1 (probability of a false-positive identification)
- `event.timestamp` — Unix ms of the event
- `event.replayed` — `true` if the payload was replayed
- `event.bot` — `"bad" | "good" | "not_detected"`
- `event.vpn`, `event.proxy`, `event.tampering`, `event.incognito` — booleans
- `event.suspect_score` — weighted Smart-Signals score (integer)
- `event.velocity` (object), `event.ip_blocklist` (object: `attack_source`, `email_spam`,
  `tor_node`) — for abuse / ATO logic

## Best practices
- One `FingerprintProvider` at the app root; don't re-instantiate per component.
- Region must match the workspace region on **both** sides (`us` | `eu` | `ap`).
- Don't block the UI on identification; handle the hook's `isLoading`/error states.
- Verify server-side on **every** sensitive action; treat the client result as a hint only.
- Fail closed on lookup errors for high-risk flows.
- Each `event_id` is single-use per action — don't cache a pass/fail across requests.
- Keep the secret key out of logs and out of any `NEXT_PUBLIC_` var or client component.

Referenced files: 7

View saved version →

---
name: fingerprint-node
description: Integrate the Fingerprint Server API into a Node/Express backend — fetch an event by event_id and read the verified identification and Smart Signals.
---

# Fingerprint — Node (Server API)

Integrate the Fingerprint Server API into a Node/Express backend: take the single-use `event_id`
your frontend sends, fetch the event server-side, and read the verified identification and Smart
Signals. The server is the source of truth — never trust a `visitor_id` or a decision sent straight
from the client.

> Docs: https://docs.fingerprint.com/reference/node-server-sdk · event schema: OpenAPI (https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi) or the Fingerprint MCP event-schema resource.

## Package
`@fingerprint/node-sdk` — install the latest version.

## Env var
- `FINGERPRINT_SECRET_API_KEY` — the secret key. Server-side only; never sent to the browser.

## Steps

1. **Install** `@fingerprint/node-sdk`.

2. **Create one client** at startup with the secret key and region (`Region.Global` | `Region.EU`
   | `Region.AP`, matching the workspace). Load `.env` (via `dotenv`) before the key is read —
   plain Node does not auto-load `.env`, and a missing key fails at startup with "Api key is not
   set". Pick the snippet by module system — check `package.json` `"type"`, not the file
   extension, since a TypeScript project can be either:
   - `"type": "module"` (ESM) → `snippets/client.mjs`. `import 'dotenv/config'` must be the
     **first import**: ESM evaluates all imports, in order, before any statement in the file, so a
     `dotenv.config()` call in the body runs too late.
   - otherwise (CommonJS) → `snippets/client.js`.

3. **Fetch and check the event.** Given the `event_id`, call `client.getEvent(eventId)` and apply
   the checks below before trusting the action. See `snippets/verify.js`.

## v4 event shape (flat — per the Server API event schema)
`getEvent` returns the event object directly:
- `event.identification.visitor_id` — the trusted visitor id
- `event.identification.confidence.score` — 0..1 (probability of a false-positive identification)
- `event.timestamp` — Unix ms of the event
- `event.replayed` — `true` if the payload was replayed
- `event.bot` — `"bad" | "good" | "not_detected"`
- `event.vpn`, `event.proxy`, `event.tampering`, `event.incognito` — booleans
- `event.suspect_score` — weighted Smart-Signals score (integer)
- `event.velocity` (object), `event.ip_blocklist` (object: `attack_source`, `email_spam`,
  `tor_node`)

## Checks (do all of them)
- **Found:** `event.identification.visitor_id` exists.
- **Replay / freshness:** reject if `event.replayed === true`, or if `event.timestamp` is older
  than your window (e.g. 2 minutes) — prevents reuse of an old `event_id`.
- **Confidence:** require `event.identification.confidence.score >= 0.9` for the action.
- **Smart Signals** (fail-closed for high-risk actions): `event.bot !== "not_detected"`,
  `event.vpn`, `event.proxy`, `event.tampering`.
- **Identity match:** bind `visitor_id` ↔ user on first trusted use; re-check on later actions.

## Notes
- Fetch and check server-side on **every** sensitive action.
- Fail closed on lookup errors for high-risk flows.
- Each `event_id` is single-use per action — don't cache a pass/fail across requests.
- Keep the secret key out of logs and any client bundle.

Referenced files: 4

View saved version →

---
name: Fingerprint Onboarding Guide
description: Use this guide to help onboard Fingerprint into a project.
---

Fingerprint helps teams prevent fraud, improve user experiences, and better understand their traffic.

To start using Fingerprint, one needs to begin with installing JS Agent on their webpage as described in the guide below. To confirm that installation is successful, one needs to check if requests successfully reach Fingerprint servers. To do it, one needs to either use Fingerprint MCP Tool `search_events` to query recent events, or to query Server API directly using instructions below.

Some users might want to create a new demo page from scratch while others want to integrate Fingerprint into an existing project—assistant should ask which option user prefers. When integrating into an existing project, assistant should ask the user on what pages of their website they would like to invoke Fingerprint, e.g.: main page only/checkout page only/all pages/etc. Some may choose to only call Fingerprint on selected pages, while others might want to do it on every single page of the website.

To communicate to Fingerprint, one needs a Public API key that is used by the JS Agent and exposed in the webpage source, and a Secret API key used for server-to-server communications. Both types of api keys can be fetched/created using Fingerprint MCP Tools `list_api_keys`, `get_api_key` and `create_api_key`. Alternatively one can talk to the Management API directly, see instructions below. Alternatively assistant can advise users to navigate to the Fingerprint Dashboard at https://dashboard.fingerprint.com/ to check the event history manually.

Successful onboarding consists of the following steps:

0. Important: Read the docs first: https://docs.fingerprint.com/docs/install-the-javascript-agent.md 
1. Add JS Agent invocation to the webpage.
2. Open the webpage in a browser
3. Confirm there's no JS errors in the browser console
4. Confirm the request shows up in the history fetched from Fingerprint.

References:
- Installing JS Agent: https://docs.fingerprint.com/docs/install-the-javascript-agent.md
- JS Agent API v4 Reference: https://docs.fingerprint.com/reference/js-agent-v4.md
- Making Server API requests: https://docs.fingerprint.com/reference/server-api-v4.md
- Making Management API requests: https://docs.fingerprint.com/docs/management-api.md

View saved version →

---
name: fingerprint-python
description: Integrate the Fingerprint Server API into a Python backend (FastAPI / Django / Flask) — fetch an event by event_id and read the verified identification and Smart Signals.
---

# Fingerprint — Python (Server API)

Integrate the Fingerprint Server API into a Python backend: take the single-use `event_id` your
frontend sends, fetch the event server-side, and read the verified identification and Smart
Signals. The server is the source of truth — never trust a `visitor_id` or a decision sent straight
from the client.

> Docs: https://docs.fingerprint.com/reference/python-server-sdk · event schema: OpenAPI (https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi) or the Fingerprint MCP event-schema resource.

## Package
`fingerprint-server-sdk` — install the latest version.

## Env var
- `FINGERPRINT_SECRET_API_KEY` — the secret key. Server-side only; never sent to the browser.

> Load `.env` with `python-dotenv` (`load_dotenv()`) and read the key via `os.environ`. Keep the
> secret key out of any client bundle, logs, or version control.

## Steps

1. **Install** `fingerprint-server-sdk`.

2. **Create one client** at startup with the secret key and region (`Region.US` | `Region.EU`
   | `Region.AP`, matching the workspace). Call `load_dotenv()` before the key is read — Python
   does not auto-load `.env`. See `snippets/client.py`.

3. **Fetch and check the event.** Given the `event_id`, call `client.get_event(event_id)` and apply
   the checks below before trusting the action. See `snippets/verify.py`.

## v4 event shape (flat — per the Server API event schema)
`get_event` returns the event object directly:
- `event.identification.visitor_id` — the trusted visitor id
- `event.identification.confidence.score` — 0..1 (probability of a false-positive identification)
- `event.timestamp` — Unix ms of the event (root-level, **not** under `identification`)
- `event.replayed` — `True` if the payload was replayed (root-level)
- `event.bot` — `BotResult.NOT_DETECTED` | `good` | `bad`
- `event.vpn`, `event.proxy`, `event.tampering`, `event.incognito` — booleans
- `event.suspect_score` — weighted Smart-Signals score (integer)
- `event.velocity` (object), `event.ip_blocklist` (object: `attack_source`, `email_spam`,
  `tor_node`)

## Checks (do all of them)
- **Found:** `event.identification.visitor_id` exists.
- **Replay / freshness:** reject if `event.replayed` is `True`, or if `event.timestamp` is older
  than your window (e.g. 2 minutes) — prevents reuse of an old `event_id`.
- **Confidence:** require `event.identification.confidence.score >= 0.9` for the action.
- **Smart Signals** (fail-closed for high-risk actions): `event.bot != BotResult.NOT_DETECTED`,
  `event.vpn`, `event.proxy`, `event.tampering`.
- **Identity match:** bind `visitor_id` ↔ user on first trusted use; re-check on later actions.

## Notes
- Fetch and check server-side on **every** sensitive action.
- Fail closed on lookup errors for high-risk flows.
- Each `event_id` is single-use per action — don't cache a pass/fail across requests.
- Keep the secret key out of logs and any client bundle.

Referenced files: 3

View saved version →

---
name: fingerprint-react
description: Integrate Fingerprint device identification into a React (or Preact) app — initialize the agent and get the visitor's visitor_id and event_id.
---

# Fingerprint — React

Integrate Fingerprint into a React app to identify visitors: initialize the agent once at startup,
then ask it for the visitor's `visitor_id` and a single-use `event_id` wherever you need it (on
load, or on an action like login or checkout).

> Docs: https://docs.fingerprint.com/docs/react · JS Agent v4: https://docs.fingerprint.com/reference/js-agent-v4

## Package
`@fingerprint/react` — install the latest version. (Preact uses the same package. For plain HTML
or an unsupported framework, use `fingerprint-javascript` and `@fingerprint/agent` instead.)

## Env var
- `FINGERPRINT_PUBLIC_API_KEY` — the public key, safe to ship to the browser.

> Bundlers only expose prefixed vars to client code — map the key to the bundler's convention:
> - Vite: `VITE_FINGERPRINT_PUBLIC_API_KEY` → `import.meta.env.VITE_...`
> - Create React App: `REACT_APP_FINGERPRINT_PUBLIC_API_KEY` → `process.env.REACT_APP_...`
> Never expose `FINGERPRINT_SECRET_API_KEY` to the frontend.

## Steps

1. **Install** `@fingerprint/react`. On pnpm, the package's `postinstall` may be blocked with
   `ERR_PNPM_IGNORED_BUILDS` — run `pnpm approve-builds`, approve `@fingerprint/react`, then
   install again. Keep pnpm's build-script protection on.

2. **Initialize once at the app root.** Wrap the app in `FingerprintProvider`, passing the public
   key and region (`us` | `eu` | `ap`, matching the workspace). Client-side only. See
   `snippets/provider.jsx`.

3. **Get the identification where you need it.** Use `useVisitorData`. For identify-on-demand pass
   `{ immediate: false }` and call `getData()` on the action you care about; it returns
   `{ visitor_id, event_id, ... }`. See `snippets/use-visitor-data.jsx`.

4. **Verify it works.** Disable your ad blocker, run the dev server, trigger the call, and confirm
   a `visitor_id` is logged in the browser console (or that the event appears on the dashboard
   Events page).

## Notes
- Region must match the workspace (`us` | `eu` | `ap`).
- Initialize once at the root; don't re-instantiate per component. Don't block the UI on
  identification — handle the hook's `isLoading` / error states.
- **Production:** protect the agent from ad blockers with a custom subdomain or proxy —
  https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers.
- Don't use legacy `@fingerprintjs/fingerprintjs-pro`, `FingerprintJS.load()`, or `scriptUrlPattern`.

Referenced files: 3

View saved version →

---
name: fingerprint-request-filtering
description: Protect your public Fingerprint API key from unauthorized use by configuring request filtering — allowed origins, header restrictions, and block lists — so the key only works from your own apps even though it's visible in client source. Use when securing the public key, preventing key abuse, or setting up allow/block lists.
---

# Fingerprint — Protect your public API key (request filtering)

Maps to the dashboard **"Protect your public API key"** Get Started step. The public API key ships
in your client source, so anyone can read it. Request filtering rules make the key only usable
from **your** apps, so a copied key can't rack up usage or pollute your data elsewhere.

This is configured in the dashboard against the environment's public key — there is no code change
beyond keeping the agent's origin consistent.

## Set up request filtering (dashboard)
1. In the dashboard, go to **Security → Web**.
2. Under **Websites**, click **Configure** and set an **allowlist** of the exact origins your app
   loads the agent from (e.g. `https://app.yourdomain.com`, plus `http://localhost:3000` for local
   dev). Requests from other origins are rejected. (Use a blocklist instead to deny specific origins.)
3. Optionally, under **Forbidden HTTP Headers**, click **Add rule** to restrict by header.
4. Save and test: a request from an allowed origin succeeds; one from an unlisted origin is blocked.
   Rule changes can take up to ~5 minutes to take effect.

## How to apply
1. **Enumerate every origin** that legitimately loads the agent: production domain(s), any preview
   domains, and local dev. Read these from the project (e.g. deployment config, `vite.config`,
   `next.config`, CORS settings) so the allowlist matches reality and you don't lock out prod.
2. **Add them in the dashboard** — this step has no SDK call.
3. If you also use a **custom subdomain / proxy** (`fingerprint-proxy-integration`), make sure the
   allowed origins still match where the page is served from.
4. Don't over-restrict: missing a real origin silently breaks identification there. Verify each
   listed app still identifies after enabling the rules.

## Best practices
- Treat the public key as public — request filtering is the control, not secrecy.
- Keep the allowlist in sync as you add domains/preview environments.
- Never try to "hide" the public key in code; it's meant to be in the browser. The **secret** key
  is the one that must never reach the client.
- Pair with the Rules Engine (`fingerprint-rules-engine`) for signal-based blocking on top of
  origin-based filtering.

Referenced files: 1

View saved version →

---
name: fingerprint-rules-engine
description: Set up no-code automatic protection with the Fingerprint Rules Engine — block or allow visitors based on Smart Signals without writing decision code — and consume the rule outcome server-side. Use when the user wants automatic protection, to build their first rule, or to enforce policy without hand-coding signal checks.
---

# Fingerprint — Rules Engine (no-code protection)

Maps to the dashboard **"Build your first rule"** Get Started step. The Rules Engine lets you
block or allow requests based on Smart Signals **in the dashboard**, without writing the decision
logic yourself. It's the fastest way to get automatic protection live, and it complements (doesn't
replace) server-side verification for your most sensitive actions.

## When to use this vs. coding the checks yourself
- **Rules Engine** — broad, policy-level protection you can change without a deploy (e.g. "block
  bad bots and IP-blocklisted requests on this key"). Good default for most traffic.
- **Server-side checks** (`fingerprint-smart-signals`) — fine-grained, per-action logic tied to
  your business state (e.g. step-up auth only for first-time-device logins). Keep these for
  high-risk flows.
- Most teams use both: a ruleset for the baseline, code for the nuanced cases.

> **Rules Engine is in beta and requires Server API v4.** Docs: https://docs.fingerprint.com/docs/rules-engine.

## Set up your first rule (dashboard)
This step is configured in the dashboard, not in code:
1. In the Fingerprint Dashboard, open **Rules Engine**.
2. Click **+ New ruleset** (you'll see the initial "Identify visitors" node).
3. Click **+ Add rule**, choose a condition on the **Visitor ID or a Smart Signal** — e.g.
   `incognito is true` → response **block** (a simple, common first rule) — and set the
   condition/response in the right-hand sidebar.

> **Start from a template for a known use case.** Rather than building from scratch, point the user
> at Fingerprint's prebuilt, customizable templates — Block bots, Block VPN users, Block region
> spoofing, Account takeover (ATO) prevention, and more — at https://fingerprint.com/templates/.
> Pick the one matching their goal and tune the signals/conditions from there.
4. Click **Save** (top right). Use the ruleset's **Settings** tab to rename, describe,
   enable/disable, or delete it — and to find the **ruleset ID** you'll need in code.

## Rulesets are NOT attached to API keys
This is the key thing to get right: a ruleset is **not** bound to a public/secret API key or
environment. It is evaluated only when you **explicitly pass its `ruleset_id`** to the Server API.
Without that parameter, the event comes back with no rule outcome — which is the usual reason a
rule "doesn't seem to fire."

## Consume the outcome in code
After your normal identification, fetch the event with the `ruleset_id` query parameter on the
`GET /events/{event_id}` (v4) call — e.g. via the Server SDK `getEvent` options or directly:

```
GET https://api.fpjs.io/v4/events/<EVENT_ID>?ruleset_id=<RULESET_ID>
```

The outcome is on the event at the root-level **`rule_action`** field:
- `ruleset_id`, `rule_id` (the matched rule), and `type` (`"block"` or `"allow"`)
- for block actions, the configured `status_code`, `headers`, and `body`

Read it and honor it:
- Treat a **block** `type` as a hard stop for the action.
- Log `rule_id` so you can tune rulesets from real traffic.
- Keep your own fail-closed checks for sensitive actions — a permissive ruleset should never
  downgrade your code-level protection.

> Guard the access — `rule_action` is only present when you passed a valid `ruleset_id`.

## Verify the rule is actually working
1. Trigger a request that should match (e.g. from a flagged bot/IP, or temporarily loosen the
   condition).
2. Fetch that event via `getEvent` **with `ruleset_id` passed** — not a plain `getEvent` call,
   which won't include `rule_action`.
3. Confirm `rule_action.type` and `rule_action.rule_id` match the rule you built.

## How to apply
1. If the user just wants automatic protection, **guide them to build the ruleset in the
   dashboard** (steps above) — there's no SDK call to create rules.
2. If they want to act on rule outcomes in code, pass `ruleset_id` to `getEvent` and add a check
   on the event's `rule_action` after verification — the same place `fingerprint-smart-signals`
   runs. Remind them a plain `getEvent` (no `ruleset_id`) returns no `rule_action`.
3. Recommend starting from a use-case template (https://fingerprint.com/templates/) or one narrow
   block rule (e.g. block incognito, bad bots), verifying it, then expanding — broad rules risk
   false positives.

## Best practices
- Roll out new rules in a non-blocking/log mode first if available, then switch to block.
- For account-level logic that needs your own data (e.g. keying off a `linkedId`/`tag`), do it in
  code with `fingerprint-smart-signals` — rule conditions match on the Visitor ID and Smart
  Signals, not your custom tagging metadata.
- Don't rely on rules alone for account-level fraud — combine with server-side identity binding.

Referenced files: 1

View saved version →

---
name: fingerprint-smart-signals
description: Use the full set of Fingerprint Smart Signals (bot, VPN, proxy, tampering, incognito, IP blocklist, velocity, suspect score, location spoofing, and more) from the v4 Server API to make richer server-side trust decisions. Use after the basic identification + verification is in place, when you want detailed insights about a visitor beyond confidence.
---

# Fingerprint — Smart Signals (v4 Server API)

Maps to the dashboard **"Access detailed insights about a visitor"** Get Started step. Once your
backend fetches an event server-side, the same `getEvent(eventId)` response carries 100+ signals.
This skill is about *acting on the full set*, not just `confidence`. All of these are
server-verified — never trust client-reported equivalents.

## Prerequisite
A working server-side flow (in whatever backend you run) that already calls `getEvent(eventId)`
with your `FINGERPRINT_SECRET_API_KEY`.

## Signals (flat v4 event shape)
Each Smart Signal is a top-level field on the event. The web-relevant set:

| Field | Meaning | Typical action |
| --- | --- | --- |
| `bot` | `"bad" \| "good" \| "not_detected"` | Block `"bad"` on protected endpoints |
| `vpn` | behind a VPN | Step-up / score for high-risk flows |
| `proxy` | behind a public proxy | Step-up / score |
| `tampering` | bool — anomalous browser signature / anti-detect browser | Reject for sensitive actions |
| `incognito` | private browsing | Score; don't hard-block alone |
| `ip_blocklist` | object: `attack_source`, `email_spam`, `tor_node` (IP on known-malicious lists) | Block or step-up on any sub-flag |
| `velocity` | object of interval counts (`5_minutes`/`1_hour`/`24_hours`) per visitor/IP/linked_id | Rate-limit abuse / ATO |
| `suspect_score` | integer — weighted aggregate of Smart Signals | Threshold-based routing |
| `location_spoofing` | GPS/timezone spoofing | Score for geo-gated actions |
| `developer_tools` | devtools open | Score for scraping/automation |
| `virtual_machine` | running in a VM | Score |
| `raw_device_attributes` | low-level device attributes | Custom heuristics |

> Field availability depends on your plan and platform (web vs. mobile), so guard each access
> (`event.vpn ?? false`) so a missing signal doesn't throw. Event schema: OpenAPI
> (https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi) or the Fingerprint MCP
> event-schema resource.

## How to apply
1. **Don't gate on a single signal.** Combine them into a per-action policy: e.g. block on
   `bot === "bad"` or `tampering`, step-up auth on `vpn || proxy || ip_blocklist`, and log
   `suspect_score` for analytics.
2. **Tune by action risk.** Login/checkout/password-reset warrant strict, fail-closed policies;
   read-only or low-risk actions can score-and-allow.
3. **Use `velocity` for abuse/ATO.** A spike of identifications for one `visitor_id` (or many
   visitors hitting one account) is a strong takeover/credential-stuffing signal.
4. **Persist signal outcomes** alongside your own fraud events so you can iterate on thresholds.
5. **Smart Signals require enablement.** Some are off by default in the workspace — enable them in
   the dashboard (Smart Signals settings) for the environment whose secret key you use.

## Best practices
- Server-side only — Smart Signals are never trustworthy when reported by the client.
- Fail closed on lookup errors for high-risk actions.
- Don't log the raw secret key or full event payloads containing PII.
- Re-evaluate signals on **every** sensitive action; each `event_id` is single-use.

See `snippets/signals-policy.js` for a composable scoring helper.

Referenced files: 2

View saved version →

---
name: fingerprint-svelte
description: Integrate Fingerprint device identification into a Svelte / SvelteKit app — initialize the agent and get the visitor's visitor_id and event_id.
---

# Fingerprint — Svelte

Integrate Fingerprint into a Svelte / SvelteKit app to identify visitors: initialize the provider
once at startup, then ask it for the visitor's `visitor_id` and a single-use `event_id` wherever
you need it (on load, or on an action like login or checkout).

> Docs: https://docs.fingerprint.com/docs/svelte · JS Agent v4: https://docs.fingerprint.com/reference/js-agent-v4

## Package
`@fingerprint/svelte` — install the latest version. (For plain HTML or an unsupported framework,
use `@fingerprint/agent` instead.)

## Env var
- `FINGERPRINT_PUBLIC_API_KEY` — the public key, safe to ship to the browser.

> Bundlers only expose prefixed vars to client code — map the key to the bundler's convention:
> - Vite (plain Svelte): `VITE_FINGERPRINT_PUBLIC_API_KEY` → `import.meta.env.VITE_...`
> - SvelteKit: `PUBLIC_FINGERPRINT_PUBLIC_API_KEY` → `import { PUBLIC_FINGERPRINT_PUBLIC_API_KEY } from '$env/static/public'`
> Only `PUBLIC_`-prefixed vars reach the browser in SvelteKit. Never expose the secret key.

## Steps

1. **Install** `@fingerprint/svelte`.

2. **Initialize once at the app root.** Wrap the app in `FingerprintProvider`, passing an `options`
   object with the public key and region (`us` | `eu` | `ap`, matching the workspace). The Svelte
   provider takes a single `options` prop. See `snippets/Provider.svelte`.

3. **Get the identification where you need it.** Use `useVisitorData`. For identify-on-demand pass
   `{ immediate: false }` and call `getData()` on the action you care about; it returns
   `{ visitor_id, event_id, ... }`. See `snippets/CreateAccountForm.svelte`.

4. **Verify it works.** Disable your ad blocker, run the dev server, trigger the call, and confirm
   a `visitor_id` is logged in the browser console (or that the event appears on the dashboard
   Events page).

## Notes
- Region must match the workspace (`us` | `eu` | `ap`).
- Initialize once at the app root; don't re-instantiate per component. Don't block the UI on
  identification — handle the `isLoading` / error states.
- **Production:** protect the agent from ad blockers with a custom subdomain or proxy —
  https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers.
- Don't use legacy `@fingerprintjs/fingerprintjs-pro`, `FingerprintJS.load()`, or `scriptUrlPattern`.

Referenced files: 3

View saved version →

---
name: fingerprint-tagging
description: Attach your own metadata (user IDs, account IDs, order IDs) to Fingerprint identification events using tag and linkedId in the v4 JS Agent, then read it back from the Server API and webhooks. Use to join Fingerprint data with your business data for fraud use-cases, tracking logged-in devices, and analytics.
---

# Fingerprint — Tagging events with your data (v4)

Maps to the dashboard **"Tag an event with your data"** Get Started step. Tagging attaches your
own context (user/account/order IDs, a plan name, a flow name) to an identification event so you
can join Fingerprint's `visitor_id` and signals with your business data — in the Server API, in
webhooks, and in dashboard search.

> **Note the client→server name change:** you send **`tag`** in the client `getData(...)` call, but
> it comes back on the server event as **`event.tags`** (plural). `linkedId` → `event.linked_id`.

## Two tools
- **`tag`** — arbitrary JSON metadata stored on the event (e.g. `{ userId, orderId, action }`).
  Use it to label *what the user was doing* when identified.
- **`linkedId`** — a string that groups related events under one identifier (e.g. a session id or
  a user id). Use it to **follow one entity across many events** and to query them together.

## Where it goes
Pass both when you identify, on the client. With the v4 React/Vue/Svelte/Angular SDKs the
identify call accepts them:

```js
// React/Next.js — useVisitorData hook
const { getData } = useVisitorData({ immediate: false })
const { event_id } = await getData({
  tag: { action: 'checkout', orderId, plan: 'pro' },
  linkedId: `user_${userId}`,
})
```

See `snippets/identify-with-tag.jsx` (client) and `snippets/read-tag.js` (server).

## How to apply
1. **Tag at the moment of the action**, alongside the existing identify call — don't add a second
   identify just to tag. The action handler already calls `getData()`; pass `tag`/`linkedId` there.
2. **Put identifiers in `linkedId`, descriptive context in `tag`.** `linkedId` is what you'll
   filter/group by; `tag` is the payload you read back.
3. **Send the `event_id` to your backend as usual.** The tag and linkedId come back on the
   server-side event from `getEvent(eventId)` (`event.tags`, `event.linked_id`) — verify the event
   first, then trust the tag you yourself set.
4. **Never put secrets or sensitive PII in a tag** — tags are set from the browser and are visible
   in the dashboard. Use opaque ids (`user_123`), not emails or tokens.
5. **Keep tags small and consistent** — a stable shape (`{ action, userId, ... }`) makes dashboard
   search and downstream joins reliable.

## Verify it worked
After wiring it up, trigger the tagged action once and confirm the tag appears: search recent
events in the dashboard (or via `search_events`) and check `event.tags` / `event.linked_id`. This
is exactly what the Get Started step checks for.

## Framework notes
- **React / Next.js**: `getData({ tag, linkedId })` from `useVisitorData`.
- **Vue / Svelte**: same `getData({ tag, linkedId })` on the composable/hook result.
- **Angular**: `fingerprint.getVisitorData({ tag, linkedId })`.
- **Plain JS Agent / CDN**: `fp.get({ tag, linkedId })`.

Referenced files: 3

View saved version →

---
name: fingerprint-vue
description: Integrate Fingerprint device identification into a Vue 3 (or Nuxt) app — initialize the agent and get the visitor's visitor_id and event_id.
---

# Fingerprint — Vue

Integrate Fingerprint into a Vue 3 app to identify visitors: register the plugin once at startup,
then ask it for the visitor's `visitor_id` and a single-use `event_id` wherever you need it (on
mount, or on an action like login or checkout).

> Docs: https://docs.fingerprint.com/docs/vuejs · JS Agent v4: https://docs.fingerprint.com/reference/js-agent-v4

## Package
`@fingerprint/vue` — install the latest version. (Nuxt uses the same package, registered
client-side. For plain HTML or an unsupported framework, use `@fingerprint/agent` instead.)

## Env var
- `FINGERPRINT_PUBLIC_API_KEY` — the public key, safe to ship to the browser.

> Bundlers only expose prefixed vars to client code — map the key to the bundler's convention:
> - Vite: `VITE_FINGERPRINT_PUBLIC_API_KEY` → `import.meta.env.VITE_...`
> - Vue CLI: `VUE_APP_FINGERPRINT_PUBLIC_API_KEY` → `process.env.VUE_APP_...`
> Never expose `FINGERPRINT_SECRET_API_KEY` to the frontend.

## Steps

1. **Install** `@fingerprint/vue`.

2. **Initialize once at the app root.** Register `FingerprintPlugin` with `app.use(...)`, passing
   the public key and region (`us` | `eu` | `ap`, matching the workspace). See `snippets/plugin.js`.

3. **Get the identification where you need it.** Use the `useVisitorData` composable. For
   identify-on-demand pass `{ immediate: false }` and call `getData()` on the action you care
   about; it returns `{ visitor_id, event_id, ... }`. See `snippets/use-visitor-data.vue`.

4. **Verify it works.** Disable your ad blocker, run the dev server, trigger the call, and confirm
   a `visitor_id` is logged in the browser console (or that the event appears on the dashboard
   Events page).

## Notes
- Region must match the workspace (`us` | `eu` | `ap`).
- Register the plugin once at the app root; don't re-instantiate per component. Don't block the UI
  on identification — handle the composable's `isLoading` / `error` state.
- **Production:** protect the agent from ad blockers with a custom subdomain or proxy —
  https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers.
- Don't use legacy `@fingerprintjs/fingerprintjs-pro`, `FingerprintJS.load()`, or `scriptUrlPattern`.

Referenced files: 3