## Recommended setup: Fingerprint CLI

`npx fingerprint` is the recommended way to add Fingerprint to an app. It is a single command that does the whole setup: it signs you in through your browser, then integrates Fingerprint automatically, with no second command to run. It creates your Fingerprint account, provisions your API keys and writes them into the right `.env` file, and adds client-side identification and server-side verification to your code.

The CLI supports React, Vue, Angular, Svelte, and Next.js on the frontend, and Node (Express, Fastify, Koa, NestJS, Hapi) and Python (FastAPI, Django, Flask) on the backend. The other commands are `fingerprint keys`, `fingerprint login`, `fingerprint signup`, `fingerprint whoami`, and `fingerprint logout`. Once you are set up, `fingerprint integrate --path PATH` integrates another project directory, but a first-time setup does not need it.

The per-framework quickstarts listed below are the manual alternative. They cover code changes only, so you still create your account and provision your API keys yourself.

# Account Sharing
Source: https://docs.fingerprint.com/docs/account-sharing-use-case-tutorial

Learn how to detect and prevent unauthorized account sharing

## Overview

This tutorial walks through implementing Fingerprint to prevent account sharing, where multiple people use the same account across different devices.

You'll begin with a starter app that includes a mock login page and a basic login flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to detect when an account is accessed from a new device. For simplicity, the sample will block logins from new devices for an account, but in practice, you would likely choose to add friction, log out other devices, or flag for review instead.

By the end, you'll have a sample app that limits an account to a single device and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor:

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `account-sharing` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Login page" />

    <Tree.File name="index.js - Front-end logic to handle login" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="server.js - Serves static files and login endpoint" />

    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="accounts.js - Account sharing logic" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock login page from the starter app. You can test the basic login form using the included test account (`demo@example.com` / `password123`) and clicking **Log in**. Then open the page in a completely different browser and log in with the same account. By default, the same account can be logged into from any device.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Log in**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the login payload. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including the verified `visitor_id` and risk signals such as browser tampering or bot activity.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Log in** button already has an event handler for submitting the credentials. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the login request to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
loginBtn.addEventListener("click", async () => {
  // ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
	    body: JSON.stringify({ email, password, eventId }),
    });
    const data = await res.json();

    // ...
  }
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your login logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/login` route there to also extract `eventId` from the request body and pass it into the `attemptLogin` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/login", async (req, reply) => {
  const { email, password, eventId } = req.body || {};
  const result = await attemptLogin({ email, password, eventId });
  return reply.send(result);
});
```

2. The `server/accounts.js` file contains the logic for handling logins. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `attemptLogin` function to accept `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  if (!email || !password) {
    console.error("Missing credentials.");
    return { success: false, error: "Login failed." };
  }

  if (!eventId) {
    console.error("Missing eventId.");
    return { success: false, error: "Login failed." };
  }

  const user = findAccountByEmail(email);
  if (!user || user.password !== password) {
    console.error("Invalid credentials");
    return { success: false, error: "Login failed." };
  }

  const event = await fpServerApiClient.getEvent(eventId);

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection and Suspect Score Smart Signals, which are only
  available on paid plans.
</Note>

A simple but powerful way to prevent automated abuse is to block bot logins. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found.

1. Continuing in the `attemptLogin` function in `server/accounts.js`, check the bot signal returned in the `event` object:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";

  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, error: "Login failed." };
  }

  // ...
}
```

You can also use Fingerprint's [Suspect Score](/docs/suspect-score) to flag high-risk logins. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload, helping to identify suspicious activity. While it's not typical to block actions based solely on a high risk score, this example shows how you might incorporate it. In a real application, a better approach would be to flag the attempt for review or add some additional step-up authentication.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the login if it exceeds a chosen threshold (for example, 20):

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  // ...

  const suspectScore = event.suspect_score || 0;

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, error: "Login failed." };
  }

  // ...
}
```

## 6. Prevent account sharing

Next, use the trusted `visitor_id` from the `event` object to enforce a one-device-per-account rule. If the same account logs in from a different device (`visitor_id`), reject the login. In production you may choose to allow a certain number of devices, add step-up verification, or alert the user. *(This example oversimplifies login logic for demonstration purposes.)*

Note: The starter app includes a SQLite database with these tables already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
accounts - Stores login credentials for test accounts
  email TEXT PRIMARY KEY
  password TEXT NOT NULL

account_devices - Logs which device (visitorId) is associated with each account
  email TEXT PRIMARY KEY
  visitorId TEXT NOT NULL
  createdAt INTEGER NOT NULL
```

1. Add some helper functions to the bottom of the `server/accounts.js` file to read and write device details for an account:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
// Get the last seen device for the user
function getLastDeviceFor(email) {
  return db.prepare(`SELECT visitorId FROM account_devices WHERE email = ?`).get(email);
}

// Record the visitor's device on logging in
function saveDeviceFor(email, visitorId) {
  db.prepare(
    `INSERT OR IGNORE INTO account_devices (email, visitorId, createdAt)
     VALUES (?, ?, ?)`,
  ).run(email, visitorId, Date.now());
}
```

2. Update `attemptLogin` to retrieve the `visitor_id` and use it to enforce the one device per account rule and record successful logins:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  // ...

  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, error: "Login failed." };
  }

  const visitorId = event.identification.visitor_id;

  const last = getLastDeviceFor(email);
  if (last && last.visitorId !== visitorId) {
    console.error("Access from new device detected.");
    return {
      success: false,
      error:
        "You can only access this account from one device. (Reset the demo to simulate logging out on the other device.)",
    };
  }
  if (!last) saveDeviceFor(email, visitorId);

  return { success: true };
}
```

This gives you a basic system to detect and block account sharing. You can extend it by allowing a small number of devices per account, expiring devices after some time, adding step-up verification on change, notifying the account owner, etc.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error checking, and password handling that align with your
  production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full protected login flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Log in (`demo@example.com` / `password123`) in one browser. You should see a success response.
3. In a different browser or device, try logging in with the same account. The second attempt will be rejected because the account is tied to a different device.
4. Bonus: Test the flow using a headless browser or automation tool to see bot detection in action. A sample script is available in `test-bot.js`. While your app is running, run the script with `node test-bot.js` in your terminal and observe that the automated logins are blocked.

## Next steps

You now have a working login flow secured with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your business policies, or layer in additional checks for suspicious visitors.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](https://github.com/fingerprintjs/node-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Account Takeover
Source: https://docs.fingerprint.com/docs/account-takeover-use-case-tutorial

Learn how to protect your application from account takeover attacks

## Overview

This tutorial walks through implementing Fingerprint to prevent account takeover. Account takeover (ATO) occurs when an attacker gains access to a real user's account, often through stolen credentials, automated login abuse at scale, phishing, or other attacks aimed at your sign-in flow.

You'll begin with a starter app that includes a mock login page and a basic login flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to detect and block automated login attempts.

By the end, you'll have a sample app that rejects high-risk traffic and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

<Note>
  This tutorial requires the Bot Detection Smart Signal, which is only available
  on paid plans.
</Note>

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
cd use-case-tutorials/account-takeover
```

2. This tutorial uses the `account-takeover` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Login page" />

    <Tree.File name="index.js - Front-end logic to handle login" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="server.js - Serves static files and login endpoint" />

    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="accounts.js - Login validation and account takeover checks" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. From the `account-takeover` directory, install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock login page from the starter app. You can test the basic login form using the included test account (`demo@example.com` / `password123`) and clicking **Log in**.
7. Then try to log in using the included headless bot test script `test-bot.js`. While the app is running, execute `node test-bot.js` and observe that the automated script logs in successfully. By default, the server does not distinguish between bots and real users.

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Log in**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the login payload. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including bot detection and other signals.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(
  `https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`
).then((Fingerprint) => Fingerprint.start({ region: "us" }));
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).

3. Near the bottom of `public/index.js`, the **Log in** button already has an event handler for submitting the credentials. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the login to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
loginBtn.addEventListener("click", async () => {
  // ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ email, password, eventId }),
    });
    const data = await res.json();

    // ...
  }
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your login logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID, Bot Detection, and other [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/login` route there to also extract `eventId` from the request body and pass it into the `attemptLogin` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/login", async (req, reply) => {
  const { email, password, eventId } = req.body || {};
  const result = await attemptLogin({ email, password, eventId });
  return reply.send(result);
});
```

2. The `server/accounts.js` file contains the logic for handling logins. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).

4. Update the `attemptLogin` function to accept `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  if (!email || !password) {
    console.error("Missing credentials.");
    return { success: false, error: "Login failed." };
  }

  if (!eventId) {
    console.error("Missing eventId.");
    return { success: false, error: "Login failed." };
  }

  const event = await fpServerApiClient.getEvent(eventId);

  const user = findAccountByEmail(email);
  if (!user || user.password !== password) {
    console.error("Invalid credentials");
    return { success: false, error: "Login failed." };
  }

  return { success: true };
}
```

Using the `eventId`, the `getEvent` method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more. You'll use those fields in the next steps to decide whether a sign-in attempt looks like account takeover or other abuse.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block logins after too many recent failed attempts

Takeover attempts and password guessing often produce many failures from the same device, even when the attacker rotates usernames. Once you can reliably associate attempts with a Fingerprint visitor ID, you can persist outcomes and rate-limit or block visitors that exceed a threshold of recent failures—before or alongside other checks.

The starter app includes a SQLite `login_attempts` table for this demo. Each row records the visitor ID, account email, whether the attempt succeeded, and a timestamp:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
accounts - Stores login credentials for test accounts
  email TEXT PRIMARY KEY
  password TEXT NOT NULL

login_attempts - Records each login attempt for rate limits and device history
  id INTEGER PRIMARY KEY AUTOINCREMENT
  visitorId TEXT NOT NULL
  email TEXT NOT NULL
  success INTEGER NOT NULL (0 = failed, 1 = succeeded)
  createdAt INTEGER NOT NULL
```

1. Add helper functions at the bottom of `server/accounts.js` to record failures and count how many failed attempts a visitor had in the last 24 hours:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
function logFailedAttempt(visitorId, email) {
  db.prepare(
    `INSERT INTO login_attempts (visitorId, email, success, createdAt) VALUES (?, ?, 0, ?)`
  ).run(visitorId, email, Date.now());
}

function getRecentFailedAttempts(visitorId) {
  const since = Date.now() - 24 * 60 * 60 * 1000;
  const row = db
    .prepare(
      `SELECT COUNT(*) as count
       FROM login_attempts
       WHERE visitorId = ? AND success = 0 AND createdAt >= ?`
    )
    .get(visitorId, since);
  return row.count;
}
```

2. In `attemptLogin`, after you call `getEvent`, read `visitor_id` from `event.identification`. Then before validating the password, block visitors with too many recent failures. On any failed outcome in this flow, record a row with `logFailedAttempt` so later attempts stay counted.

At this stage, `attemptLogin` should look like this:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  if (!email || !password) {
    console.error("Missing email or password.");
    return { success: false, error: "Login failed." };
  }

  if (!eventId) {
    console.error("Missing eventId.");
    return { success: false, error: "Login failed." };
  }

  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id;

  if (getRecentFailedAttempts(visitorId) >= 3) {
    logFailedAttempt(visitorId, email);
    console.error("Too many failed login attempts.");
    return { success: false, error: "Login failed." };
  }

  const user = findAccountByEmail(email);
  if (!user || user.password !== password) {
    logFailedAttempt(visitorId, email);
    console.error("Invalid credentials");
    return { success: false, error: "Login failed." };
  }

  return { success: true };
}
```

## 6. Block unrecognized devices from logging in

Valid passwords are often used from new devices during account takeover. A practical pattern is to require a prior successful login from the same visitor ID for that user before treating the session as routine, or to step up authentication (MFA, OTP, etc.) when that history is missing.

This tutorial is simplified and will block unrecognized devices from logging in for demonstration purposes. For the first successful login for an account there is no history yet, so allow it and establish a baseline. For later logins, if the account already has at least one successful login stored, but this visitor ID has never succeeded for that email, block as an unrecognized device.

1. Add helpers to query and record successful attempts by email and visitor ID:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
function hasAnySuccessfulLogin(email) {
  return !!db
    .prepare(
      `SELECT 1 FROM login_attempts WHERE email = ? AND success = 1 LIMIT 1`
    )
    .get(email);
}

function hasSuccessfulLoginForVisitor(email, visitorId) {
  return !!db
    .prepare(
      `SELECT 1 FROM login_attempts WHERE email = ? AND visitorId = ? AND success = 1 LIMIT 1`
    )
    .get(email, visitorId);
}

function logSuccessfulAttempt(visitorId, email) {
  db.prepare(
    `INSERT INTO login_attempts (visitorId, email, success, createdAt) VALUES (?, ?, 1, ?)`
  ).run(visitorId, email, Date.now());
}
```

2. Within `attemptLogin`, after the password matches, add the check before returning and logging a successful attempt. If the account already has successful logins but this visitor ID has not, log a failed attempt and return an error:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
const accountHasSuccessfulLogins = hasAnySuccessfulLogin(email);
const visitorHasLoggedInBefore = hasSuccessfulLoginForVisitor(email, visitorId);

if (accountHasSuccessfulLogins && !visitorHasLoggedInBefore) {
  logFailedAttempt(visitorId, email);
  console.error("Unrecognized device.");
  return {
    success: false,
    error: "Login failed.",
  };
}

logSuccessfulAttempt(visitorId, email);
return { success: true };
```

## 7. Block bots

Automated scripts and headless browsers often show up in account takeover workflows. Fingerprint Bot Detection helps differentiate real users from abusive automation. Fingerprint returns `not_detected` if no bot activity is found, `good` for known bots (for example known search engines, verified AI agents, etc.), and `bad` for other automation.

1. Continuing in `attemptLogin`, add a bot check on the same `event` you already fetched, then a [Suspect Score](/docs/suspect-score) check (optional but useful as a secondary layer for suspicious traffic):

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
const botDetected = event.bot !== "not_detected";
if (botDetected) {
  logFailedAttempt(visitorId, email);
  console.error("Bot detected.");
  return { success: false, error: "Login failed." };
}

const suspectScore = event.suspect_score || 0;
if (suspectScore > 20) {
  logFailedAttempt(visitorId, email);
  console.error(`High Suspect Score detected: ${suspectScore}`);
  return { success: false, error: "Login failed." };
}

logSuccessfulAttempt(visitorId, email);
return { success: true };
```

Suspect Score is a weighted rollup of Smart Signals. In production you might use it to step up authentication rather than hard-block, depending on your business rules.

Together, rate limits by visitor ID, device history, and bot detection give you a layered defense against account takeover. You can extend this with more [Smart Signals](/docs/smart-signals-reference), different thresholds, or alternate responses.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real
  application, make sure to implement proper security practices, error checking,
  and password handling that align with your production standards.
</Info>

## 8. Test your implementation

Now that everything is wired up, you can test the full protected login flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Log in once with a valid test account (`demo@example.com` / `password123`). You will see a success response, and that browser’s visitor ID will be recorded as a known trusted device for that account.
3. Try several failed login attempts using the wrong password from the same browser. After three failures within the rolling time window, the recent failed attempts check blocks that visitor ID, including with the correct password, until the window rolls forward or you reset the demo database.
4. Reset the demo database, then log in successfully again from your browser so there is a known trusted device on file for `demo@example.com`.
5. With that successful browser session in place, open the demo in a completely different browser. Attempt to log in with the correct credentials. Since the new browser has no prior successful login, the login will be rejected as an unrecognized device
6. Next, run the headless test script from the `account-takeover` directory. It uses the correct credentials but because it is a headless browser, the login will be rejected as a bot:

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

*Note: If you encounter errors launching the automated browser, make sure you have the testing browser installed:*

```bash Terminal theme={"theme":"github-dark-dimmed"}
npx puppeteer browsers install chrome
```

## Next steps

You now have a working login flow that layers visitor-based rate limiting, device history, and bot detection with Fingerprint for account takeover protection. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your business policies, or layer in additional defenses such as multi-factor authentication.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# AI agent detection
Source: https://docs.fingerprint.com/docs/ai-agents

Detect and verify AI agents visiting your web properties, and distinguish them from malicious bots.

AI agent detection lets you identify authorized AI agents visiting your website and distinguish them from malicious bots.

It uses [Web Bot Auth](/docs/bot-detection/web-bot-auth-implementation), a cryptographic signing protocol, to verify agent identity. When Fingerprint detects an agent, it returns structured metadata, including the agent's provider, name, and the identity verification status in the `bot_info` field of the Server API response.

This lets you make precise access decisions: allow authorized agents, block unverified automation, or apply different logic based on agent category and provider.

## How verification works

1. The agent signs its HTTP requests using a private key.
2. Fingerprint retrieves the agent's public key from a directory hosted at a known URL.
3. Fingerprint verifies the signature and returns an `identity` value in `bot_info`.

The `identity` value reflects the outcome of the verification:

| Value      | Meaning                                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| `signed`   | Signature verified against the agent's public key directory                                                    |
| `verified` | Signature verified, and the agent is operated exclusively by its vendor (not configurable by vendor customers) |
| `unknown`  | Agent recognized, but no verifiable identity was presented                                                     |
| `spoofed`  | Agent presented an identity that failed verification                                                           |

## API response

When Fingerprint detects a bot or agent, the [Server API](/reference/server-api-get-event) response includes the following fields:

| Field      | Type   | Description                                      |
| ---------- | ------ | ------------------------------------------------ |
| `bot`      | string | `good`, `bad`, or `not_detected`                 |
| `bot_type` | string | Additional classification, e.g. `ai_agent`       |
| `bot_info` | object | Extended metadata for recognized agents and bots |

The `bot_info` object contains:

| Field      | Description                                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | Agent category, e.g. `ai_agent`, `ai_browser`, `browser_automation` ([full list](/docs/bot-detection/bot-directory#bot_info-metadata)) |
| `provider` | The organization that operates the agent, e.g. `OpenAI` or `AWS`                                                                       |
| `name`     | Human-readable agent name, e.g. `ChatGPT Agent`                                                                                        |
| `identity` | Verification status: `signed`, `verified`, `unknown` or `spoofed`                                                                      |

`bot_info` is available in Server API v4 and only when Fingerprint recognizes the agent or bot. See the [Server API reference](/reference/server-api-get-event#response-bot-info) for the full schema.

## Supported AI agents

The following agents are currently detected and return `bot_info` metadata:

| Name              | Provider    | Category     | Identity |
| ----------------- | ----------- | ------------ | -------- |
| ChatGPT Agent     | OpenAI      | `ai_agent`   | `signed` |
| Bedrock AgentCore | AWS         | `ai_agent`   | `signed` |
| Browserbase Agent | Browserbase | `ai_agent`   | `signed` |
| Manus Agent       | Manus       | `ai_agent`   | `signed` |
| AGI Agent         | AGI Inc     | `ai_agent`   | `signed` |
| Anchor Browser    | Anchor      | `ai_browser` | `signed` |

For the full list of all detectable bots and agents, see the [Bot Directory](/docs/bot-detection/bot-directory).

## Using detection results

The `bot` field (`good`, `bad`, `not_detected`) is a legacy signal. For AI agents and other recognized bots, use `bot_info.identity` instead, as it provides more precise, actionable information.

Note that `identity` is only available for well-known bots and agents in the [Bot Directory](/docs/bot-detection/bot-directory). Some generic browser automation tools (Selenium, Playwright, headless Chrome, etc.) will not have a `bot_info` entry and should be handled using the `bot: bad` signal.

| Scenario                               | Suggested action                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `bot_info.identity: verified`          | **Allow**: agent identity is confirmed and safety verified                                 |
| `bot_info.identity: signed`            | **Allow**: agent identity is cryptographically verified                                    |
| `bot_info.identity: unknown`           | **Apply custom logic**: agent is recognized but unverified                                 |
| `bot_info.identity: spoofed`           | **Review**: verification failed, which may indicate misconfiguration or malicious spoofing |
| `bot` is `bad`, no `bot_info` (legacy) | **Review or Block**: unrecognized and potentially malicious automation                     |

## Next steps

<Columns>
  <Card title="Bot Directory" icon="globe" href="/docs/bot-detection/bot-directory">
    Full list of detectable bots and agents
  </Card>

  <Card title="Web Bot Auth implementation" icon="braces" href="/docs/bot-detection/web-bot-auth-implementation">
    Cryptographically sign your agent to verify identity
  </Card>

  <Card title="Submit your agent to Fingerprint directory" icon="shield" href="https://dashboard.fingerprint.com/submit-bot">
    Submit your agent or bot to the Fingerprint Bot Directory
  </Card>
</Columns>


# AI assistant detection
Source: https://docs.fingerprint.com/docs/ai-assistants

Detect and verify AI assistants visiting your web properties or API endpoints and distinguish them from malicious bots.

<Info>
  AI assistant detection requires a [Flow worker](/docs/flow-deployments#using-a-flow-worker-to-detect-bots-at-the-edge) deployment.
</Info>

AI assistants are LLM chat applications that can answer questions, summarize information, and make requests to websites to gather information. When an AI assistant is making a request to a website, Fingerprint can detect these requests and identity the assistant category, provider and identity. The most common AI assistants are ChatGPT, Gemini, and Claude.ai.

Fingerprint's AI assistant detection lets you detect and verify AI assistants visiting your website or using your APIs and distinguish them from malicious bots.

It uses [Web Bot Auth](/docs/bot-detection/web-bot-auth-implementation), IP, and DNS checks to verify AI assistant identity. When Fingerprint detects an assistant, it returns structured metadata, including the assistant's provider, name, and the identity verification status in the `bot_info` field of the Server API response.

This lets you make precise access decisions: allow authorized assistants, block unverified automation, or apply different logic based on assistant category and provider.

## How identity verification works

Fingerprint will use all available methods to verify the assistant identity and will also detect spoofing / impersonation attempts.

The `identity` value reflects the outcome of the verification:

| Value      | Meaning                                                     |
| ---------- | ----------------------------------------------------------- |
| `verified` | Identity verified                                           |
| `unknown`  | Assistant recognized, but the identity couldn't be verified |
| `spoofed`  | Assistant presented an identity that failed verification    |

## API response

When Fingerprint detects a bot, the [Server API](/reference/server-api-get-event) response includes the following fields:

| Field      | Type   | Description                                                   |
| ---------- | ------ | ------------------------------------------------------------- |
| `bot`      | string | `good`, `bad`, or `not_detected`                              |
| `bot_type` | string | Additional classification, e.g. `ai_assistant`                |
| `bot_info` | object | Extended metadata for recognized assistants, agents, and bots |

The `bot_info` object contains:

| Field      | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `category` | `ai_assistant`                                                             |
| `provider` | The organization that operates the assistant, e.g. `OpenAI` or `Anthropic` |
| `name`     | Human-readable assistant name, e.g. `ChatGPT-User`                         |
| `identity` | Verification status: `verified`, `unknown` or `spoofed`                    |

`bot_info` is available in Server API v4 and only when Fingerprint recognizes the AI tool or a bot. See the [Server API reference](/reference/server-api-get-event#response-bot-info) for the full schema. The full list of bots is available here: [full list](/docs/bot-detection/bot-directory#bot_info-metadata).

## Supported AI assistants

For the full list of all detectable AI tools and bots, see the [Bot Directory](/docs/bot-detection/bot-directory).

## Using detection results

The `bot` field (`good`, `bad`, `not_detected`) is a legacy signal. For AI assistants and other recognized bots, use `bot_info.identity` instead, as it provides more precise, actionable information.

Note that `identity` is only available for well-known bots and assistants in the [Bot Directory](/docs/bot-detection/bot-directory). Some generic browser automation tools (Selenium, Playwright, headless Chrome, etc.) will not have a `bot_info` entry and should be handled using the `bot: bad` signal.

| Scenario                               | Suggested action                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `bot_info.identity: verified`          | **Allow**: assistant identity is confirmed and safety verified                             |
| `bot_info.identity: unknown`           | **Apply custom logic**: assistant is recognized but unverified                             |
| `bot_info.identity: spoofed`           | **Review**: verification failed, which may indicate misconfiguration or malicious spoofing |
| `bot` is `bad`, no `bot_info` (legacy) | **Review or Block**: unrecognized and potentially malicious automation                     |

## Next steps

<Columns>
  <Card title="Bot Directory" icon="globe" href="/docs/bot-detection/bot-directory">
    Full list of detectable bots and agents
  </Card>

  <Card title="AI agent detection" icon="braces" href="/docs/ai-agents">
    Detect and verify AI agents
  </Card>

  <Card title="Submit your assistant to Fingerprint directory" icon="shield" href="https://dashboard.fingerprint.com/submit-bot">
    Submit your assistant or bot to the Fingerprint Bot Directory
  </Card>
</Columns>


# Overview
Source: https://docs.fingerprint.com/docs/akamai-proxy-integration



Fingerprint JavaScript agent v4.0.0 or later is required.

*Fingerprint Akamai Proxy Integration* is responsible for proxying identification and agent-download requests between your website and Fingerprint through your Akamai infrastructure. The integration consists of a set of property rules you need to add to your Akamai property configuration. The property rules template is available on [GitHub][proxy-github-repo].

<img alt="" />

<Warning>
  **Limitations and expectations**

  ### Limited to Enterprise plan

  Support for the Akamai Proxy Integration is provided only to customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup][custom-domain] or [Cloudflare Proxy Integration][cloudflare-proxy].

  ### Manual updates occasionally required

  The underlying data contract in the identification logic can change to keep up with browser and device releases. Using the Akamai Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.

  ### Tested property types

  This integration has been tested with the **Dynamic Site Accelerator (DSA)** Akamai property type only. **Ion** (Standard / Premier) and **API Acceleration (AA)** have not been formally tested. These property types might work because Akamai's Property Manager exposes the same rule tree across them, but compatibility is not guaranteed. Validate the integration in a staging property before activating it in production. Contact [support][support] if you encounter issues.
</Warning>

## The benefits of using the Akamai Proxy Integration

* Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox.
* Cookies are now recognized as "first-party". This means they can live longer in the browser and extend the lifetime of visitor IDs.
* Ad blockers will not block our Fingerprint JavaScript agent from loading. Attempts to connect to an external URL will be stopped by most ad blockers while attempts to connect to the same site URL will be allowed.
* Ad blockers will not block our identification requests since they are sent to the specific path or subdomain that belongs to the same site.
* Insight and control over the identification requests that can be combined with other Akamai features like property rules and traffic reports.
* With the Akamai Proxy Integration, you can manage unlimited subdomains and paths and provide Fingerprint services to all your customers at any scale while benefiting from all the 1st-party integration improvements.
* Cookie security: Akamai Proxy Integration drops all the cookies sent from the origin website. The source is open-source so this behavior can be transparently verified and audited.
* Easy to meet compliance and auditing requirements.

## Integration setup overview

1. Issue a proxy secret in the Fingerprint Dashboard.
2. Create a path variable used by the Akamai property rules and client agent configuration on your website or mobile app.
3. Install and configure the integration in your Akamai account. You have 2 options:
   1. [Using Terraform][akamai-terraform] (recommended).
   2. [Using Akamai Property Manager API][akamai-papi].

Finally, configure the Fingerprint JavaScript agent on your website or client application.

## Step 1: Issue a Fingerprint proxy secret

Issue a Fingerprint proxy secret to authenticate requests from your Akamai infrastructure.

1. Go to the [Fingerprint dashboard][fingerprint-dashboard] and select your workspace.
2. In the left menu, navigate to [**API keys**][fingerprint-api-keys].
3. Click **Create Proxy Key**.
4. Give it a name, for example, `Akamai proxy integration`.
5. Optionally, you can [choose an environment][fingerprint-environments] for the proxy secret.
   1. By default, the proxy secret works for all environments in your workspace.
   2. A proxy secret scoped to a specific environment can only authenticate identification requests made with a public API key from the same environment.
6. Click **Create API Key**.

You will use the proxy secret value in the following step, so store it somewhere safe. You cannot retrieve the secret later.

## Step 2: Create a path variable

Set the path variable you will use throughout your property configuration and the JavaScript agent configuration on your website. This value is arbitrary. Just decide what your value is and write it down somewhere.

In this guide, we will use a readable value corresponding to the variable name to make it easier to follow:

```text theme={"theme":"github-dark-dimmed"}
FPJS_INTEGRATION_PATH="FPJS_INTEGRATION_PATH"
```

However, your value used in production should look more like a random string:

```text theme={"theme":"github-dark-dimmed"}
FPJS_INTEGRATION_PATH="ore54guier"
```

That is because ad blockers might automatically block requests from any URL containing fingerprint-related terms like "fingerprint", "fpjs", "track", etc. Random strings are the safest. So whenever you see a value like `FPJS_INTEGRATION_PATH` in this guide, you should use your random value instead.

## Step 3: Install and configure the integration in your Akamai property

You can choose from two available installation methods.

### Using Terraform (recommended)

If you manage your infrastructure as code using Terraform, you can use the Fingerprint Akamai proxy integration Terraform module. This installation method does not include any mechanism for automatic updates. The proxy function code is updated every time you run `terraform apply`.

If you prefer the Terraform installation method, continue with [**Install Akamai proxy integration using Terraform**][akamai-terraform], then come back to this page to configure the Fingerprint JavaScript agent on your website.

### Using Akamai Property Manager API

If you don't use Terraform to manage your infrastructure, you can deploy the integration using Akamai Property Manager API. This installation method does not include any mechanism for automatic updates. You will need to manually repeat the deployment process every time you update the integration.

If you prefer the Akamai Property Manager API installation method, continue with [**Install Akamai proxy integration using Akamai Property Manager API**][akamai-papi], then come back to this page to configure the Fingerprint JavaScript agent on your website.

<Note>
  **Note: Usage of `Origin IP Access Control List` rule**

  * To support IPv6 origins, the integration uses the `Origin IP Access Control List` rule.
  * Without additional configuration, this results in a warning in Akamai Control Center: "You have Origin IP Access Control List enabled in a rule in your property. You should also enable Tiered Distribution in either the same rule or a parent rule. This will better support caching on edge servers."
  * This warning is expected and means the integration is working. We recommend following the recommendation in the warning and enabling Tiered Distribution in your property rules. See the [Akamai documentation for Origin IP ACL][akamai-ip-acl] for more details.
</Note>

## Configure Fingerprint Agent

1. Use the random path variable created in the deployment steps according to your deployment method to construct the `endpoints` URL.
2. Configure the Fingerprint JavaScript agent on your website accordingly:

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent';

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: ['https://yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
    region: 'us',
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN installation theme={"theme":"github-dark-dimmed"}
  const url = 'https://yourwebsite.com/FPJS_INTEGRATION_PATH/web/v4/PUBLIC_API_KEY?region=us';
  const fpPromise = import(url)
  .then(Fingerprint => Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: ['https://yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
    region: 'us',
  }));

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

<Note>
  **Parameter URL nuances**

  * The `region` query parameter value needs to reflect the [region](/docs/regions) of your application.
  * Note that the import URL for the CDN installation method and the `endpoints` URL used by NPM packages are different and **cannot be used interchangeably**.
</Note>

If everything is configured correctly, you should receive the latest Fingerprint client-side script and the identification result through your Akamai integration. If you have any questions, reach out to our [support team][support].

## Monitoring the integration

Go to **Dashboard** > [**SDKs & integrations**][fingerprint-integrations] > **Akamai** to see the status of your integration. Here you can monitor:

* If the integration is up to date.
* How many identification requests are coming through the integration (and how many are not).
* The error rate of proxied identification requests (caused by missing or incorrect proxy secret).

The information on the status page is cached so allow a few minutes for the latest data points to be reflected.

<img alt="" />

[akamai-ip-acl]: https://techdocs.akamai.com/origin-ip-acl/docs/welcome

[akamai-papi]: /docs/deploy-akamai-proxy-integration-via-papi

[akamai-terraform]: /docs/deploy-akamai-proxy-integration-via-terraform

[cloudflare-proxy]: /docs/cloudflare-integration

[custom-domain]: /docs/custom-subdomain-setup

[fingerprint-api-keys]: https://dashboard.fingerprint.com/api-keys

[fingerprint-dashboard]: https://dashboard.fingerprint.com

[fingerprint-environments]: /docs/multiple-environments#proxy-integrations-and-proxy-secrets

[fingerprint-integrations]: https://dashboard.fingerprint.com/integrations

[proxy-github-repo]: https://github.com/fingerprintjs/akamai-proxy

[support]: https://fingerprint.com/support/


# Analytics
Source: https://docs.fingerprint.com/docs/analytics



## Overview Page

The Overview page serves as the homepage for the Dashboard, displaying key insights and metrics at a glance. The page features a row of selected key metrics, a timeline chart, and distribution lists. The page also features a date range filter, and an environment filter.

You can access the Overview page by visiting **Dashboard** > [**Overview**](https://dashboard.fingerprint.com/overview).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 44 35@2x" />
</Frame>

The **key metrics** (1) provide you with information and insights about your integration at a glance.

<Expandable title="available key metrics">
  | Metric                                | Description                                                                                                                                                |
  | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | **API usage**                         | Number of identification requests made in the selected period                                                                                              |
  | **Number of unique visitors**         | Number of distinct visitor IDs seen in the selected period                                                                                                 |
  | **Events per visitor ratio**          | Average number of identification events for every uniquely identified visitor                                                                              |
  | **Number of restricted API calls**    | Number of API calls that were restricted due to request filtering rules, exceeding limits on your environments, or exceeding limits on your workspace plan |
  | **Number of throttled API calls**     | Number of API calls that went over the RPS limit and were throttled                                                                                        |
  | **Average requests per second (RPS)** | Rolling average number of requests per second in the selected period                                                                                       |
  | **Peak requests per second (RPS)**    | Peak number of requests per second in 5-minute window                                                                                                      |
</Expandable>

The **timeline chart** (2) provides a view into key metrics over time (hourly, daily, monthly), and shows comparison to the previous period.

<Expandable title="available timeline views">
  | Timeline view                 | Description                                                                                        |
  | ----------------------------- | -------------------------------------------------------------------------------------------------- |
  | **API usage**                 | Displays a timeline chart of API usage, comparing currently selected period to the previous period |
  | **Events per visitor**        | Shows the timeline chart of the ratio of identification requests per unique visitor ID             |
  | **Failed API calls**          | Shows the number of throttled and restricted API calls for the selected period                     |
  | **Requests per second (RPS)** | Shows API usage bandwidth as average and peak requests per second, for the selected period         |
</Expandable>

The granularity options available depend on the selected date range. **Hourly** requires a range of 7 days or less, **Daily** requires a range between 1 day and 6 months, and **Monthly** requires a range of at least 2 months.

The chart selector also has a **Breakdowns** group. Instead of a single total, a breakdown plots the composition of your identification events over time as a stacked chart of the top 5 entities for the selected period, with all remaining entities grouped into **Other**.

<Expandable title="available breakdowns">
  | Breakdown             | Description                                                      |
  | --------------------- | ---------------------------------------------------------------- |
  | **Browsers**          | Composition of events by web browser                             |
  | **Client types**      | Composition of events by client SDK platform                     |
  | **Client versions**   | Composition of events by specific client SDK version             |
  | **Countries**         | Composition of events by originating country                     |
  | **Operating systems** | Composition of events by originating operating system            |
  | **URLs**              | Composition of events by specific URL where events were recorded |
</Expandable>

Each breakdown has two display controls:

* **Count** or **Percent** switches between absolute event volume and percentage share. Browsers, client types, countries, and operating systems open in **Percent**, client versions and URLs open in **Count**.
* The chart and table icons switch between the stacked chart and a table of the same data. Tables for browsers, countries, and operating systems show an icon for each entry.

The **distribution lists** (3) display top lists of observed entities sorted by number of events associated with each entity.

<Expandable title="available distribution lists">
  | Distribution list         | Description                                      |
  | ------------------------- | ------------------------------------------------ |
  | **Top browsers**          | List of web browsers                             |
  | **Top client types**      | List of client SDK platforms                     |
  | **Top client versions**   | List of specific client SDK versions             |
  | **Top countries**         | List of originating countries                    |
  | **Top operating systems** | List of originating operating systems            |
  | **Top origins**           | List of origin domains or mobile app identifiers |
  | **Top URLs**              | List of specific URLs where events were recorded |
</Expandable>

<Info>
  You can view statistics for up to the past 12 months.
</Info>

## Identification Events

The Identification page lists all recent identification events, allows you to find specific events, and dive deep into their details. The page also features a date range filter, and a wide array of other filtering options.

You can access the Identification page by visiting **Dashboard** > [**Identification**](https://dashboard.fingerprint.com/events).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 45 26@2x" />
</Frame>

The page can be filtered by a very large number of **available filters**.

<Expandable title="identification filters">
  | Filter          | Description                                                                              |
  | --------------- | ---------------------------------------------------------------------------------------- |
  | **Event ID**    | Navigate to an event with specific ID                                                    |
  | **Visitor ID**  | Find events reported with a specific visitor ID                                          |
  | **Linked ID**   | Find events reported with a specific linked ID                                           |
  | **Environment** | Find events associated with a specific environment                                       |
  | **Client SDK**  | Find events reported from a specific SDK platform or version                             |
  | **IP address**  | Find events coming from a specific IP address, or an IP address matching a CIDR notation |
  | **URL**         | Find events reported from the specific URL or mobile app package identifier              |
  | **0rigin**      | Find events reported from a specific domain or mobile app package identifier             |
</Expandable>

<Expandable title="Smart Signal filters">
  | Smart Signal filter          | Description                                                                    |
  | ---------------------------- | ------------------------------------------------------------------------------ |
  | **Suspect score**            | Find events with a suspect score greater than provided value                   |
  | **IP blocklist**             | Find events coming from IP addresses that were found in blocklists             |
  | **Residential proxy**        | Find events coming from IP addresses that were detected as residential proxy   |
  | **Man-in-the-middle attack** | Find events where a request to Fingerprint was intercepted and modified        |
  | **Bot detection**            | Find events that were detected as bots - good bots or bad bots                 |
  | **Incognito**                | Find events where incognito (or private mode) was detected                     |
  | **VPN**                      | Find events that were reported behind a VPN                                    |
  | **Browser tampering**        | Find events where browser tampering was detected                               |
  | **Virtual machine**          | Find events where the browser was detected as running inside a virtual machine |
  | **Privacy settings**         | Find events where the browser has privacy settings turned on                   |
  | **Developer tools**          | Find events where developer tools were open in the browser                     |
  | **Jailbroken device**        | Find events coming from a jailbroken iOS device                                |
  | **Emulator**                 | Find events coming from an Android emulator                                    |
  | **Rooted device**            | Find events coming from a rooted Android device                                |
  | **Cloned app**               | Find events coming from a cloned app                                           |
  | **Frida**                    | Find events coming from an app modified by a Frida toolkit                     |
  | **Location spoofing**        | Find events coming from a mobile device where location was spoofed             |
</Expandable>

<Info>
  You can view identification events for up to the past 3 months.
</Info>

## Event details page

Clicking on an event on the Identification page opens the **Event Details** view, which provides thorough information about that specific request.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 46 02@2x" />
</Frame>

On the page you can find:

1. **Device and visitor information**: basic details about the device, client, browser, operating system, and Visitor ID
2. **Location**: includes the IP address and a visual map of the approximate location
3. **Suspect Score**: displays the score and indicates if it is considered low, medium, or high compared to recent traffic
4. **Smart Signal details**: details for all detected Smart Signals, including velocity signals
5. **JSON view**: explore the entire event by looking through the JSON payload
6. **Visitor history**: allows you to see all events detected from that single Visitor ID, which is a convenient way to find recurring patterns or similar events

## Smart Signals Page

The Smart Signals page focuses on providing statistics for [**Smart Signals**](/docs/smart-signals-introduction), which are identifiers that give you actionable device intelligence for browsers and devices interacting with your application.

You can access the Smart Signals page by visiting **Dashboard** > [**Smart Signals**](https://dashboard.fingerprint.com/smart-signals).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 46 33@2x" />
</Frame>

The page features a **list of Smart Signals** (1) and the number of events where each signal was detected for the selected time period.

On the **timeline chart** (2), you can plot the selected signal over time, allowing you to compare the trend with previous period.

This page also includes a date range filter, and an environment filter (3).

**Bots and AI agents**

Bot statistics have their own section of the Dashboard. Go to **Dashboard** > [**Bots & AI agents**](https://dashboard.fingerprint.com/bot-detection) to break your bot traffic down by category, provider, and identity, and to investigate individual automation events.

See [Bots and AI agents](/docs/dashboard-bots-ai-agents) for a guide to those pages, or learn more about [bot detection](/docs/bot-detection/overview).

## CSV export

On the Identification page, you can **export** identification events into a **CSV file** for use in your own analysis, or integration with external fraud prevention systems.

To get CSV export of your data, visit **Dashboard** > [**Identification**](https://dashboard.fingerprint.com/events), and click on **Export** (1).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 48 56@2x" />
</Frame>

You can filter up to 3 months of data, and any applied filters will also apply on the CSV file. The data provided in the CSV matches the data from the [Server API payload](/reference/server-api-get-event), and available columns are determined by your billing plan.

<Expandable title="CSV columns">
  * event\_id
  * timestamp
  * replayed
  * identification.visitor\_id
  * identification.visitor\_found
  * identification.confidence.score
  * identification.confidence.version
  * identification.first\_seen\_at
  * identification.last\_seen\_at
  * environment\_id
  * sdk.platform
  * sdk.version
  * linked\_id
  * tags
  * url
  * ip\_address
  * user\_agent
  * client\_referrer
  * browser\_details.browser\_name
  * browser\_details.browser\_major\_version
  * browser\_details.browser\_full\_version
  * browser\_details.os
  * browser\_details.os\_version
  * browser\_details.device
  * bot
  * developer\_tools
  * ip\_blocklist.email\_spam
  * ip\_blocklist.attack\_source
  * ip\_blocklist.tor\_node
  * ip\_info.address
  * ip\_info.geolocation.accuracy\_radius
  * ip\_info.geolocation.latitude
  * ip\_info.geolocation.longitude
  * ip\_info.geolocation.postal\_code
  * ip\_info.geolocation.timezone
  * ip\_info.geolocation.city\_name
  * ip\_info.geolocation.country\_code
  * ip\_info.geolocation.country\_name
  * ip\_info.geolocation.continent\_code
  * ip\_info.geolocation.continent\_name
  * ip\_info.geolocation.subdivisions.0.iso\_code
  * ip\_info.geolocation.subdivisions.0.name
  * ip\_info.asn
  * ip\_info.asn\_name
  * ip\_info.asn\_network
  * ip\_info.asn\_type
  * ip\_info.datacenter\_result
  * ip\_info.datacenter\_name
  * proximity\_id
  * proximity\_confidence
  * proximity\_precision\_radius
  * proxy
  * proxy\_confidence
  * proxy\_details.proxy\_type
  * incognito
  * privacy\_settings
  * suspect\_score
  * tampering
  * tampering\_details.anomaly\_score
  * tampering\_details.anti\_detect\_browser
  * velocity.distinct\_ip.5\_minutes
  * velocity.distinct\_ip.1\_hour
  * velocity.distinct\_ip.24\_hours
  * velocity.distinct\_country.5\_minutes
  * velocity.distinct\_country.1\_hour
  * velocity.distinct\_country.24\_hours
  * velocity.events.5\_minutes
  * velocity.events.1\_hour
  * velocity.events.24\_hours
  * velocity.ip\_events.5\_minutes
  * velocity.ip\_events.1\_hour
  * velocity.ip\_events.24\_hours
  * velocity.distinct\_linked\_id.5\_minutes
  * velocity.distinct\_linked\_id.1\_hour
  * velocity.distinct\_linked\_id.24\_hours
  * velocity.distinct\_ip\_by\_linked\_id.5\_minutes
  * velocity.distinct\_ip\_by\_linked\_id.1\_hour
  * velocity.distinct\_ip\_by\_linked\_id.24\_hours
  * velocity.distinct\_visitor\_id\_by\_linked\_id.5\_minutes
  * velocity.distinct\_visitor\_id\_by\_linked\_id.1\_hour
  * velocity.distinct\_visitor\_id\_by\_linked\_id.24\_hours
  * virtual\_machine
  * vpn
  * vpn\_confidence
  * vpn\_origin\_timezone
  * vpn\_origin\_country
  * vpn\_methods.timezone\_mismatch
  * vpn\_methods.public\_vpn
  * vpn\_methods.auxiliary\_mobile
  * vpn\_methods.os\_mismatch
  * vpn\_methods.relay
  * high\_activity\_device
  * root\_apps
  * emulator
  * cloned\_app
  * factory\_reset.time
  * factory\_reset.timestamp
  * jailbroken
  * frida
  * location\_spoofing
  * mitm\_attack
  * remote\_control
  * simulator
  * raw\_device\_attributes
</Expandable>

***

[Using the Dashboard](/docs/using-the-dashboard)


# Android API call allowance
Source: https://docs.fingerprint.com/docs/android-api-call-allowance

Prevent fraud in your Android apps for free with Fingerprint device intelligence.

Free and Pro Plus plans receive 500,000 complimentary Android API calls per month. These API calls apply when using our [Android SDK](/docs/android-sdk), [React Native](/docs/fingerprintjs-pro-react-native), or [Flutter](/docs/flutter) SDKs within an Android app.

## How can I get access to the Android API call allowance?

New customers can start with our [unlimited 14-day free trial](https://dashboard.fingerprint.com/signup).\
When the trial ends, your workspace will default to the Free plan unless you upgrade to Pro Plus. Either way, the 500,000 Android allowance is automatically added to the workspace.

Existing customers with a Pro Plus workspace will automatically have the allowance added at the **start of their next billing cycle**. It will automatically be added to the first or oldest Pro Plus workspace on the account.

## What are the limitations?

* The Android API call allowance is limited to 500,000 Android API calls per billing cycle.
  * **Pro Plus plan** – continue usage past 500,000 at a rate of \$4 per additional 1,000 API calls.
  * **Free plan** – Android calls are restricted after 500,000 until the next billing cycle.
* The allowance is limited to 1 workspace per account.

## Frequently Asked Questions

### Is the Android API call allowance a permanent or limited-time offer?

Accounts created during the offer will retain this free usage cap permanently.

### How will it work if I have API calls on both Android and iOS?

Billing will be separated by platform and billed accordingly, API calls from other platforms will count towards the original plan’s usage.

For more details on how identification API requests are billed, please refer to our [documentation](/docs/billing#identification-api-request-as-a-billing-unit).

### What happens if I exceed 500K Android API calls?

As your workspace nears the 500,000 Android API call limit, you will be alerted and prompted to upgrade to our [Enterprise plan](https://fingerprint.com/pricing/).

Upon reaching the 500,000 limit within the billing cycle, Pro Plus customers can continue usage at a rate of \$4 per additional 1,000 API calls.

For Free subscriptions that reach the limit during the billing cycle, we will restrict Android API calls for the remainder of the billing cycle.

### Is support included with the Android API call allowance?

Accounts receive access to our best-in-class developer documentation anytime, along with dedicated support available 8 hours a day, 5 days a week.

### Is 500K free Android API calls a limit per app, email, domain, or company?

The API call limit applies per company. Only one workspace from each account is eligible for the offer.

### Where can I check the free API usage?

API call usage will be available on the [Plan](https://dashboard.fingerprint.com/plan/)  page, with a breakdown by platform.

### I’m on the legacy Pro plan. Do I get the 500K Android API calls?

Yes. Legacy Pro plan customers will also receive 500,000 complimentary Android API calls per month. This allowance will be automatically added at the start of your next billing cycle and applies to one workspace per account. After the 500,000 API call limit is exceeded within a billing cycle, additional Android usage will be billed at a rate of \$2 per additional 1,000 API calls.


# Android Quickstart
Source: https://docs.fingerprint.com/docs/android-quickstart

Get started using the Android SDK

## Overview

In this quickstart, you'll add Fingerprint to a new Android Studio project and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend mobile integration. You'll install the [Fingerprint Android SDK](/docs/android-sdk) and initialize the client agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [Android Studio](https://developer.android.com/studio) installed (latest stable version recommended)
* Basic knowledge of [Kotlin](https://kotlinlang.org/docs/kotlin-tour-welcome.html) and [Android development](https://developer.android.com/courses/android-basics-compose/course)

<Note>
  This quickstart
  only covers the
  **frontend
  setup**. You'll
  need a [backend
  server](/reference/server-sdks)
  to receive and
  process the device
  identification
  event to enable
  fraud detection.
  Check out one of
  the [backend
  quickstarts](/docs/server-quickstarts-overview)
  after completing
  this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the client agent.

## 2. Set up your project

To get started, create a new Android Studio project. If you already have a project you want to use, you can skip to the next section.

1. Open **Android Studio** and choose **New Project**.
2. Select **Empty Activity**, then click **Next**.
3. Name your project (for example, "Fingerprint Quickstart").
4. Keep the default settings (as of this writing, that's **API 24 ("Nougat"; Android 7.0)** as the minimum SDK and **Kotlin DSL** as the build configuration language).
5. Click **Finish**.

Android Studio will generate a basic project for you. Once the project is ready, you'll add the Fingerprint client agent.

## 3. Install the client agent

To integrate Fingerprint into your Android app, first add the Fingerprint Android SDK to your project.

### Add the Fingerprint Maven repository

1. In Android Studio, make sure you're in **Android** view (top-left dropdown in the <Icon icon="folder" /> **Project** pane). Note you may need to wait for your project to finish setting up to see the **Android** view.
2. Expand the **Gradle Scripts** section and open `settings.gradle.kts (Project Settings)`.
3. Find the `dependencyResolutionManagement` block and update the repositories section to include the Fingerprint Maven repository:

```kotlin settings.gradle.kts theme={"theme":"github-dark-dimmed"}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.fpregistry.io/releases") } // [!code ++]
    }
}
```

### Add the SDK dependency

1. In the same **Gradle Scripts** section, open `build.gradle.kts (Module: app)`.
2. Inside the `dependencies` block, add:

```kotlin build.gradle.kts theme={"theme":"github-dark-dimmed"}
implementation("com.fingerprint.android:sdk:4.1.0")
```

### Sync your project

After editing the files, sync your project by either:

* Clicking **Sync Now** in the banner that appears.
* Or going to **File > Sync Project with Gradle Files**.

Once syncing is complete, you're ready to initialize the SDK.

## 4. Initialize the SDK

Now that the SDK is installed, you can import and initialize it in your app.

1. In **Android** view, open `MainActivity.kt` (found in app > kotlin+java > `your.package.name`) and add the following imports:

```kotlin MainActivity.kt theme={"theme":"github-dark-dimmed"}
import com.fingerprint.android.Configuration
import com.fingerprint.android.FingerprintException
import com.fingerprint.android.FingerprintFactory
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
```

2. Additionally, add these imports you'll need for some basic UI:

```kotlin MainActivity.kt theme={"theme":"github-dark-dimmed"}
import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.unit.dp
import androidx.compose.ui.graphics.Color
import android.util.Log
```

3. Next, initialize the client agent before `setContent` in your `onCreate` function:

```kotlin MainActivity.kt theme={"theme":"github-dark-dimmed"}
// ...
enableEdgeToEdge()

val configuration = Configuration( // [!code ++:7]
    apiKey = "PUBLIC_API_KEY",
    region = Configuration.Region.US // Ensure this matches your workspace region
    // For more information, see /docs/regions
)

val fpClient = FingerprintFactory(applicationContext).createInstance(configuration)

setContent {...}
// ...
```

4. Replace `PUBLIC_API_KEY` with your actual public API key from the Fingerprint [dashboard](https://dashboard.fingerprint.com/api-keys).

<Tip>
  For best
  performance,
  consider
  initializing the
  SDK on a
  background thread
  rather than the
  main thread. Class
  loading during
  initialization can
  add overhead, and
  offloading it from
  the main thread
  has been shown to
  reduce latency.
</Tip>

A common pattern is to create the client lazily and run both initialization and identification on `Dispatchers.IO`:

```kotlin theme={"theme":"github-dark-dimmed"}
class FingerprintService(context: Context) {
    val client: Fingerprint by lazy { FingerprintFactory(context).createInstance(configuration) }

    suspend fun fetch(): FingerprintResponse = withContext(Dispatchers.IO) {
        client.getVisitorId()
    }
}

// Usage:
viewModelScope.launch {
    try {
        val response = fingerprintService.fetch()
        // use response.visitorId
    } catch (e: FingerprintException) {
        // handle error
    }
}
```

## 5. Trigger visitor identification

Now that the client agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps a **Create Account** button.

When making the visitor identification request, you will receive the `visitorId` as well as an `eventId`. Instead of using the `visitorId` returned directly on the frontend (which could be tampered with), you’ll send the `eventId` to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) and retrieve the complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

### Add a basic sign-up UI with Compose

1. Create a new composable function for the account creation screen. It will display a simple form with username and password fields, along with a **Create Account** button:

```kotlin MainActivity.kt theme={"theme":"github-dark-dimmed"}
@Composable
fun CreateAccountScreen(
    onSubmit: () -> Unit,
    modifier: Modifier = Modifier
) {
    Column(
        modifier = modifier
            .fillMaxSize()
            .padding(16.dp),
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        val accentColor = Color(0xFFF35B22)

        Text(
            text = "Create account",
            style = MaterialTheme.typography.headlineSmall,
            color = accentColor
        )

        Spacer(modifier = Modifier.height(24.dp))

        var username by remember { mutableStateOf("") }
        var password by remember { mutableStateOf("") }

        OutlinedTextField(
            value = username,
            onValueChange = { username = it },
            label = { Text("Username") },
            modifier = Modifier.fillMaxWidth(),
            colors = OutlinedTextFieldDefaults.colors(
                focusedBorderColor = accentColor,
                unfocusedBorderColor = accentColor,
                cursorColor = accentColor
            )
        )

        Spacer(modifier = Modifier.height(12.dp))

        OutlinedTextField(
            value = password,
            onValueChange = { password = it },
            label = { Text("Password") },
            visualTransformation = PasswordVisualTransformation(),
            modifier = Modifier.fillMaxWidth(),
            colors = OutlinedTextFieldDefaults.colors(
                focusedBorderColor = accentColor,
                unfocusedBorderColor = accentColor,
                cursorColor = accentColor
            )
        )

        Spacer(modifier = Modifier.height(24.dp))

        Button(
            onClick = onSubmit,
            colors = ButtonDefaults.buttonColors(containerColor = accentColor)
        ) {
            Text("Create Account")
        }
    }
}
```

2. Replace the existing call to `Greeting` in your `onCreate` function with the `CreateAccountScreen` composable and pass in a placeholder for the submit function. Be sure to apply the provided `innerPadding` so the content respects system UI insets:

```kotlin MainActivity.kt theme={"theme":"github-dark-dimmed"}
setContent {
    FingerprintQuickstartTheme {
        Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
            CreateAccountScreen( // [!code ++:4]
                onSubmit = { /* TODO: Handle account creation */ },
                modifier = Modifier.padding(innerPadding)
            )
        }
    }
}
```

3. Now replace the placeholder `onSubmit` function with a call to the client agent's `getVisitorId` method. This will capture the device's details and return an `eventId`, which you can then send to your backend for your fraud detection logic:

```kotlin MainActivity.kt theme={"theme":"github-dark-dimmed"}
setContent {
    val scope = rememberCoroutineScope() // [!code ++]

    FingerprintQuickstartTheme {
        Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
            CreateAccountScreen(
                onSubmit = { // [!code ++:11]
                    scope.launch(Dispatchers.IO) {
                        try {
                            val response = fpClient.getVisitorId()
                            Log.d("Fingerprint", "Event ID: ${response.eventId}")
                            // Send this event ID to your backend
                        } catch (e: FingerprintException) {
                            Log.e("Fingerprint", "Error: ${e.error.description}")
                        }
                    }
                },
                modifier = Modifier.padding(innerPadding)
            )
        }
    }
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

This setup ensures you're triggering device identification only when needed.

## 6. Run the app

1. Run <Icon icon="play" /> the app on an emulator or physical device.

   > To learn how to set up Android Studio to [run an emulator](https://developer.android.com/studio/run/emulator) or [connect a physical Android device](https://developer.android.com/studio/run/device#connect), see the official [Android Studio setup guide](https://developer.android.com/studio/run).

2. Type in a username and password and click the **Create Account** button.

3. Open **Logcat** (View > Tool Windows > Logcat) and filter by the Fingerprint tag (`tag:Fingerprint`) to find your log message:

```text Output theme={"theme":"github-dark-dimmed"}
Event ID: 1234566477745.abc1GS
```

You're now successfully identifying the device and capturing the event ID and are ready to send it to your backend for further fraud prevention logic!

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the `eventId` to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information and make decisions.

***

Check out these related resources:

* [Android SDK reference](/docs/android-sdk)
* [Android SDK changelog](/docs/changelog-android-sdk#august-2026)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Android SDK
Source: https://docs.fingerprint.com/docs/android-sdk

A simple guide to integrate Fingerprint's device intelligence platform in your native Android apps.

In this guide, you will learn to

* Include Android SDK in your mobile apps.
* Get a `visitorId`.
* Read the SDK response.
* Enable location data collection (optional; to start getting additional location-based proximity data).
* Configure the SDK as per your needs.
* Specify additional metadata in your identification request.
* Handle errors.

For a complete example of how to use this SDK in your app, please visit the [GitHub repo of our demo app](https://github.com/fingerprintjs/fingerprint-device-intelligence-android-demo). View our [Android quickstart](/docs/android-quickstart) for a step-by-step guide to get started.

## Prerequisites

[Sign up](https://dashboard.fingerprintjs.com/signup) for an account with Fingerprint to get your API key.

## Including the SDK in your app

1. Add the repositories to your **Project Settings** file. Depending on your build configuration language, this file can either be `settings.gradle.kts` or `settings.gradle`.

   <CodeGroup>
     ```kotlin settings.gradle.kts (Kotlin DSL) theme={"theme":"github-dark-dimmed"}
       ...
       dependencyResolutionManagement {
           repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
           repositories {
               google()
               mavenCentral()
               maven { url = uri("https://maven.fpregistry.io/releases") }
           }
       }
     ```

     ```groovy settings.gradle (Groovy DSL) theme={"theme":"github-dark-dimmed"}
       ...
       dependencyResolutionManagement {
           repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
           repositories {
               google()
               mavenCentral()
               maven { url 'https://maven.fpregistry.io/releases' }
           }
       }
     ```
   </CodeGroup>

   Alternatively, if your project is configured to [ignore the repositories declared in the Project Settings](https://docs.gradle.org/current/javadoc/org/gradle/api/initialization/resolve/RepositoriesMode.html) file, you can add the repositories to the **project-level** build file. Depending on your build configuration language, this file can either be `build.gradle.kts` or `build.gradle`.

   <CodeGroup>
     ```kotlin build.gradle.kts (Kotlin DSL) theme={"theme":"github-dark-dimmed"}
       allprojects {
           repositories {
               google()
               mavenCentral()
               maven { url = uri("https://maven.fpregistry.io/releases") }
           }
       }
     ```

     ```groovy build.gradle (Groovy DSL) theme={"theme":"github-dark-dimmed"}
       ...
       allprojects {
           repositories {
               google()
             	mavenCentral()
               maven { url 'https://maven.fpregistry.io/releases' }
           }
       }
     ```
   </CodeGroup>

2. Add the dependencies to your **module-level** build file. Depending on your build configuration language, this file can either be `build.gradle.kts` or `build.gradle`.

   <CodeGroup>
     ```kotlin build.gradle.kts (Kotlin DSL) theme={"theme":"github-dark-dimmed"}
     dependencies {
         implementation("com.fingerprint.android:sdk:4.1.0")
     }
     ```

     ```groovy build.gradle (Groovy DSL) theme={"theme":"github-dark-dimmed"}
      dependencies {
        implementation "com.fingerprint.android:sdk:4.1.0"
      }
     ```
   </CodeGroup>

3. Perform a Gradle sync to update all the dependencies.

## Getting a `visitorId`

To get a `visitorId`, you need the public API key that you obtained when signing up for an account with Fingerprint. You can find this API key in the **Dashboard** > [**API Keys**](https://dashboard.fingerprint.com/api-keys).

Here is an example that shows you how to get a `visitorId`:

<CodeGroup>
  ```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
  val factory = FingerprintFactory(applicationContext)
  val configuration = Configuration(apiKey = "PUBLIC_API_KEY")
  val fpClient = factory.createInstance(configuration)

  scope.launch(Dispatchers.IO) {
      try {
          val response = fpClient.getVisitorId()
          val visitorId = response.visitorId
      } catch (e: FingerprintException) {
          // Handle error
      }
  }
  ```

  ```java Java theme={"theme":"github-dark-dimmed"}
  FingerprintFactory factory = new FingerprintFactory(getApplicationContext());
  Configuration configuration = new Configuration("PUBLIC_API_KEY");
  Fingerprint fpClient = factory.createInstance(configuration);

  fpClient.getVisitorId(
      response -> {
          String visitorId = response.getVisitorId();
          return null;
      },
      error -> {
          // Handle error
          return null;
      }
  );
  ```
</CodeGroup>

<Note>
  The `getVisitorId()` suspend functions perform blocking I/O and should be called from a background
  dispatcher such as `Dispatchers.IO`. Cancelling the coroutine does not cancel the underlying
  signal collection or network request. The coroutine API is Kotlin-only; Java users should use the
  callback-based API.
</Note>

### Specifying a custom timeout

**Default timeout value:** `null`

The identification requests made from an Android SDK do not have a default timeout.

You can use `timeoutMillis` to provide a custom timeout value of your choice. If the `getVisitorId()` call does not complete within the specified timeout, you will receive a `ClientTimeout` error.

Here is an example that shows you how to specify a custom timeout:

<CodeGroup>
  ```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
  scope.launch(Dispatchers.IO) {
      try {
          // Get a visitor ID, will timeout after 5s
          val response = fpClient.getVisitorId(
              timeoutMillis = 5_000
          )
          val visitorId = response.visitorId
      } catch (e: FingerprintException) {
          if (e.error is ClientTimeout) {
              // Handle timeout
          }
      }
  }
  ```

  ```java Java theme={"theme":"github-dark-dimmed"}
  fpClient.getVisitorId(
    // Pass a timeout value of 5 seconds
    5000,
    visitorIdResponse -> {
      // Get a 'visitorId', will timeout after 5s
      visitorId = visitorIdResponse.getVisitorId();
      return null;
    }
  );
  ```
</CodeGroup>

## Using Location Data for Proximity Detection

<Note>
  This is optional. Enable this only if you want to include the additional location-based [proximity detection](/docs/smart-signals-reference#proximity-detection) signal in your response.
</Note>

Starting with [Android SDK 2.10.0](/docs/changelog-android-sdk#v2-10-0), you can receive additional location-based signals (proximity ID, confidence, precision radius) by enabling [`allowUseOfLocationData`](#allowuseoflocationdata) and declaring the corresponding [location permissions](/docs/android-sdk#location-permissions).

### Location permissions

#### Declaring permissions

To calculate [Proximity ID](https://docs.fingerprint.com/docs/smart-signals-reference#proximity-detection) and related data (confidence score, precision radius), Fingerprint needs the following location permissions in the manifest:

<CodeGroup>
  ```xml XML theme={"theme":"github-dark-dimmed"}
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  ```
</CodeGroup>

At least coarse location permission is required. Please note that accuracy will be lower without fine location permission.

#### Asking for permissions

Your app is responsible for asking for permissions. Refer to [Android documentation](https://developer.android.com/training/permissions/requesting) or refer to the [Fingerprint demo app](https://github.com/fingerprintjs/fingerprint-device-intelligence-android-demo) if you need to implement this flow. If you already have this process set up, skip to the next section.

### Enabling location collection

Fingerprint can only collect location data if [`allowUseOfLocationData`](#allowuseoflocationdata) is set to `true`. Optionally, you can control the timeout by setting [`locationTimeoutMillis`](#locationtimeoutmillis) to the desired value. Note that the value is 5 seconds by default.

<Note>
  Timeout Recommendation:
  Because location accuracy and performance can vary based on user settings, device models, and use cases, **we do not enforce a fixed default timeout.** We recommend that you explicitly configure a timeout value that aligns with the app's user experience and performance expectations.
</Note>

## Reading the response

The function `Fingerprint.getVisitorId()` returns the response in a `FingerprintResponse` object. This object has the following fields, some of which can be empty/invalid when [Sealed Client Results](/docs/sealed-client-results) is enabled for your account.

| Field              | Sealed Client Results is disabled                                                                          | Sealed Client Results is enabled                                                                                                                                         |
| ------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`eventId`**      | String. An identifier that uniquely identifies this particular event to `Fingerprint.getVisitorID()`.      | String. An identifier that uniquely identifies this particular request to `Fingerprint.getVisitorID()`.                                                                  |
| **`visitorId`**    | String. An identifier that uniquely identifies the device.                                                 | N/A                                                                                                                                                                      |
| **`suspectScore`** | Int?. A score estimating the likelihood that a device is associated with fraudulent or malicious activity. | N/A                                                                                                                                                                      |
| **`sealedResult`** | `null`                                                                                                     | String?. An encrypted, binary, Base64-encoded String that contains the same response as you would receive with an [/events API](/reference/server-api-get-event) request |

## Configuring the SDK

Using the [Configuration](/docs/android-sdk#configuration) object, it is possible to configure the SDK as per your requirements. As of now, the following options are supported:

### `region`

**Type:** [Configuration.Region](/docs/android-sdk#configuration).

**Default value:** `Configuration.Region.US`

This option allows you to specify a region where you want your data to be stored and processed. This region must be the same as the one you specified when registering your app with Fingerprint. See [region](/reference/js-agent-start-function#region) for more information.

### `endpointUrl`

**Type:** String

**Default value:** `Configuration.Region.US.getEndpointUrl()`

This option allows you to specify a custom endpoint, particularly when you have set up either a custom sub-domain or a proxy integration.

### `fallbackEndpointUrls`

**Type:** List\<String>

**Default value:** emptyList()

This option allows you to specify alternate, fallback endpoints to redirect failed requests.

### `allowUseOfLocationData`

**Type:** Boolean

**Default value:** `false`

This option allows you to enable the location data collection needed to calculate the [location-based proximity detection signal](/docs/smart-signals-reference#proximity-detection).

### `locationTimeoutMillis`

**Type:** Long

**Default value:** `5_000L` (5 seconds)

This option allows you to configure the maximum timeout for location collection (controlled by [`allowUseOfLocationData`](#allowuseoflocationdata)).

The SDK will delay identification up to the specified timeout to collect the device location. If it cannot collect the location information within the specified time, identification continues without location information.

## Specifying `linkedID` and `tags`

Like the [JavaScript agent](/reference/js-agent-get-function#linkedid), the Android SDK also supports providing custom metadata with your identification request. To learn more about this capability, please visit [Linking and tagging information](/docs/tagging-information).

Here is an example that shows you how to associate your identification request with an account ID and additional metadata:

<CodeGroup>
  ```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
  scope.launch(Dispatchers.IO) {
      try {
          val response = fpClient.getVisitorId(
              // Associate additional metadata to this request
              tags = mapOf("orderID" to orderId, "zip" to zipCode),
              // Associate an account number to this request
              linkedId = accountID
          )
          val visitorId = response.visitorId
      } catch (e: FingerprintException) {
          // Handle error
      }
  }
  ```

  ```java Java theme={"theme":"github-dark-dimmed"}
  Map<String, String> tags = new HashMap<>();
  tags.put("orderID", orderId);
  tags.put("zip", zipCode);

  fpClient.getVisitorId(
    // Associate additional metadata to this request
    tags,
    // Associate an account number to this request
    accountId,
    // Get a 'visitorId'
    visitorIdResponse -> {
      // handle visitorId and other data
    },
  );
  ```
</CodeGroup>

The metadata you want to include may not be available when making the identification request. For such scenarios, you can [update that event](/reference/server-api-update-event/) later when the required metadata becomes available. A typical workflow is explained in [`Update linked_id and tags on the server`](/docs/tagging-information#updating-linked_id-and-tags-on-the-server).

## Handling errors

The SDK provides an [Error](/docs/android-sdk#error) class that helps you identify the reasons behind an unsuccessful identification request. Here is an example that shows you how to handle errors in your app:

<CodeGroup>
  ```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
  scope.launch(Dispatchers.IO) {
      try {
          val response = fpClient.getVisitorId()
          val visitorId = response.visitorId
      } catch (e: FingerprintException) {
          when (e.error) {
              is ApiKeyRequired -> {
                  val eventId = e.eventId
                  // Handle error
              }
              is NetworkError -> {
                  // Handle network error
              }
              is ClientTimeout -> {
                  // Handle timeout
              }
              else -> {
                  Log.e("Fingerprint", "${e.eventId}: ${e.error.description}")
              }
          }
      }
  }
  ```

  ```java Java theme={"theme":"github-dark-dimmed"}
  Map<String, String> tags = new HashMap<>();
  tags.put("orderID", orderId);
  tags.put("zip", zipCode);

  fpClient.getVisitorId(
    // Associate additional metadata to this request
    tags,
    // Associate an account number to this request
    accountID,
    // Get a 'visitorId'
    visitorIdResponse -> {
      // Handle visitorId and other data
      String visitorId = visitorIdResponse.getVisitorId();
    	return null;
    },
    // Handle errors
    error -> {
      // Handle errors as per their type
      if (error.getClass() == ApiKeyRequired.class) {
        Log.e(TAG, error.getEventId() + error.getDescription());
    	}
    	return null;
    }
  );
  ```
</CodeGroup>

## Data Classes

### Configuration

<CodeGroup>
  ```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
  public class Configuration @JvmOverloads constructor(
      public val apiKey: String,
      public val region: Region = Region.US,
      public val endpointUrl: String = region.endpointUrl,
      public val fallbackEndpointUrls: List<String> = emptyList(),
      public val integrationInfo: List<Pair<String, String>> = emptyList(),
      public val allowUseOfLocationData: Boolean = false,
      public val locationTimeoutMillis: Long = DEFAULT_LOCATION_TIMEOUT_MILLIS,
  ) {
      public enum class Region(public val endpointUrl: String) {
          US("https://api.fpjs.io"),
          EU("https://eu.api.fpjs.io"),
          AP("https://ap.api.fpjs.io")
      }
  }
  ```
</CodeGroup>

### Error

`Error` is a sealed class representing the reason an identification request failed. Each subtype carries an `eventId` and a `description`.

<CodeGroup>
  ```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
  sealed class Error(
    // The event ID of the identification request
    val eventId: String = UNKNOWN,
    // A self-explanatory description of the error
    val description: String? = UNKNOWN
  )
  ```
</CodeGroup>

#### Server API error codes

These subtypes correspond to error codes returned by the [Server API](/reference/server-api-get-event). Their `description` contains the message returned by the server.

* ApiKeyRequired
* ApiKeyNotFound
* SecretApiKeyRequired
* SecretApiKeyNotFound
* RequestCannotBeParsed
* Failed
* RequestTimeout
* TooManyRequest
* WrongRegion
* SubscriptionNotActive
* InstallationMethodRestricted
* InvalidProxyIntegrationHeaders
* InvalidProxyIntegrationSecret
* ProxyIntegrationSecretEnvironmentMismatch
* VisitorNotFound
* SubscriptionRestricted
* ServiceUnavailable
* FeatureNotEnabled
* RequestNotFound
* StateNotReady
* MissingModule
* PayloadTooLarge
* RulesetNotFound
* EnvironmentRestricted
* SubscriptionNotFound

#### SDK errors

These subtypes are generated by the SDK on the client side and have a fixed `description`.

| Error class               | Description                                              |
| ------------------------- | -------------------------------------------------------- |
| `ResponseCannotBeParsed`  | Null/Invalid Response                                    |
| `NetworkError`            | Network error. Check your connection or the endpoint URL |
| `NetworkUnavailableError` | No network connectivity available.                       |
| `UnknownError`            | Unknown                                                  |
| `ClientTimeout`           | The session timed out                                    |

### FingerprintException

Exception thrown by the coroutine-based `getVisitorId()` suspend functions when an error occurs. Wraps the [`Error`](/docs/android-sdk#error) sealed class and is thrown for use with `try/catch`.

<CodeGroup>
  ```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
  class FingerprintException(
    // The error that caused the exception
    val error: Error
  ) : Exception(error.description) {
    // The event ID associated with this error
    val eventId: String get() = error.eventId
  }
  ```
</CodeGroup>

### Check out these related resources:

* [Android SDK changelog](/docs/changelog-android-sdk#august-2026)
* [Android Quickstart](/docs/android-quickstart)
* [Migrating the Fingerprint Android SDK from v2 to v4](https://docs.fingerprint.com/reference/migrating-android-sdk-from-v2-to-v4)


# Angular SDK
Source: https://docs.fingerprint.com/docs/angular



The [Fingerprint Angular SDK](https://github.com/fingerprintjs/angular) integrates Fingerprint into Angular applications. It supports all capabilities of the JavaScript agent including a built-in [caching mechanism](/reference/js-agent-start-function#cache). See the [Angular quickstart](/docs/angular-quickstart) for a step-by-step guide to get started.

### How to install

Add `@fingerprint/angular` as a dependency to your application via npm, yarn or pnpm.

<CodeGroup>
  ```shell NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/angular
  ```

  ```shell Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/angular
  ```

  ```shell PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/angular
  ```
</CodeGroup>

Add `provideFingerprint` to your application's providers. You need to specify your public API key and other configuration options based on your chosen region and active integration.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
// src/app/app.config.ts
// ...other imports
import { provideFingerprint } from '@fingerprint/angular'

export const appConfig: ApplicationConfig = {
  providers: [
    // ...other config options
    provideFingerprint({
      startOptions: {
        apiKey: 'PUBLIC_API_KEY',
        endpoints: 'https://metrics.yourwebsite.com',
        // region: "eu"
      },
    }),
  ],
}
```

Inject the `FingerprintService` in your component's constructor. Now you can identify visitors using the `getVisitorData()` method from the service.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
// src/app/home/home.component.ts
import { Component } from '@angular/core'
import { FingerprintService, Fingerprint } from '@fingerprint/angular'

@Component({
  selector: 'app-home',
  template: `
    <div>
      <button (click)="onIdentifyButtonClick()">Identify</button>
      <p>VisitorId: {{ visitorId }}</p>
    </div>
  `,
})
export class HomeComponent {
  constructor(
    private fingerprintService: FingerprintService
  ) {}

  visitorId?: string = 'Press "Identify" button to get visitorId'
  result: null | Fingerprint.GetResult = null

  async onIdentifyButtonClick(): Promise<void> {
    const data = await this.fingerprintService.getVisitorData()
    this.visitorId = data.visitor_id
    this.result = data
  }
}
```

### Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/angular). The repository also contains [an example app](https://github.com/fingerprintjs/angular/tree/main/src) demonstrating the usage of the library.

### Migration guide for Angular SDK v3.0.0

Version 3.0.0 of the Angular SDK switches from JavaScript agent v3 to [JavaScript agent v4](/reference/migrating-from-v3-to-v4).

1. Install a new version of the package:

<CodeGroup>
  ```bash NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/angular
  ```

  ```bash Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/angular
  ```

  ```bash PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/angular
  ```
</CodeGroup>

2. Update your module import and configuration:

The default caching strategy has changed from `sessionStorage` caching to **no caching by default**, aligned with the underlying [JavaScript agent v4 default](/reference/js-agent-start-function#cache). To preserve the previous behavior, explicitly configure caching in the module options (see example below).

```typescript Change module imports and configuration theme={"theme":"github-dark-dimmed"}
// [!code --:4]
import {
  FingerprintjsProAngularModule,
  FingerprintJSPro
} from '@fingerprintjs/fingerprintjs-pro-angular'
import { provideFingerprint } from '@fingerprint/angular' // [!code ++]

// [!code --:13]
FingerprintjsProAngularModule.forRoot({
  loadOptions: {
    apiKey: 'PUBLIC_API_KEY',
    endpoint: [
      'https://metrics.yourwebsite.com',
      FingerprintJSPro.defaultEndpoint
    ],
    scriptUrlPattern: [
      'https://metrics.yourwebsite.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js',
      FingerprintJSPro.defaultScriptUrlPattern
    ],
  },
})
// [!code ++:10]
provideFingerprint({
  startOptions: {
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://metrics.yourwebsite.com',
    cache: {
      storage: 'sessionStorage',
      duration: 3600,
    },
  },
})
```

3. Update service usage and result field names:

```typescript Update service usage theme={"theme":"github-dark-dimmed"}
// [!code --:5]
import {
  FingerprintjsProAngularService,
  ExtendedGetResult,
  GetResult,
} from '@fingerprintjs/fingerprintjs-pro-angular'
import { FingerprintService } from '@fingerprint/angular' // [!code ++]

// Update constructor injection
constructor(private fingerprintService: FingerprintjsProAngularService) {} // [!code --]
constructor(private fingerprintService: FingerprintService) {} // [!code ++]

// [!code --:2]
const { visitorId, requestId } = await this.fingerprintService.getVisitorData()
console.log(visitorId, requestId)
// [!code ++:2]
const { visitor_id, event_id } = await this.fingerprintService.getVisitorData()
console.log(visitor_id, event_id)
```

The v4 agent uses snake\_case field names. `requestId` is now `event_id`, and `visitorId` is now `visitor_id`. The `clearCache()` method has been removed from the service - if you need to clear the cache, interact directly with the storage you configured.


# Angular Quickstart
Source: https://docs.fingerprint.com/docs/angular-quickstart

Get started using the Angular SDK

## Overview

In this quickstart, you'll add Fingerprint to a new [Angular](https://angular.dev/) v21 project and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend integration. You'll install the [Fingerprint Angular SDK](/docs/angular) and initialize the JavaScript agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [**Node.js**](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of [**Angular**](https://angular.dev/tutorials/learn-angular) and JavaScript/TypeScript

<Note>
  This quickstart
  only covers the
  **frontend
  setup**. You'll
  need a [backend
  server](/reference/server-sdks)
  to receive and
  process the device
  identification
  event to enable
  fraud detection.
  Check out one of
  the [backend
  quickstarts](/docs/server-quickstarts-overview)
  after completing
  this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the JavaScript agent.

## 2. Set up your project

To get started, create a new Angular project. If you already have a project you want to use, you can skip to the next section.

1. Install the Angular CLI:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install -g @angular/cli
```

2. Create a new project:

```bash Terminal theme={"theme":"github-dark-dimmed"}
ng new fingerprint-angular-quickstart
```

You will be presented with some configuration options for your project. Use the arrow and enter keys to navigate and select which options you desire. If you don't have any preferences, just hit the enter key to take the default options and continue with the setup.

After you select the configuration options and the CLI runs through the setup, you should see the following message:

```bash Terminal theme={"theme":"github-dark-dimmed"}
✔ Packages installed successfully.
 Successfully initialized git.
```

3. Change into the project folder:

```bash Terminal theme={"theme":"github-dark-dimmed"}
cd fingerprint-angular-quickstart
```

4. Open the `fingerprint-angular-quickstart` folder in your code editor and you're ready to go! To run your project, run:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm start
```

5. In your browser, go to [http://localhost:4200](http://localhost:4200), and you should see the Angular welcome page. The application will automatically reload whenever you modify any of the source files.

## 3. Set up your account creation form

1. Before hooking up Fingerprint, create a new component at `src/app/create-account-form/create-account-form.component.ts` with the following:

```angular-ts src/app/create-account-form/create-account-form.component.ts theme={"theme":"github-dark-dimmed"}
import { Component, signal} from '@angular/core';
import { FormsModule } from '@angular/forms';

@Component({
  selector: 'app-create-account-form',
  imports: [FormsModule],
  template: `<div class="wrapper">
  <h1>Create an account</h1>

  <div class="input-group">
    <label for="username">Username</label>
    <input
      id="username"
      type="text"
      placeholder="Username"
      [(ngModel)]="username"
      required
    />
  </div>
  <div class="input-group">
    <label for="password">Password</label>
    <input
      id="password"
      type="password"
      placeholder="Password"
      [(ngModel)]="password"
      required
    />
  </div>
  <button
    [disabled]="isLoading()"
    type="submit"
    (click)="handleSubmit()"
  >
    {{ isLoading() ? 'Loading...' : 'Create Account' }}
  </button>
</div>`,
  styles: `
    .wrapper {
      display: flex;
      align-items: center;
      flex-direction: column;
      margin-top: 200px;
      font-family: sans-serif;
    }

    .input-group {
      margin-bottom: 1.5rem;
      display: flex;
      flex-direction: column;
    }

    label {
      font-weight: 600;
      margin-bottom: 0.5rem;
      color: #333;
    }

    input[type="text"],
    input[type="password"] {
      padding: 0.75rem 1rem;
      border: 1px solid #ccc;
      border-radius: 6px;
      font-size: 1rem;
      transition: border-color 0.2s ease;
    }

    input:focus {
      border-color: #007bff;
      outline: none;
    }

    button[type='submit'] {
      width: 200px;
      padding: 0.75rem;
      font-size: 1rem;
      font-weight: 600;
      background-color: #e36132;
      color: white;
      border: none;
      border-radius: 6px;
      cursor: pointer;
      transition: background-color 0.2s ease;
    }

    button[type="submit"]:hover:not(:disabled) {
      background-color: #e3531f;
    }

    button[type='submit']:disabled {
      opacity: 0.4;
      cursor: not-allowed;
    }
  `,
})
export class CreateAccountFormComponent {
  isLoading = signal(false);

  username = '';
  password = '';

  // We will populate this in a later step.
  async handleSubmit() {}
}
```

2. Import and add the component to your `App` in `src/app/app.ts`:

```angular-ts src/app/app.ts theme={"theme":"github-dark-dimmed"}
// ... other imports here
import { CreateAccountFormComponent } from './create-account-form/create-account-form.component';

@Component({
  selector: "app-root",
  imports: [CreateAccountFormComponent],
  template: `<main class="main">
    <app-create-account-form />
  </main>`,
})

export class App {
  protected readonly title = signal('fingerprint-angular-quickstart');
}
```

## 4. Install and initialize the JavaScript agent

1. To integrate Fingerprint into your Angular app, first add the Fingerprint Angular SDK via npm:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/angular
```

Note: This quickstart is written for version 3.x of the Fingerprint Angular SDK.

2. Open `src/app/app.config.ts` and add `provideFingerprint` to the `providers` array:

```angular-ts src/app/app.config.ts theme={"theme":"github-dark-dimmed"}
// ... other imports here
import { provideFingerprint } from '@fingerprint/angular';

export const appConfig: ApplicationConfig =
  {
    providers: [
      // ...other config options
      provideFingerprint(
        {
          startOptions:
            {
              apiKey: 'PUBLIC_API_KEY',
              region: 'us',
              // Ensure this matches your workspace region
              // For more information, see https://docs.fingerprint.com/docs/regions
            },
        },
      ),
    ],
  };
```

3. Replace `PUBLIC_API_KEY` with your actual public API key from the [Fingerprint dashboard](https://dashboard.fingerprint.com/api-keys).

*Note: For production, consider using environment variables to configure the API key.*

## 5. Trigger visitor identification

Now that the JavaScript agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps/clicks the **Create Account** button.

When making the visitor identification request, you will receive the `visitor_id` as well as an `event_id`. Instead of using the `visitor_id` returned directly on the frontend (which could be tampered with), you'll send the `event_id` to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. Import `FingerprintService` in `create-account-form.component.ts` and configure it by passing it into the `CreateAccountFormComponent` class `constructor`. This automatically initializes it via `Dependency Injection`:

```angular-ts src/app/create-account-form/create-account-form.component.ts theme={"theme":"github-dark-dimmed"}
import { FingerprintService } from '@fingerprint/angular';

// ... rest of component here
export class CreateAccountFormComponent {
  // ... other properties here

  constructor(private fingerprintService: FingerprintService) {}
}
```

2. Now populate the `handleSubmit` method to trigger identification when the user clicks **Create Account**:

```angular-ts src/app/create-account-form/create-account-form.component.ts theme={"theme":"github-dark-dimmed"}
 async handleSubmit() {
    this.isLoading.set(true);

    try {
      const data = await this.fingerprintService.getVisitorData();

      console.log(`
        Visitor ID: ${data.visitor_id}
        Event ID: ${data.event_id}`);

      // Send the event_id to your server
      // await fetch("/api/create-account", {
      //   method: "POST",
      //   headers: { "Content-Type": "application/json" },
      //   body: JSON.stringify({
      //     username: this.username,
      //     password: this.password,
      //     event_id: data.event_id,
      //   }),
      // });

    } catch (err) {
      console.error('Registration failed', err);
    } finally {
      this.isLoading.set(false);
    }
  }
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

In this function:

* `this.isLoading.set(true)` is used to monitor the process stage for the function call.
* `const data = await this.fingerprintService.getVisitorData();` - This triggers Fingerprint's device identification and returns a `data` object containing the visitor's `visitor_id` and `event_id`, which you can then send to your backend along with the username and password.

## 6. Test the app

1. If your dev server isn't already running, start it with:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm start
```

2. In your browser, go to [http://localhost:4200](http://localhost:4200/) (Angular's default).
3. If you have any ad blockers, turn them off for localhost. View the [documentation](/docs/protecting-the-javascript-agent-from-adblockers) to learn how to protect your Fingerprint implementation from ad blockers in production.
4. Enter a username and password, then click **Create Account**.
5. Open the developer console in your browser, and you should see the visitor ID and event ID in the output:

```text Output theme={"theme":"github-dark-dimmed"}
Visitor ID: kLmvO1y70BHKyTgoNoPq
Event ID: 9171022083823.zox1GS
```

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the `event_id` to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information data and use it to make decisions and prevent fraud.

Check out these related resources:

* [Angular SDK reference](https://github.com/fingerprintjs/angular)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Audit logs
Source: https://docs.fingerprint.com/docs/audit-logs



The Dashboard provides an audit log of changes made to workspace resources: what was changed, by whom, and when. This helps you trace configuration changes, troubleshoot issues, and support compliance reporting.

### Activity overview

The audit log lives on the Activity page in Settings.

To check it out, visit **Dashboard** > **Settings** > [**Activity**](https://dashboard.fingerprint.com/audit-log).

The Activity page is only accessible to team members with the **admin** role.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 45 22@2x" />
</Frame>

Activity is listed in reverse chronological order, grouped by month. Each entry shows:

* **Who** performed the action - a team member or an automated system action.
* **What** was done - the action taken and the resource affected.
* **When** it happened - relative to now.

### Inspecting an event

Click an event to expand it and see the full details:

* **At** - the exact timestamp.
* **Action** - the type of change (Create, Update, Delete, etc.).
* **Resource** - the resource type that was affected (API key, Ruleset, Webhook, Environment, etc.).
* **Performed by** - the user (with email) or system that initiated the change.

### Filtering

To find specific events, use the filters at the top of the Activity page:

* **Search** - full-text search across event descriptions, resource names, and performer names.
* **Resource** - filter by resource type.
* **Performed by** - filter by a specific team member or system source.
* **Date range** - narrow the time window down to a specific window of dates and times.


# Install CloudFront Integration using Terraform
Source: https://docs.fingerprint.com/docs/aws-cloudfront-integration-via-terraform



<Note>
  **Before you start: Read the general CloudFront guide**

  This document only covers deploying the Fingerprint CloudFront proxy integration to your AWS account using Terraform. It assumes you use you have already read the [general AWS CloudFront Proxy Integration v2 guide](/docs/cloudfront-proxy-integration-v2) and completed the following steps:

  * [Step 1](/docs/cloudfront-proxy-integration-v2#step-1-issue-a-proxy-secret): You have issued a proxy secret in the Fingerprint Dashboard (`FPJS_PRE_SHARED_SECRET`).
  * [Step 2](/docs/cloudfront-proxy-integration-v2#step-2-create-path-variable): You have defined a path variable for the integration (`FPJS_BEHAVIOR_PATH`)

  If want to use CloudFormation instead of Terraform to install the integration, see [Install CloudFront integration using CloudFormation](/docs/install-cloudfront-integration-using-cloudformation).
</Note>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).
</Warning>

## Prerequisites

* AWS Account.
* Access to an IAM role in AWS with privileges to manage IAM roles, CloudFront distributions, Secrets Manager, Lambda Functions, and S3 Read Only access.
* Terraform project using the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) with the IAM role described above.
* [Terraform CLI](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli).

## Step 3: Add the Fingerprint Terraform module

Add the Fingerprint CloudFront integration [Terraform module](https://registry.terraform.io/modules/fingerprintjs/fingerprint-cloudfront-proxy-integration/aws/latest) into your Terraform project.

* Use the proxy secret created in Step 1 as `fpjs_shared_secret`.
* Make sure to deploy your integration in the `us-east-1` AWS region.
  * Due to [AWS limitations](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-at-edge-function-restrictions.html#lambda-at-edge-restrictions-region), Lambda functions must be deployed in the `us-east-1` region.
  * The Terraform module pulls the Lambda function source code from an S3 bucket in the `us-east-1` region.
* Make sure your AWS CLI has a policy allowing it to read from S3 buckets, for example [`AmazonS3ReadOnlyAccess`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonS3ReadOnlyAccess.html).

```terraform fingerprint.tf theme={"theme":"github-dark-dimmed"}
module "fingerprint_cloudfront_integration" {
  source = "fingerprintjs/fingerprint-cloudfront-proxy-integration/aws"

  fpjs_shared_secret       = "FPJS_PRE_SHARED_SECRET"
}

provider "aws" {
  // You must deploy the integration in the us-east-1 region
  region = "us-east-1"
}
```

Run `terraform init` to install the module. The Terraform module source code is [available on GitHub](https://github.com/fingerprintjs/terraform-aws-fingerprint-cloudfront-proxy-integration).

You can update the module by running `terraform init -upgrade`. Specify the [version constraint](https://developer.hashicorp.com/terraform/language/modules/syntax#version) according to your needs.

<Note>
  **Note: Proxy secret required**

  Proxied identification requests without a valid proxy secret will result in an authentication error and not receive identification results.
</Note>

## Step 4: Use Terraform module outputs in your CloudFront distribution

In this step, choose between using an existing CloudFront distribution or creating a new one. The module's GitHub repository contains [example projects](https://github.com/fingerprintjs/terraform-aws-fingerprint-cloudfront-proxy-integration?tab=readme-ov-file#examples) for both approaches.

### A) Use an existing CloudFront distribution (recommended)

If your website is already running on CloudFront, you can use the same distribution and domain for the proxy integration. The proxy endpoints will be available on your chosen path such as`yourwebsite.com/random-path/...`

This is the recommended setup. Your website and the proxy function will be same-site, served from the same IP address or IP address range. Having the same or similar IP improves cookie lifetimes in Safari — they will be stored in the browser for up to one year instead of 7 days.

1. Add the following code to the definition of your CloudFront distribution.
2. Replace `FPJS_BEHAVIOR_PATH` with the value you defined in Step 2.

```terraform main.tf theme={"theme":"github-dark-dimmed"}
resource "aws_cloudfront_distribution" "cloudfront_dist" {
  // Your existing CloudFront configuration

  # region Fingerprint CloudFront integration start

  origin {
    domain_name = module.fingerprint_cloudfront_integration.fpjs_origin_name
    origin_id   = module.fingerprint_cloudfront_integration.fpjs_origin_id
    custom_origin_config {
      origin_protocol_policy = "https-only"
      http_port              = 80
      https_port             = 443
      origin_ssl_protocols   = ["TLSv1.2"]
    }
    custom_header {
      name  = "FPJS_SECRET_NAME"
      value = module.fingerprint_cloudfront_integration.fpjs_secret_manager_arn
    }
  }

  ordered_cache_behavior {
    path_pattern = "FPJS_BEHAVIOR_PATH*"

    allowed_methods          = ["GET", "HEAD", "OPTIONS", "PUT", "POST", "PATCH", "DELETE"]
    cached_methods           = ["GET", "HEAD"]
    cache_policy_id          = module.fingerprint_cloudfront_integration.fpjs_cache_policy_id
    origin_request_policy_id = module.fingerprint_cloudfront_integration.fpjs_origin_request_policy_id
    target_origin_id         = module.fingerprint_cloudfront_integration.fpjs_origin_id
    viewer_protocol_policy   = "https-only"
    compress                 = true

    lambda_function_association {
      event_type   = "origin-request"
      lambda_arn   = module.fingerprint_cloudfront_integration.fpjs_proxy_lambda_arn
      include_body = true
    }
  }

  #endregion
}
```

<Info>
  **Multi-segment behavior paths**

  We recommend using **single** behavior path segments for simplicity, but it's possible to use more complex ones if needed.
  For example:

  ```terraform theme={"theme":"github-dark-dimmed"}
  path_pattern = "ore54guier/vbcnkxb654*"
  ```

  However, this requires adjustment of an additional parameter `integration_path_depth` which describes the number of path segments in the behavior path:

  ```terraform main.tf theme={"theme":"github-dark-dimmed"}
  module "fingerprint_cloudfront_integration" {
      source = "fingerprintjs/fingerprint-cloudfront-proxy-integration/aws"

      fpjs_shared_secret       = "FPJS_PRE_SHARED_SECRET"
      // The number of path segments in the behavior path, in this case 2: ore54guier/vbcnkxb654 // [!code ++]
      integration_path_depth = 2 // [!code ++]
  }

  resource "aws_cloudfront_distribution" "cloudfront_dist" {
    // Your existing CloudFront configuration
    ordered_cache_behavior {
      path_pattern = "ore54guier/vbcnkxb654*"
      // The rest of the configuration is the same as above
    }
  }
  ```

  How to count path segments:

  ```
   Segment      Segment
      ↓            ↓
  ore54guier / vbcnkxb654 → 2 path segments
  ```
</Info>

### B) Create a new CloudFront distribution

If your website is not running on CloudFront, you can create a new CloudFront distribution just for the proxy integration and serve it from a subdomain of your website like `metrics.yourwebsite.com`.

This setup limits Safari cookie lifetime to 7 days. Because your website and the Lambda proxy function will likely have [different IP ranges](https://github.com/WebKit/WebKit/pull/5347), Safari will apply the same cookie lifetime cap as for third-party CNAME cloaking. This is still an improvement over third-party cookies getting blocked entirely by Safari. But we recommend serving your website and the proxy integration using the same CloudFront distribution if possible (option A above).

* Add the following code to create a CloudFront distribution with the Fingerprint Terraform module as the default cache behavior.
* Configure the CloudFront distribution (for example `price_class`, `viewer_certificate`, `restrictions`, etc.) according to your needs.

```terraform main.tf theme={"theme":"github-dark-dimmed"}
resource "aws_cloudfront_distribution" "fpjs_cloudfront_distribution" {
  comment = "Fingerprint distribution (created via Terraform)"

  origin {
    domain_name = module.fingerprint_cloudfront_integration.fpjs_origin_name
    origin_id   = module.fingerprint_cloudfront_integration.fpjs_origin_id
    custom_origin_config {
      origin_protocol_policy = "https-only"
      http_port              = 80
      https_port             = 443
      origin_ssl_protocols   = ["TLSv1.2"]
    }
    custom_header {
      name  = "FPJS_SECRET_NAME"
      value = module.fingerprint_cloudfront_integration.fpjs_secret_manager_arn
    }
    # This header is required, since it informs the integration that it's served under the root path
    custom_header {
      name  = "FPJS_INTEGRATION_PATH_DEPTH"
      value = "0"
    }
  }

  enabled = true

  http_version = "http1.1"

  price_class = "PriceClass_100"

  default_cache_behavior {
    allowed_methods          = ["GET", "HEAD", "OPTIONS", "PUT", "POST", "PATCH", "DELETE"]
    cached_methods           = ["GET", "HEAD"]
    cache_policy_id          = module.fingerprint_cloudfront_integration.fpjs_cache_policy_id
    origin_request_policy_id = module.fingerprint_cloudfront_integration.fpjs_origin_request_policy_id
    target_origin_id         = module.fingerprint_cloudfront_integration.fpjs_origin_id
    viewer_protocol_policy   = "https-only"
    compress                 = true

    lambda_function_association {
      event_type   = "origin-request"
      lambda_arn   = module.fingerprint_cloudfront_integration.fpjs_proxy_lambda_arn
      include_body = true
    }
  }

  restrictions {
    geo_restriction {
      restriction_type = "none"
    }
  }

  viewer_certificate {
    cloudfront_default_certificate = true
  }
}
```

#### Creating a subdomain for the new CloudFront distribution

If you use Terraform to manage your DNS records, you can also configure a subdomain for your proxy CloudFront distribution.

```terraform theme={"theme":"github-dark-dimmed"}
resource "aws_cloudfront_distribution" "fpjs_cloudfront_distribution" {
  # Same configuration as above

  viewer_certificate {
    cloudfront_default_certificate = true # [!code --]
    acm_certificate_arn = "<YOUR_SUBDOMAIN_CERTIFICATE_ARN>" # [!code ++]
    ssl_support_method  = "sni-only" # [!code ++]
  }

  aliases = ["metrics.yourwebsite.com"] # [!code ++:10]
}

resource "aws_route53_record" "cloudfront_terraform_new_distribution_record" {
  zone_id = "<DOMAIN_ZONE_ID>"
  name    = "metrics.yourwebsite.com"
  type    = "CNAME"
  ttl     = 300
  records = [aws_cloudfront_distribution.fpjs_cloudfront_distribution.domain_name]
}
```

## Step 5: Apply the Terraform changes

1. Run `terraform plan` to verify the planned configuration changes.
2. Run `terraform apply` to apply the changes.

## Step 6: Configure the client agent

See [the main CloudFront proxy integration guide](/docs/cloudfront-proxy-integration-v2#configure-the-fingerprint-javascript-agent-on-your-client) to configure the JavaScript agent on your website.

## Updating the integration

Unlike the [CloudFormation](/docs/install-cloudfront-integration-using-cloudformation) installation method, the Terraform installation of the CloudFront proxy integration does not include any mechanism for automatic updates.

* The module does not include a Management lambda function or any related resources.
* No need to configure automatic updates in the Fingerprint Dashboard.

To keep your integration up to date, please run `terraform apply` regularly.

<Warning>
  **Update expectations**

  The underlying data contract in the identification logic can change to keep up with browser and device releases. Using the AWS CloudFront Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.
</Warning>

## Defining a permission boundary for the proxy function

If you need to, you can define the proxy function's [permission boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) as an input of the Terraform module.

```terraform theme={"theme":"github-dark-dimmed"}
module "fingerprint_cloudfront_integration" {
  source = "fingerprintjs/fingerprint-cloudfront-proxy-integration/aws"

  fpjs_shared_secret       = "FPJS_PRE_SHARED_SECRET"

  fpjs_proxy_lambda_role_permissions_boundary_arn = "arn:aws:iam::<YOUR_ACCOUNT_ID>:policy/YOUR_POLICY_NAME" # [!code ++]
}
```

Make sure your permissions boundary allows the function to:

* Access the Secret manager secret created for the integration (`secretsmanager:GetSecretValue`)
* Create logs (`logs:CreateLogStream`, `logs:CreateLogGroup`, `logs:PutLogEvents`).

Example permission boundary definition:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "<YOUR_SID_HERE>",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "logs:CreateLogStream",
        "logs:CreateLogGroup",
        "logs:PutLogEvents"
      ],
      "Resource": [
        "arn:aws:secretsmanager:us-east-1:<ACCOUNT_ID>:secret:fingerprint-pro-cloudfront-integration-settings-secret-<ID-SUFFIX>",
        "arn:aws:logs:*:<ACCOUNT_ID>:log-group:*"
      ]
    }
  ]
}
```

## What's next

To learn more about calculating AWS costs and monitoring your CloudFront integration, go back to the [general CloudFront Proxy Integration guide](/docs/cloudfront-proxy-integration-v2#monitoring-and-managing-the-integration).


# Ban Enforcement
Source: https://docs.fingerprint.com/docs/ban-enforcement-use-case-tutorial

Learn how to enforce user bans and prevent banned users from accessing your platform

## Overview

This tutorial covers how to use Fingerprint to enforce bans on your platform by recognizing the same device even when a user changes accounts.

You'll begin with a starter app that shows a simple ticket resale marketplace: a page displaying existing listings and a form to post new ones. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic to detect and block submissions from banned visitors.

By the end, you'll have a sample app that prevents banned users from re-posting listings, even if they change their email address or use a new account.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor:

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `ban-evasion` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Listing page" />

    <Tree.File name="index.js - Front-end logic for listings and admin" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="listings.js - Ban enforcement logic" />

    <Tree.File name="server.js - Serves static files and listings endpoint" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000/) to view the mock ticket listing page from the starter app. Create a few listings using the form at the bottom and they'll appear in the list above. Click **Admin mode** in the top right to simulate admin access, then use **Ban seller** on any listing. This blocks that specific email address from posting again. Try creating another listing with the same email and you'll see it's rejected but simply changing the email will allow the submission to go through.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Post listing**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the listing data. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including bot detection and other Smart Signals.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Post listing** button already has an event handler for submitting the listing details. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the listing to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
submitBtn.addEventListener("click", async () => {
  // ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/listings", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        eventName,
        eventDate,
        venue,
        price,
        ticketCount,
        ticketDescription,
        sellerEmail,
        eventId,
      }),
    });

    const data = await res.json();
    showResult(data.success, data.message);
    if (data.success) getListings();
  } catch (err) {
    console.error("Listing posting failed:", err);
    showResult(false, "Something went wrong.");
  }
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your server-side listing logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file already defines API routes for the app. The `POST /api/listings` route passes the request body to the `postListing` function defined in `server/listings.js`. Because the frontend now sends `eventId` in the payload, that value will be available in the body when `postListing` runs:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/listings", async (req, reply) => {
  const result = await postListing(req.body);
  return reply.send(result);
});
```

2. The `server/listings.js` file contains the logic for handling listing submissions and ban enforcement. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`:

```javascript server/listings.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `postListing` function to extract `eventId` and use it to fetch the full identification event details from Fingerprint so you can log the visitor ID alongside each listing:

```javascript server/listings.js theme={"theme":"github-dark-dimmed"}
export async function postListing(body) {
  const { sellerEmail, eventId } = body;

  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id;

  if (isSellerBanned(sellerEmail)) {
    console.error("Seller is banned:", sellerEmail);
    return { success: false, message: "You are banned from posting listings." };
  }

  const saveResult = saveListing(body);
  return saveResult;
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block suspicious devices

<Note>This optional step uses Smart Signals, which are only available on paid plans.</Note>

A useful optional layer for ban enforcement is the Suspect Score signal. Suspect Score is a weighted representation of all Smart Signals detected during identification and can help surface visitors that show signs of risky or manipulated environments.

While you normally wouldn't block someone solely because they have a high Suspect Score, you might choose to treat these visitors differently — for example, requiring extra verification before allowing them to post a listing, or reviewing their activity more closely.

1. Continuing in the `postListing` function in `server/listings.js`, read the Suspect Score from the `event` object and apply any additional rules you want based on it:

```javascript server/listings.js theme={"theme":"github-dark-dimmed"}
export async function postListing(body) {
  const { sellerEmail, eventId } = body;

  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id;

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, message: "Listing posting failed." };
  }

  if (isSellerBanned(sellerEmail)) {
    console.error("Seller is banned:", sellerEmail);
    return { success: false, message: "You are banned from posting listings." };
  }

  const saveResult = saveListing(body);
  return saveResult;
}
```

## 6. Enforce bans using visitor IDs

Next, use the trusted visitor ID from the `event` object to enforce your ban rules. If a visitor (identified by visitor ID) tries to create a new listing after being banned, reject the submission. In production, you may choose to apply different actions for banned visitors, such as blocking specific actions, requiring additional review, or flagging the account for your trust and safety team.

Note: The starter app includes a SQLite database with some tables already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
listings – Stores ticket listings and the visitor that created them
  id INTEGER PRIMARY KEY AUTOINCREMENT
  eventName TEXT NOT NULL
  eventDate TEXT NOT NULL
  ticketCount INTEGER NOT NULL
  venue TEXT NOT NULL
  sellerEmail TEXT NOT NULL
  price REAL NOT NULL
  ticketDescription TEXT NOT NULL
  visitorId TEXT
  createdAt INTEGER NOT NULL

banned_visitors – Stores banned visitors and their identifiers
  id INTEGER PRIMARY KEY AUTOINCREMENT
  email TEXT
  visitorId TEXT
  bannedAt INTEGER NOT NULL
```

1. First update the existing `saveListing` helper function to store the `visitorId` alongside a new listing:

```javascript server/listings.js theme={"theme":"github-dark-dimmed"}
// Save listing to database
function saveListing(listing) {
  const createdAt = Date.now();
  try {
    db.prepare(
      "INSERT INTO listings (eventName, eventDate, ticketCount, venue, sellerEmail, price, ticketDescription, visitorId, createdAt) VALUES (@eventName, @eventDate, @ticketCount, @venue, @sellerEmail, @price, @ticketDescription, @visitorId, @createdAt)",
    ).run({ ...listing, createdAt });
    return { success: true, message: "Listing saved successfully." };
  } catch (err) {
    // ...
  }
}
```

2. Then update the existing `isSellerBanned` helper function to use the `visitorId` instead of email to check for banned visitors:

```javascript server/listings.js theme={"theme":"github-dark-dimmed"}
// Check if seller is banned
function isSellerBanned(visitorId) {
  const bannedAt = db
    .prepare("SELECT bannedAt FROM banned_visitors WHERE visitorId = ?")
    .get(visitorId);
  return bannedAt ? true : false;
}
```

3. Next update `banSeller` function so it looks up the listing's associated visitor ID instead of email address:

```javascript server/listings.js theme={"theme":"github-dark-dimmed"}
export function banSeller(listingId) {
  const bannedAt = Date.now();
  try {
    const listing = db.prepare("SELECT visitorId FROM listings WHERE id = ?").get(listingId);

    if (!listing) {
      console.error("Listing not found.");
      return { success: false, message: "Listing not found." };
    }

    const visitorId = listing.visitorId;

    db.prepare("INSERT INTO banned_visitors (visitorId, bannedAt) VALUES (?, ?)").run(
      visitorId,
      bannedAt,
    );

    return { success: true, message: "Seller banned successfully." };
  } catch (err) {
    console.error("Failed to ban seller:", err);
    return { success: false, message: "Failed to ban seller: " + err.message };
  }
}
```

4. Finally, update `postListing` to include the `visitorId` when checking if the visitor is banned and when saving new listings:

```javascript server/listings.js theme={"theme":"github-dark-dimmed"}
export async function postListing(body) {
  const { eventId } = body;

  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id;

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, message: "Listing posting failed." };
  }

  if (isSellerBanned(visitorId)) {
    console.error("Seller is banned.");
    return { success: false, message: "You are banned from posting listings." };
  }

  const saveResult = saveListing({ ...body, visitorId });
  return saveResult;
}
```

Together with Suspect Score, this gives you a way to filter out visitors you do not want interacting with your platform. More importantly, logging and enforcing bans by `visitor_id` ensures that a banned visitor cannot return simply by changing their email address. You can expand the logic by adding more Smart Signals, adjusting thresholds, or customizing how bans are applied based on your business rules.

<Info>
  This is a minimal example to show how to implement Fingerprint for ban enforcement. In a real
  application, make sure to implement proper security practices, error checking, and access-control
  flows that align with your production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full ban evasion flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Try posting a listing by filling out the form at the bottom of the page and clicking **Post listing**. You should see a success response and the listing will appear in the list above.
3. Click **Admin mode** in the top right to toggle admin controls, then click **Ban seller** on one of the listings that *you* created.
4. Try to post another listing. The submission will be blocked because Fingerprint recognizes the banned visitor ID
5. Open the page in an incognito window and try posting a new listing. The request is still blocked, since Fingerprint continues to recognize the visitor.

## Next steps

You now have a working ban enforcement flow powered by Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), tailor ban rules to your platform's policies, or build additional protections like rate limits or step-up verification for suspicious visitors.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Overview
Source: https://docs.fingerprint.com/docs/billing

A guide to understanding our API request-based billing and related concepts

## Fingerprint Platform Billing

Customers are billed monthly based on the number of identification API requests made over the billing period. The Fingerprint Platform has three plans: [Free, Pro Plus and Enterprise](https://fingerprint.com/pricing/?utm_source=/docs/quick-start-guide).

> Check out our [Pricing](https://fingerprint.com/pricing/) to learn which plan is best for your needs.

Custom pricing options are available for businesses that require 9,000,000 annual API requests or more. Please reach out to our [Sales team](https://fingerprint.com/contact-sales/).

### Payment Methods

For self-serve plans, Fingerprint supports the following payment methods:

* Credit and debit cards
* Digital wallets, including Apple Pay, Google Pay, Link, Cash App Pay, and Samsung Pay
* Bank transfers
* Bank debits, including ACH Direct Debit and SEPA Direct Debit
* Regional payment methods, including Pay by Bank, Pix, and UPI
* Stablecoins and cryptocurrency

Available payment methods vary by country, currency, device, and other eligibility requirements. The payment options available to you will appear at checkout.

For Enterprise plans, please reach out to our [Sales team](https://fingerprint.com/contact-sales/).

### Identification API request as a billing unit

A billable API request happens when you *successfully* use the Fingerprint client agent to identify a browser or mobile device. Identification requests successfully processed by Fingerprint generate an `event_id` that is returned in the response.

* All identification requests with an assigned event ID are billable.
* Requests that do not generate an event ID are not billed.

The following requests are **billable**:

* Calling the [`get()`](/reference/js-agent-get-function) function of the Fingerprint JavaScript agent.
* Calling the [`getVisitorId()`](/docs/ios-sdk#getting-a-visitorid) function of the iOS SDK.
* Calling the [`getVisitorId()`](/docs/android-sdk#getting-a-visitorid) function of the Android SDK.
* Calling equivalent functions in our [Flutter](/docs/flutter), [React Native](/docs/fingerprintjs-pro-react-native), or [frontend libraries](/docs/frontend-libraries).

The following requests are **not billable**:

* Downloading the client agent (calling the [`start()`](/reference/js-agent-start-function) function) is not billable.
* Requests to [Server API](/reference/server-api) are not billable.
* Requests blocked by ad blockers or application firewalls are generally not billed.
* Failed requests that result in an error without generating an event ID are not billed.
* Throttled identification requests are not billed.
* Requests filtered by [Request Filtering](/docs/request-filtering) are not billed.

If you encounter any billing issues or believe the billing is not working correctly, please reach out to [our support team](https://fingerprint.com/support/) to resolve your issue.

#### How many API calls will I need?

If you're unsure how many API calls you'll need, try these two options:

1. Start with an [unlimited 14-day free trial](https://dashboard.fingerprint.com/signup) to test all Fingerprint products. By the end, you'll know how many API calls you need.
2. If a trial isn’t possible, estimate the number of important actions where you'll use Fingerprint, like logins, account creation, payments, refunds, or return requests.

### Android API Call Allowance

Pro Plus customers receive 500,000 free Android API calls per month. These API calls apply when using our [Android SDK](/docs/android-sdk), [React Native](/docs/fingerprintjs-pro-react-native), or [Flutter](/docs/flutter) SDKs within an Android app. See [more details](/docs/android-api-call-allowance) on the allowance.

### Caching

When your application code retrieves visitor data from the application cache, it is not billed. Only requests that hit the Fingerprint backend are billed. Our [frontend libraries](https://fingerprint.com/sdk-libraries/) for specific web frameworks provide various caching strategies.

The number of billed requests will depend on your selected caching strategy. See [Caching visitor information](/docs/identify-visitors#caching-the-visitor-id) for more details.

### Smart Signals

[Smart Signals](/docs/smart-signals-reference) (for example, Bot Detection, VPN Detection, and more) are available to users on the Pro Plus or Enterprise plans.

### Billing changes

We reserve the right to change the billing model for our current or future products. In the event of an upcoming billing change, we'll send a notification to all our customers with a notification at least 30 days before the billing change event.

### Other Fingerprint platform features

Other Fingerprint platform features, such as [Server API requests](/reference/server-api), [Webhooks](/docs/webhooks), [Custom subdomains](/docs/custom-subdomain-setup), [Request filtering](/docs/request-filtering), [Proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers#cloud-proxy-integrations), [libraries, and SDKs](https://fingerprint.com/sdk-libraries/) are free of charge with certain limitations per account. See below for more details.

## Account limits

All Fingerprint **accounts** are limited to **one unlimited 14-day free trial**. After you sign up, you are automatically enrolled in the free trial and can try the Fingerprint API without limitations. When the trial ends, your workspace will default to the Free plan unless you upgrade to a paid plan. On the Free plan, you can continue using Fingerprint with some limitations.

The following limits apply to all Fingerprint **accounts**:

| Resource     | Default limit | Notes                                                                                                                                                 |
| ------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Team members | 10            | Includes users that signed up and pending invitations. Reach out to [Customer Support](https://fingerprint.com/support/) if you need more user slots. |

All **workspaces** under your account have the following limits:

| Resource              | Default limit                                                                    | Notes                                                                                                                                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Monthly API requests  | **unlimited** (paid plans)                                                       | On the Free plan, monthly API requests are limited to 1,000 for Web and iOS, and 500,000 for Android. Only Identification API requests count towards your monthly plan. Server API requests are free.                           |
| API rate limit        | 5 requests per second ([\*bursts](/docs/billing#rate-limiting-burst-protection)) | Applies to requests made using public keys (Identification API). It is possible to increase the limit on the [Enterprise plan](https://fingerprint.com/pricing/?utm_source=/docs/billing#account-limits) by emailing support.   |
| Server API rate limit | 5 requests per second ([\*bursts](/docs/billing#rate-limiting-burst-protection)) | Applies to requests made using secret keys ([Server API](/reference/server-api)). A separate rate limit applies to the [DELETE API](/reference/server-api-delete-visitor-id).                                                   |
| Visitor history       | 30 days                                                                          | For plans, visit history is available through the Dashboard or the [Server API](/reference/server-api) for the past 30 days. For Enterprise plans, the data is kept for 90 days or longer depending on the enterprise contract. |
| SSL certificates      | 50                                                                               | Limited to 5 certificates on Free and trialing plans.                                                                                                                                                                           |
| Environments          | 2                                                                                | Number of multiple environments you can setup.                                                                                                                                                                                  |
| Management API keys   | 5                                                                                | Number of API keys used to interact with the [Management API]().                                                                                                                                                                |

With support for [multiple environments](/docs/multiple-environments), some limits are applied **per environment**. For resources that are **workspace-scoped**, they take up a slot in every environment.

| Resource                | Default limit | Notes                                                                                                                                                    |
| ----------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public API keys         | 2             | API keys used to make billable [identification requests](/docs/quick-start-guide).                                                                       |
| Secret API keys         | 5             | API keys used to make requests to the [Server API](/reference/server-api). Optionally they can be workspace-scoped.                                      |
| Proxy keys              | 5             | Keys used to authenticate with [proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers). Optionally they can be workspace-scoped.     |
| Encryption keys         | 5             | Keys used to encrypt client payloads to enable [Sealed Client Results](/docs/sealed-client-results).                                                     |
| Request filtering rules | 10            | [Filtering rules](/docs/request-filtering) that are used to filter out unwanted requests. Includes allowed/forbidden origins and forbidden HTTP headers. |
| Webhooks                | 5             | Number of configured [webhooks](/docs/webhooks). Optionally they can be workspace-scoped.                                                                |

<Info>
  ### Increasing Limits

  If you are a customer and want to increase a limit, please reach out to [our support team](https://fingerprint.com/support/).
</Info>

### Rate Limiting - Burst Protection

Short unexpected traffic spikes could normally cause request throttling if the API key exceeded the API Rate Limit. **Burst protection** prevents that by allowing peak traffic to be higher than usual for a short period of time. The allowed burst size (bucket) is always `API Rate Limit * 3` (15 RPS in the default configuration). The burst bucket automatically regenerates every second by `API Rate Limit - RPS` when the current RPS is lower than the `API Rate Limit`.

#### Examples

Real world examples of burst bucket depletion with different RPS values (considering the default `API Rate Limit` value above):

* Burst bucket **never depletes** when RPS is 5
* Burst bucket depletes **in 15 seconds** on 6 RPS
* Burst bucket depletes **in 3 seconds** on 10 RPS
* Burst bucket depletes **in 1 second** on 20 RPS

Whenever the bucket depletes, the service starts dropping requests above `API Rate Limit`.

### How am I protected from overpaying?

Fingerprint offers two types of **surge protection** for all customer accounts. First is DDoS protection, so you won't be charged for API calls during an attack. Second is a web application firewall (WAF), which inspects all incoming requests and blocks harmful or abusive traffic (including certain classes of bot activity).

Each request also goes through a customizable [request filtering](/docs/request-filtering) layer. This lets you block requests from unknown sources, limit API calls to certain web apps, or ignore requests based on HTTP headers.

In rare cases where a malicious surge or implementation issue still causes unexpected usage, you may be eligible for **partial** **bill forgiveness**.

* See our [Spike Troubleshooting guide](/docs/troubleshooting-unexpected-usage-spikes) to diagnose the root cause.
* If you confirm the spike was unintentional or malicious, you can [submit a forgiveness request](https://dashboard.fingerprint.com/settings/billing) through the Billing page on the Fingerprint dashboard.

**Important:** Forgiveness can only be applied to your **most recent completed invoice** (i.e. the last completed billing cycle). Older invoices are not eligible, even if they experienced a spike.

***

[Browser and device support](/docs/browser-and-device-support)


# Browser and device support
Source: https://docs.fingerprint.com/docs/browser-and-device-support

An overview of Fingerprint compatibility across various browsers and devices.

## Browsers

Fingerprint supports all popular browsers. We aim to cover at least 99% of all users according to our Fingerprint Identification statistics. The overall identification accuracy of traffic coming from supported browsers is industry-leading based on all Fingerprint identification statistics. Our research and development team continuously monitors releases of supported browsers and adjusts our identification algorithm if necessary.

At the moment, the supported browsers are:

| Browser                 | Version   | Notes                                                                  |
| ----------------------- | --------- | ---------------------------------------------------------------------- |
| Edge                    | **140+**  |                                                                        |
| Chrome                  | **110+**  |                                                                        |
| Firefox                 | **128+**  |                                                                        |
| Desktop Safari          | **16.0+** | See [below](#safari-intelligent-tracking-prevention) for more details. |
| Mobile Safari           | **16.0+** |                                                                        |
| Mobile Samsung Internet | **29.0+** | See [below](#samsung-internet-browser-support) for more information    |
| Brave                   | **1.48+** | See [below](#brave-browser-support) for more details.                  |

Browsers not listed here may work, but we don't make guarantees about identification functionality or accuracy.

The identification accuracy of individual browsers may vary, and their impact on your overall identification accuracy depends on their prevalence in your traffic. See [Understanding our accuracy](/docs/identification-accuracy-and-confidence) for an explanation of how we measure our accuracy.

### Safari Intelligent Tracking Prevention

Apple Safari has an on-by-default privacy protection feature called [Intelligent Tracking Protection](https://webkit.org/blog/9521/intelligent-tracking-prevention-2-3/), or ITP. ITP has been very effective in preventing cross-site tracking by completely disabling 3rd-party cookies and capping the lifetime of all script-writable website data.

By default, the Fingerprint API uses 3rd party cookies (both client-side set with `document.cookie` and server-side set with the `Set-Cookie` HTTP header) and script-writable website data (localStorage) to more reliably [identify returning visitors](https://fingerprint.com/blog/browser-fingerprinting-techniques/). All of these methods are affected by ITP, lowering identification accuracy. View the methods for [keeping identification accuracy high](#keeping-identification-accuracy-high) to maximize identification accuracy.

### Brave browser support

[Brave](https://brave.com/) is a privacy-focused browser based on Chromium. For our purposes, it behaves similarly to Chrome with a strict ad-blocking extension installed. That means it blocks the agent download and identification requests to Fingerprint CDN and API. View the methods for [keeping identification accuracy high](#keeping-identification-accuracy-high) to ensure your requests are not blocked.

### Samsung Internet browser support

[Samsung Internet](https://play.google.com/store/apps/details?id=com.sec.android.app.sbrowser\&hl=en_US\$0) is a browser optimized for Samsung Galaxy devices, but available for all Androids. Fingerprint only supports the Android version of this browser. iOS, desktop, and TV versions of Samsung browser are not supported.

### Keeping identification accuracy high

Ad-blocking extensions and browser features can disrupt visitor identification. To maintain high identification accuracy even with Safari and Brave, you need to use a [custom subdomain setup](/docs/custom-subdomain-setup) or a cloud proxy integration like [Cloudflare](/docs/cloudflare-integration) or [Cloudfront](/docs/cloudfront-proxy-integration-v2). These methods allow you to route Fingerprint HTTP requests through your domain, preventing browsers from blocking them and making cookies set by Fingerprint considered "first-party." See [Protecting the JavaScript agent from ad-blockers](/docs/protecting-the-javascript-agent-from-adblockers) for more details.

## Mobile devices

Fingerprint supports most iOS and Android devices in circulation today. The overall identification accuracy of traffic coming from mobile devices is even higher than that of browsers, thanks to long-lasting system-level attributes available on mobile platforms.

At the moment, the supported OS versions are:

| OS      | Version                               | Notes                                                                                |
| ------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| Android | 5.0 Lollipop (API Level 21) or higher | See [Android](/docs/native-android-integration#supported-versions) for more details. |
| iOS     | 13+                                   | See [iOS](/docs/ios#supported-versions) for more details.                            |

***

[Regions and data retention](/docs/regions)


# Card Testing
Source: https://docs.fingerprint.com/docs/card-testing-use-case-tutorial

Learn how to detect and prevent credit card testing fraud

## Overview

This tutorial walks through implementing Fingerprint to prevent card testing and card cracking attacks, where fraudsters use bots to rapidly test stolen or generated credit card numbers on an online checkout form to find valid card details.

You'll begin with a starter app that includes a mock checkout page and a basic payment flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to detect and block automated card submissions.

By the end, you'll have a sample app that rejects card-testing bots and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

<Note>
  This tutorial requires the Bot Detection Smart Signal, which is only available on paid plans.
</Note>

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `card-testing` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Checkout page" />

    <Tree.File name="index.js - Front-end logic to handle checkout" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="orders.js - Card testing prevention logic" />

    <Tree.File name="server.js - Serves static files and ordering endpoint" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock checkout page from the starter app. You can test the basic payment form by entering some fake card details and clicking **Place order**.
7. Then try submitting an order using the included headless bot script `test-bot.js`. While the app is running, execute `node test-bot.js` and observe that the automated script successfully submits the order. By default, the server does not distinguish between bots and real users.

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Place order**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the checkout payload. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including bot detection and other signals.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Place order** button already has an event handler for submitting the payment details. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the checkout to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
placeOrderBtn.addEventListener("click", async () => {
	// ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/place-order", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        recipientEmail,
        amount,
        cardNumber,
        cardExp,
        cardCvv,
        eventId,
      }),
    });

	// ...
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your order processing logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and Bot Detection [Smart Signal](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/place-order` route there to also extract `eventId` from the request body and pass it into the `placeOrder` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/place-order", async (req, reply) => {
  const result = await placeOrder(req.body);
  return reply.send(result);
});
```

2. The `server/orders.js` file contains the logic for handling orders. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/orders.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `placeOrder` function to also extract `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/orders.js theme={"theme":"github-dark-dimmed"}
export async function placeOrder(body) {
  const { recipientEmail, amount, cardNumber, cardExp, cardCvv, eventId } = body;

  const event = await fpServerApiClient.getEvent(eventId);

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block card testing bots

Card testing and card cracking attacks rely heavily on automated checkout attempts, so rejecting bots outright can stop the abuse. Fingerprint returns `not_detected` if no bot activity is found, `good` for known bots, like search engines, and `bad` for other automation tools. Any visitor identification that does not return `not_detected` can be blocked from placing orders.

1. Continuing in the `placeOrder` function in `server/orders.js`, check the bot signal returned in the `event` object and block bots:

```javascript server/orders.js theme={"theme":"github-dark-dimmed"}
export async function placeOrder(body) {
  const { recipientEmail, amount, cardNumber, cardExp, cardCvv, eventId } = body;

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, message: "Order failed." };
  }

  // ...
}
```

You can also add [Suspect Score](/docs/suspect-score) as a secondary layer. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload, helping to identify suspicious activity. While you may not normally block checkout attempts based only on a high risk score, you could flag them for review, modify rate-limits, or require additional verification.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the order if it exceeds a chosen threshold (for example, 20):

```javascript server/orders.js theme={"theme":"github-dark-dimmed"}
export async function placeOrder(body) {
  // ...

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, message: "Order failed." };
  }

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, message: "Order failed." };
  }

  // ...
}
```

## 6. Recognize repeat offenders by visitor ID

As a secondary measure, you can log the `visitorId` along with orders to spot suspicious activity. This lets you recognize and block the same device even if they clear cookies, change IPs, or change accounts.

Note: The starter app includes a SQLite database with this table already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
orders – Stores orders and associated visitor IDs
  orderNumber INTEGER PRIMARY KEY AUTOINCREMENT
  visitorId TEXT
  recipientEmail TEXT NOT NULL
  amount REAL NOT NULL
  createdAt INTEGER NOT NULL
```

1. Add a new helper function to the bottom of the `server/orders.js` file to check the number of orders in the last 24 hours for a specific `visitorId`:

```javascript server/orders.js theme={"theme":"github-dark-dimmed"}
// Count visitor's orders placed in the last 24 hours
function countRecentOrders(visitorId) {
  const since = Date.now() - 24 * 60 * 60 * 1000;

  const row = db
    .prepare(
      `SELECT COUNT(*) AS count
       FROM orders
       WHERE visitorId = ? AND createdAt >= ?`,
    )
    .get(visitorId, since);

  return row.count;
}
```

2. Also update the existing `saveOrder` helper function to accept and use the `visitorId`:

```javascript server/orders.js theme={"theme":"github-dark-dimmed"}
// Save the order to the database
function saveOrder({ recipientEmail, amount, visitorId }) {
  db.prepare(
    "INSERT INTO orders (recipientEmail, amount, visitorId, createdAt) VALUES (?, ?, ?, ?)",
  ).run(recipientEmail, amount, visitorId, Date.now());
}
```

3. Update `placeOrder` to retrieve the `visitorId`, and use it check for an unusually high volume of recent orders made by the visitor and when saving the order:

```javascript server/orders.js theme={"theme":"github-dark-dimmed"}
export async function placeOrder(body) {
  // ...

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, message: "Order failed." };
  }

  const visitorId = event.identification.visitor_id;
  if (countRecentOrders(visitorId) >= 5) {
    console.error("Too many orders placed in the last 24 hours.");
    return { success: false, message: "Order failed." };
  }

  // ...

  saveOrder({ recipientEmail, amount, visitorId });

  // ...
}
```

Together with the bot detection Smart Signal, this allows you to protect your checkout and prevent card testing and card cracking attempts. No matter which account is used, you can monitor order velocity and tie activity back to the same browser or device. You can extend it by analyzing additional signals, changing rate limit thresholds, or varying your response based on risk.

<Note>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error checking, and payment and card data handling that
  align with your production standards.
</Note>

## 7. Test your implementation

Now that everything is wired up, you can test the full checkout flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Try placing an order by entering some fake payment details and clicking **Place order**. You should see a success response.
3. If you make five orders, additional attempts from the same device will be blocked based on the recent-order check. Open the page in incognito mode to see that you are still blocked since Fingerprint still recognizes your browser with the same visitor ID.
4. While your demo is running, run the included headless bot test script from the `card-testing` folder. This will attempt to place an order using a headless browser, which will be flagged by the Bot Detection signal and rejected:

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

*Note: If you encounter errors launching the automated browser, make sure you have the testing browser installed:*

```bash Terminal theme={"theme":"github-dark-dimmed"}
npx puppeteer browsers install chrome
```

## Next steps

You now have a working checkout flow that blocks card testing and card cracking attempts with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your business policies, or layer in additional defenses or step-up verification.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Chargeback Dispute
Source: https://docs.fingerprint.com/docs/chargeback-dispute-use-case-tutorial

Learn how to reduce chargebacks and win disputes with device identification data

## Overview

This tutorial covers how to use Fingerprint to strengthen chargeback dispute evidence by linking purchases to a visitor over time, even when a customer claims an unauthorized transaction.

You'll begin with a starter app that includes a simple event ticket storefront where you can make purchases, a personal order history view where you can simulate a chargeback, and a merchant/admin view where you can view purchase details. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic to link purchases together with a visitor identifier to prove a consistent pattern of legitimate activity tied to the same visitor.

By the end, you'll have a sample app that creates a browser-linked purchase history you can reference when a customer disputes a charge, claiming the purchase wasn't made by them (AKA friendly fraud).

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor:

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `chargeback-dispute` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="admin.html - Admin dashboard" />

    <Tree.File name="admin.js - Front-end logic for admin view" />

    <Tree.File name="history.html - Order history and dispute simulator" />

    <Tree.File name="history.js - Front-end logic for history view" />

    <Tree.File name="index.html - Event ticket storefront" />

    <Tree.File name="index.js - Front-end logic for browsing and purchases" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="purchases.js - Purchase and evidence logic" />

    <Tree.File name="server.js - Serves static files and purchase endpoints" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000/) to view the mock events storefront and make a few test purchases, then open your order history page to simulate a chargeback on one of them, and finally switch to the merchant view to inspect the disputed order where you'll see only limited evidence to help you prove the purchase was actually appropriately authorized.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Complete purchase**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the purchase data. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including Smart Signals you can use as evidence during chargeback disputes.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Complete purchase** button already has an event handler for submitting the purchase details. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the purchase to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
purchaseButton.addEventListener("click", async () => {
  // ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/purchases", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        eventName: currentEvent.name,
        ticketQuantity: parseInt(ticketQuantity),
        price: parseFloat(currentEvent.price.replace("$", "")),
        creditCard,
        deliveryEmail,
        eventId,
      }),
    });

    const data = await res.json();
    if (data.success) {
      showResult(true, "Purchase completed successfully!");
    } else {
      showResult(false, data.message || "Failed to complete purchase.");
    }
  } catch (err) {
    console.error("Purchase failed:", err);
    showResult(false, "Something went wrong. Please try again.");
  }
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your server-side purchase logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and any additional Smart Signals you want to store for dispute evidence.

1. In the backend, the `server/server.js` file already defines API routes for the app. The `POST /api/purchases` route passes the request body to the `postPurchase` function defined in `server/purchases.js`. Because the frontend now sends `eventId` in the payload, that value will be available in the body when `postPurchase` runs:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/purchases", async (req, reply) => {
  const result = await postPurchase(req.body);
  return reply.send(result);
});
```

2. The `server/purchases.js` file contains the logic for handling purchase submissions and chargebacks. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`:

```javascript server/purchases.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update your purchase handler function to extract `eventId` and use it to fetch the full identification event details from Fingerprint so you can log the visitor ID alongside each purchase:

```javascript server/purchases.js theme={"theme":"github-dark-dimmed"}
export async function postPurchase(body) {
  const createdAt = Date.now();

  const { eventId } = body;
  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id;

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Link purchase history with visitor IDs

Next, use the trusted visitor ID from the `event` object to link purchases together. Instead of relying only on an account email or IP address, you'll associate each purchase with the visitor ID, so you can later show that the same visitor has a history of legitimate purchases when a chargeback happens.

Note: The starter app includes a SQLite database with a table already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
purchases – Stores completed ticket purchases and the visitor who made them
  id INTEGER PRIMARY KEY AUTOINCREMENT
  eventName TEXT NOT NULL
  ticketQuantity INTEGER NOT NULL
  price REAL NOT NULL
  creditCard TEXT NOT NULL
  deliveryEmail TEXT NOT NULL
  visitorId TEXT
  chargeback INTEGER DEFAULT 0
  createdAt INTEGER NOT NULL
```

1. First update the existing `postPurchase` function so it stores the `visitorId` alongside each new row in the `purchases` table.

```javascript server/purchases.js theme={"theme":"github-dark-dimmed"}
export async function postPurchase(body) {
  const createdAt = Date.now();

  const { eventId } = body;
  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id;

  try {
    db.prepare(
      `INSERT INTO purchases (eventName, ticketQuantity, price, creditCard, deliveryEmail, visitorId, createdAt)
      VALUES (@eventName, @ticketQuantity, @price, @creditCard, @deliveryEmail, @visitorId, @createdAt)`,
    ).run({ ...body, visitorId, createdAt });
    return { success: true, message: "Purchase completed successfully." };
  } catch (err) {
    console.error("Failed to save purchase:", err);
    return {
      success: false,
      message: "Failed to save purchase: " + err.message,
    };
  }
}
```

2. Update the `getRelatedPurchases` function so it looks up related orders based on both email and visitorId. This lets you see the full history for a visitor even if they change accounts.

```javascript server/purchases.js theme={"theme":"github-dark-dimmed"}
export function getRelatedPurchases(orderId) {
  try {
    const purchase = db
      .prepare("SELECT deliveryEmail, visitorId FROM purchases WHERE id = ?")
      .get(orderId);

    if (!purchase) {
      return {
        success: false,
        message: "No purchase found for the given order ID.",
      };
    }

    const { deliveryEmail, visitorId } = purchase;

    const purchases = db
      .prepare(
        `SELECT id, eventName, ticketQuantity, price, creditCard, deliveryEmail, chargeback, visitorId, createdAt
        FROM purchases
        WHERE deliveryEmail = ? OR visitorId = ?
        ORDER BY createdAt DESC`,
      )
      .all(deliveryEmail, visitorId);

    return { success: true, purchases };
  } catch (err) {
    console.error("Failed to get purchases:", err);
    return {
      success: false,
      message: "Failed to get purchases: " + err.message,
    };
  }
}
```

3. In the merchant/admin view (`public/admin.js`), update the following functions to include the `visitorId` when displaying and exporting the history related to a purchase:

```javascript public/admin.js theme={"theme":"github-dark-dimmed"}
function createHistoryRow(purchase) {
  // ...
  row.querySelector("[data-email]").textContent = purchase.deliveryEmail || "";
  row.querySelector("[data-visitor-id]").textContent = purchase.visitorId || "";
  row.querySelector("[data-ticket-quantity]").textContent = purchase.ticketQuantity;
  row.querySelector("[data-total]").textContent = `$${total.toFixed(2)}`;
  row.querySelector("[data-credit-card]").textContent = purchase.creditCard;

  // ...
}

function exportToCsv() {
  // ...

  // CSV headers
  const headers = ["Event", "Date", "Email", "Visitor ID", "Tickets", "Total", "Card", "Status"];

  // Convert purchases to CSV rows
  const rows = currentPurchaseHistory.map((purchase) => {
    const total = purchase.price * purchase.ticketQuantity;
    const purchaseDate = formatDate(purchase.createdAt);
    const status = purchase.chargeback === 1 ? "Chargeback" : "Completed";

    return [
      purchase.eventName,
      purchaseDate,
      purchase.deliveryEmail || "",
      purchase.visitorId || "",
      purchase.ticketQuantity,
      `$${total.toFixed(2)}`,
      purchase.creditCard,
      status,
    ];
  });

  // ...
}
```

4. Then in the `admin.html` file, uncomment the visitor ID header and template column:

```html public/admin.html theme={"theme":"github-dark-dimmed"}
<td class="px-4 py-3 whitespace-nowrap text-sm text-gray-500" data-visitor-id>Visitor ID</td>

<!-- ... -->

<th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">
  Visitor ID
</th>
```

This gives the simulated evidence package additional information to help dispute friendly fraud chargebacks. Browser and device identifiers aren't the only types of evidence a merchant can submit, but they provide a strong additional signal of continuity that [card networks ask for during chargeback dispute reviews](https://fingerprint.com/blog/chargeback-dispute-process/). You can expand the logic by including more factors, depending on the level of detail your business needs.

<Info>
  This is a minimal example showing how to use Fingerprint data to support chargeback disputes. In a
  real application, make sure to implement proper security practices, perform robust server-side
  validation, and follow your organization's standards for storing and transmitting evidence related
  to payments and disputes.
</Info>

## 6. Test your implementation

Now that everything is wired up, you can see how the visitor ID provides additional evidence for chargeback disputes.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Make a few purchases from the main **Events** page. Each one will be logged with both your account email (you are logged in as `jamie@example.com`) and your visitor ID.
3. Open your personal **Order history** page and simulate a chargeback on one of them.
4. Switch to the **Merchant view** and view the purchase history related to the purchase with the chargeback. You'll see your full purchase history including visitor ID, showing that the disputed purchase and the earlier successful purchases all originated from the same browser.

## Next steps

You now have a basic chargeback dispute helper powered by Fingerprint. From here, you can enrich the dispute evidence even more with [Smart Signals](/docs/smart-signals-reference). To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Overview
Source: https://docs.fingerprint.com/docs/cloudflare-integration

Fingerprint JavaScript agent v4.0.0 or later is required.

Fingerprint Cloudflare Proxy Integration proxies JavaScript agent download and identification requests between your website and Fingerprint through Cloudflare. Your website does not strictly need to be behind Cloudflare to use this proxy integration, although that is optimal for ease of setup and maximum accuracy benefits.

<Info>
  This guide assumes you are using [JavaScript agent v4](/reference/js-agent). If you are still
  using JavaScript agent v3, see [Cloudflare Proxy Integration
  (v3)](/docs/v3/cloudflare-integration) or migrate to [JavaScript agent
  v4](/reference/migrating-from-v3-to-v4).
</Info>

<img alt="Cloudflare Proxy Integration" />

The integration consists of three components:

* Fingerprint infrastructure
* Cloudflare worker, created and managed by Fingerprint but running in your Cloudflare account
* Fingerprint JavaScript agent installed on your website

Fingerprint creates a [Cloudflare Worker](https://workers.cloudflare.com/) on a specific path on your site. The rest of your site is not affected.

Cloudflare worker code is open-source and available [on GitHub](https://github.com/fingerprintjs/cloudflare-worker-proxy). Once the Fingerprint JavaScript agent is configured correctly, the worker delivers the latest client-side logic and proxies identification requests and responses between your site and Fingerprint APIs.

## The benefits of using Cloudflare Proxy Integration

* Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox
* Cookies are recognized as first-party, so they can live longer in the browser and extend the lifetime of visitor IDs
* Ad blockers do not block the Fingerprint JavaScript agent from loading
* Ad blockers do not block identification requests because they are sent to a path or subdomain that belongs to your site
* Insight and control over identification requests that you can combine with other Cloudflare features such as WAF or Analytics
* The ability to manage unlimited subdomains and paths and provide Fingerprint services to all your customers at any scale while benefiting from first-party integration improvements
* Cookie security: the Cloudflare integration drops all cookies sent from the origin website. The worker code is open-source, so you can verify and audit this behavior
* Easier compliance and auditing

## Setup

The Cloudflare configuration guide in the Fingerprint [dashboard](https://dashboard.fingerprint.com/) will help you set everything up step by step. Start the guide from **SDKs & integrations**.

<Warning>
  **Prerequisites**

  * Only users with the **Admin** or **Owner** roles can launch the Cloudflare configuration guide in the dashboard.
  * Cloudflare Proxy Integration uses the Cloudflare Workers [Custom Routes](https://developers.cloudflare.com/workers/platform/triggers/routes/) feature. Your site must be [added to Cloudflare](https://developers.cloudflare.com/fundamentals/get-started/setup/add-site/) and [proxied](https://developers.cloudflare.com/dns/manage-dns-records/reference/proxied-dns-records/) through Cloudflare, not DNS-only. If you can only add your domain to Cloudflare without proxying, see [Alternative worker subdomain setup (for DNS-only domains)](#alternative-worker-subdomain-setup-for-dns-only-domains).
</Warning>

### Step 1: Follow the Cloudflare configuration wizard

1. Go to **SDKs & integrations**, then select **Cloudflare**.

<img alt="SDKs & integrations page - Cloudflare Integration" />

2. In the Cloudflare configuration guide, click **Connect**.

<img alt="Cloudflare configuration wizard - Connect" />

3. Optionally, [scope the integration to a specific environment](/docs/multiple-environments#proxy-integrations-and-proxy-secrets).
   * By default, the integration works for all environments in your workspace.
   * If you scope the integration to a specific environment, it will only proxy identification requests made with public API keys from that environment.

4. Add information about your Cloudflare account.

<img alt="Cloudflare configuration wizard - Add information" />

<br />

| Name                  | Example                                  | Short description                                                                                          |
| :-------------------- | :--------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
| Cloudflare Account ID | 88e2a7348d589a61edd0918e57fb136f         | The Account ID from the [Cloudflare Dashboard](https://dash.cloudflare.com/).                              |
| Cloudflare API Token  | YQSnnxWAQiiEh9qM58wZNnyQS7FUdoqGIUAbrh7T | API token generated on Cloudflare's [**API Tokens** page](https://dash.cloudflare.com/profile/api-tokens). |

#### Cloudflare Account ID

The account ID is required to deploy workers. Go to [Cloudflare Workers](https://dash.cloudflare.com/?to=/:account/workers) and copy the account ID.

#### Cloudflare API token

The API token is required to deploy workers. Go to the [**API Tokens** page](https://dash.cloudflare.com/profile/api-tokens), select [**Create Custom Token**](https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B"key"%3A"workers_routes"%2C"type"%3A"edit"%7D%2C%7B"key"%3A"workers_scripts"%2C"type"%3A"edit"%7D%5D\&name=fingerprint.com), and follow these steps:

* Type `fingerprint.com` in the name field
* Add the **Workers Scripts** > **Edit** account permission
* Add the **Workers Routes** > **Edit** zone permission
* Select the account in **Account Resources**
* Select the website in **Zone Resources**
* Add IP filtering for `3.23.16.20`
* Do not set a TTL

<img alt="API Token Creation Form" />

In the next step, review the summary and click **Create Token**.

<img alt="API Token Summary" />

<Note>
  **API token safety**

  When creating an API token, grant as few privileges as possible. In the example above, the token can only manage workers in your account. Fingerprint uses your API token only for managing the Fingerprint Cloudflare worker.

  Fingerprint encrypts customer data, including API tokens and configuration items. Client IP address filtering adds another layer of security. Allowing the Fingerprint Cloudflare service IP ensures the API token can only be used by Fingerprint services.
</Note>

5. After entering the account ID and API token, continue to the next step.

<img alt="Cloudflare configuration wizard - Select domain" />

6. Select the same domain you used when creating the API token. If you do not see the domain you want to use, contact [support](https://fingerprint.com/support).

<img alt="Cloudflare configuration wizard - Select domain" />

7. Confirm the deployment. This process can take several minutes.

Once deployment completes, Fingerprint creates a worker named like `fingerprint-pro-cloudflare-worker-random-id`. You can see it in the [Cloudflare Workers Dashboard](https://dash.cloudflare.com/?to=/:account/workers/overview).

<Warning>
  **Do not disrupt worker authentication or updates**

  The integration wizard creates a proxy secret in your Fingerprint dashboard and passes it to your Cloudflare worker through environment variables.

  Do not delete the proxy secret in either place. Proxied identification requests without a valid proxy secret fail with an authentication error.

  Fingerprint updates your Cloudflare worker to keep visitor identification working correctly as browsers change. Outdated worker configuration can lower accuracy or break visitor identification completely. Do not make changes that would prevent Fingerprint from updating your worker:

  * Do not reduce the API token permissions or revoke it
  * Do not change the worker name
  * Do not change the original worker route or configuration
</Warning>

### Step 2: Configure your JavaScript agent

Once the worker is deployed, configure your client-side application to use it. You can always return to **SDKs & integrations** to get code snippets for different frameworks that match your Cloudflare setup.

<img alt="Cloudflare configuration wizard - Configure your JavaScript agent" />

#### JavaScript agent configuration example

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  // The same pattern applies to React SDK, Vue SDK, and other frontend SDKs.
  import * as Fingerprint from '@fingerprint/agent';

  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: 'https://yourwebsite.com/WORKER_PATH/?region=us',
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN installation theme={"theme":"github-dark-dimmed"}
  const fpPromise = import('https://yourwebsite.com/WORKER_PATH/web/v4/PUBLIC_API_KEY').then(
    (Fingerprint) =>
      Fingerprint.start({
        region: 'us',
        endpoints: 'https://yourwebsite.com/WORKER_PATH/?region=us',
      }),
  );

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

* Include the region in the `endpoints` URL query string using the format `?region=REGION`. Replace `REGION` with the [region](/docs/regions) of your application.

<Note>
  **Migrating from JavaScript agent v3**

  Cloudflare Proxy Integration remains compatible with JavaScript agent v3, so you can upgrade when it works for your rollout plan.

  When you migrate to JavaScript agent v4:

  * Remove `scriptUrlPattern` and `endpoint`
  * Replace them with a single `endpoints` option that points to the worker route, for example `https://yourwebsite.com/WORKER_PATH/?region=us`
  * See [Migrating JavaScript agent from v3 to v4](/reference/migrating-from-v3-to-v4#use-endpoints-instead-of-scripturlpattern) for more details
</Note>

### Using multiple worker routes

Cloudflare Proxy Integration uses Cloudflare Workers, which supports [multiple routes](https://developers.cloudflare.com/workers/platform/triggers/routes/). You can add more routes if you need to, but do not change the original worker route or configuration created by Fingerprint.

## Monitoring and troubleshooting the integration

Go to **Dashboard** > [**SDKs & integrations**](https://dashboard.fingerprint.com/integrations) > **Cloudflare** to see the integration status, usage statistics, and configuration. You can monitor:

* Whether the integration is up to date
* How many identification requests go through the integration, and how many do not
* The error rate of proxied identification requests, usually caused by a missing or incorrect proxy secret

The information on the status page is cached, so allow a few minutes for the latest data points to appear.

<img alt="Cloudflare integration status" />

The Cloudflare integration has limited visibility into your Cloudflare environment. If you run into issues, verify that firewall rules, rate limiting rules, or other Cloudflare restrictions are not disrupting the Fingerprint worker and its path. Contact [support](https://fingerprint.com/support/) if needed.

### Updating the Cloudflare token

If you accidentally delete the Cloudflare API token you provided to Fingerprint, you can update it in the Fingerprint dashboard.

* Go to [**SDKs & integrations**](https://dashboard.fingerprint.com/integrations) > **Cloudflare** and click **Edit API token**

<img alt="Cloudflare configuration wizard - Updating the Cloudflare token" />

### Deleting the integration

If something goes irreversibly wrong with your integration or Cloudflare worker configuration, you can delete everything and create a new integration from scratch.

1. Make sure your Fingerprint JavaScript agent is not using the integration URLs you are about to delete.
2. Go to [**SDKs & integrations**](https://dashboard.fingerprint.com/integrations) > **Cloudflare** and click **Delete integration** at the bottom of the page.

This deletes the Cloudflare worker and all associated records.

## Alternative worker subdomain setup (for DNS-only domains)

The Cloudflare configuration guide above assumes your website is added to Cloudflare and [proxied through Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/reference/proxied-dns-records/) instead of DNS-only. If your website uses DNS-only mode, the worker is not accessible on the generated path and the provided code snippets do not work.

<img alt="Cloudflare integration status" />

If you cannot proxy your primary domain through Cloudflare, you can host the Fingerprint worker on a subdomain instead. This still requires that your website is [added to Cloudflare](https://developers.cloudflare.com/fundamentals/setup/manage-domains/add-site/) without proxying.

1. Follow the installation steps above to deploy the proxy integration worker in your Cloudflare account.
2. Go to your [Cloudflare dashboard](https://dash.cloudflare.com/).
3. In the left-hand navigation, click **Workers & Pages**.
4. Click your Fingerprint Cloudflare worker. It will be named like **fingerprint-pro-cloudflare-worker-yourwebsite-com**.
5. At the top, click **Settings**, then find **Domains & Routes**.
6. Click **+ Add** and select **Custom domain**.
7. Enter a subdomain like `metrics.yourwebsite.com` and click **Add domain**. Avoid terms commonly blocked by ad blockers like `fingerprint`, `fpjs`, or `track`.

<img alt="Cloudflare add custom domain" />

Your new subdomain will be proxied through Cloudflare, even though your primary domain is not:

<img alt="Cloudflare alternative setup DNS" />

Your Fingerprint worker is now accessible on the chosen subdomain. Update the code snippets shown on [**SDKs & integrations**](https://dashboard.fingerprint.com/integrations) accordingly. For example, `endpoints: https://yourwebsite.com/VWmFUKL1dfIjc8gg/?region=us` becomes `endpoints: https://metrics.yourwebsite.com/VWmFUKL1dfIjc8gg/?region=us`.


# Blocking Origins and IPs
Source: https://docs.fingerprint.com/docs/cloudflare-integration-blocking-ips-and-origins



Fingerprint allows you to [filter requests](/docs/request-filtering) to prevent bad actors from making identification requests using your account. Filtered-out requests do not count toward your Fingerprint billing. However, if you use Cloudflare Proxy Integration, those requests can still be proxied through your Cloudflare worker, which can increase your Cloudflare costs.

To prevent this, you can block specific IPs or origins at the Cloudflare worker level by using Cloudflare's Web Application Firewall.

<Note>
  **Cloudflare Web Application Firewall**

  * You are limited to 5 WAF custom rules on the Cloudflare [free plan](https://www.cloudflare.com/plans/).
  * This guide uses the Cloudflare dashboard to create WAF custom rules manually. You can also create and modify custom rules programmatically using the [Cloudflare API](https://developers.cloudflare.com/waf/custom-rules/create-api/).
</Note>

## 1. Find the worker route

The JavaScript agent v4 uses a single worker route for all requests to Fingerprint servers.

The easiest way to find your route is from the JavaScript agent configuration snippet on **SDKs & integrations** > **Cloudflare**:

1. Go to **SDKs & integrations** > **Cloudflare** in the Fingerprint dashboard.
2. Find the JavaScript agent configuration snippet.
3. Copy the `WORKER_PATH` part from the `endpoints` value.

For example, if your snippet uses `https://yourwebsite.com/icXhT6JSJ2MhAdk6/?region=us`, then your worker route to protect is `/icXhT6JSJ2MhAdk6*`.

## 2. Create a firewall rule

Create a [custom rule](https://developers.cloudflare.com/waf/custom-rules/) in your Cloudflare WAF.

1. In the Cloudflare dashboard, go to **Websites** > **Your website** > **Security** > **WAF** > **Custom rules**.
2. Click **Create rule**.
3. Enter a name for the rule.
4. Use the visual editor or click **Edit expression** to define the rule using the [Rules language](https://developers.cloudflare.com/ruleset-engine/rules-language/).
5. Choose `Block` as the rule action.
6. Click **Deploy**.

<img alt="Screenshot of the firewall rule" />

### Block requests from specific IP addresses

For example, to block IPs `111.111.112.113`, `114.112.222.33`, and the entire `211.12.82.0/24` subnet for worker route `/icXhT6JSJ2MhAdk6*`, use this expression:

```txt theme={"theme":"github-dark-dimmed"}
(
  ip.src in {111.111.112.113, 114.112.222.33, 211.12.82.0/24}
  and starts_with(http.request.uri.path, "/icXhT6JSJ2MhAdk6")
)
```

### Block requests from specific `origin` and `referer`

For example, to block requests from `example1.com` for the same worker route, use this expression:

```txt theme={"theme":"github-dark-dimmed"}
(
  starts_with(http.request.uri.path, "/icXhT6JSJ2MhAdk6")
  and
  (
    any(http.request.headers["origin"][*] == "https://example1.com")
    or
    any(http.request.headers["referer"][*] contains "https://example1.com/")
  )
)
```

Block requests by `referer` in addition to `origin` because some request types [do not include the `origin` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin#description).

See the [Cloudflare rules language documentation](https://developers.cloudflare.com/ruleset-engine/rules-language/) for more details.

### Cloudflare limitations

* Each rule expression can contain up to [4096 symbols](https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/#maximum-rule-expression-length)
* The number of custom rules depends on [your Cloudflare plan](https://www.cloudflare.com/plans/)


# Migrating CloudFront proxy integration to JavaScript Agent V4
Source: https://docs.fingerprint.com/docs/cloudfront-integration-migration-to-js-agent-v4



This migration guide describes how to switch to JavaScript Agent V4 in your Fingerprint CloudFront integration with zero downtime and without the need to update the proxy path used by your [JavaScript Agent](/reference/js-agent).

## Migration overview

<Info>
  **Upgrade to v2 first**

  If your CloudFront integration is still on v1, follow the [migrating CloudFront proxy integration from v1 to v2 guide](/docs/v3/cloudfront-integration-migration-from-v1-to-v2) to upgrade to **2.2.0** (or later) first. Then, return to this guide to finish migrating to JavaScript Agent V4.
</Info>

1. Update your CloudFront Integration to the latest version that supports JavaScript Agent V4 (**2.2.0** or later) using your preferred deployment method.
2. Update your CloudFront distribution cache behavior path.
3. Verify that the updated integration works.
4. Switch from JavaScript Agent V3 to V4 in your application.

## Step 1: Update your CloudFront Integration's Lambda function

Follow the update guide for your deployment method:

* **CloudFormation**:
  * If you've enabled the [automatic updates](/docs/install-cloudfront-integration-using-cloudformation#step-6-enable-automatic-updates-in-the-fingerprint-dashboard) you should already be using the latest version of the Lambda function.
  * **Important**: Due to recent changes on AWS, you might need to update your Management Lambda function permissions. To do so, follow the [CloudFront Management Lambda permissions update](/docs/cloudfront-cloudformation-mgmt-lambda-permissions-update) guide.
  * If you are not using automatic updates, you need to [update the Lambda function manually](/docs/manually-updating-your-aws-cloudfront-integration-lambda-function).
* **Terraform**:
  * [Update the Lambda function in your Terraform configuration](/docs/aws-cloudfront-integration-via-terraform#updating-the-integration).

To verify the integration version, check your integration status page available at `https://yourwebsite.com/FPJS_BEHAVIOR_PATH/status`.

## Step 2: Update your CloudFront distribution cache behavior path

Depending on your deployment method, you need to update the cache behavior path in your CloudFront distribution in the following ways:

<Info>
  The latest version of the Lambda function maintains compatibility with your existing CloudFront
  configuration and JavaScript agent v3, but the following CloudFront configuration change is
  recommended before upgrading to JavaScript agent v4.
</Info>

### CloudFormation

1. Head to your CloudFront distribution in the AWS console.
2. Select the **Behaviors** tab and edit the **fpcdn.io** behavior.
3. Update the **Path Pattern** from `FPJS_BEHAVIOR_PATH/*` to `FPJS_BEHAVIOR_PATH*` (without the trailing slash):
   ```diff theme={"theme":"github-dark-dimmed"}
   - FPJS_BEHAVIOR_PATH/*
   + FPJS_BEHAVIOR_PATH*
   ```
4. Save the changes.
5. If your behavior path contains more than one segment (e.g. `ore54guier/vbcnkxb654`):
   1. Head to the **Origins** tab and edit the **fpcdn.io** origin.
   2. Add a custom header:
      * Set **Header name** to `FPJS_INTEGRATION_PATH_DEPTH`.
      * Set **Value** to the number of path segments in the behavior path, in our example it's `2`.
      ```
       Segment      Segment
          ↓            ↓
      ore54guier / vbcnkxb654 → 2 path segments
      ```
   3. Save the changes.

### Terraform

<Info>
  Ensure that you're using our Terraform Module version [v2.0.0](https://github.com/fingerprintjs/terraform-aws-fingerprint-cloudfront-proxy-integration/releases/tag/v2.0.0) or later.
</Info>

Update your CloudFront distribution cache behavior `path_pattern` from `FPJS_BEHAVIOR_PATH/*` to `FPJS_BEHAVIOR_PATH*` (without the trailing slash)

```terraform main.tf theme={"theme":"github-dark-dimmed"}
resource "aws_cloudfront_distribution" "cloudfront_dist" {
  ordered_cache_behavior {
    path_pattern = "FPJS_BEHAVIOR_PATH/*" // [!code --]
    path_pattern = "FPJS_BEHAVIOR_PATH*" // [!code ++]
  }
}
```

If your behavior path contains more than one segment (e.g. `ore54guier/vbcnkxb654`), you need to count the number of path segments in the behavior path and add the `integration_path_depth` parameter with value equal to the number of path segments:

```
 Segment      Segment
    ↓            ↓
ore54guier / vbcnkxb654 → 2 path segments
```

```terraform main.tf theme={"theme":"github-dark-dimmed"}
module "fingerprint_cloudfront_integration" {
  source = "fingerprintjs/fingerprint-cloudfront-proxy-integration/aws"

  fpjs_shared_secret       = "FPJS_PRE_SHARED_SECRET"
  // The number of path segments in the behavior path, in this case 2: ore54guier/vbcnkxb654 // [!code ++]
  integration_path_depth = 2 // [!code ++]
}

resource "aws_cloudfront_distribution" "cloudfront_dist" {
  // Your existing CloudFront configuration
  ordered_cache_behavior {
    path_pattern = "ore54guier/vbcnkxb654/*" // [!code --]
    path_pattern = "ore54guier/vbcnkxb654*" // [!code ++]
  }
}
```

Finally, apply the changes:

1. Run `terraform plan` to verify the planned configuration changes.
2. Run `terraform apply` to apply the changes.

## Step 3: Update your application to use the JavaScript Agent V4

At this point, you should have CloudFront integration running that will work with both v3 and v4 JavaScript agents.

Try using the integration with the V4 agent. For example:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from "@fingerprint/agent";

const fp = Fingerprint.start({
  apiKey: "PUBLIC_API_KEY",
  region: "us",
  endpoints: "https://yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us",
});

fp.get().then((result) => console.log(result));
```

All requests from the agent should go through your integration and resolve successfully. Confirm by using the Network tab in your browser Developer tools, as the JavaScript agent can fall back to default endpoints in case of an integration error.

## Step 4: Switch from JavaScript Agent V3 to V4

At this point, you can start migrating your application to use the new JavaScript Agent V4.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
import * as FingerprintJS from "@fingerprintjs/fingerprintjs-pro"; // [!code --]
import * as Fingerprint from "@fingerprint/agent"; // [!code ++]

// [!code --:10]
const fpPromise = FingerprintJS.load({
  apiKey: "PUBLIC_API_KEY",
  region: "us",
  scriptUrlPattern: [
    "https://yourwebsite.com/FPJS_BEHAVIOR_PATH/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>",
  ],
  endpoint: ["https://yourwebsite.com/FPJS_BEHAVIOR_PATH/FPJS_GET_RESULT_PATH?region=us"],
});

// [!code ++:10]
const fp = Fingerprint.start({
  apiKey: "PUBLIC_API_KEY",
  region: "us",
  endpoints: "https://yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us",
});
```

## What's next

To learn more, see the [JavaScript Agent V4 migration guide](/reference/migrating-from-v3-to-v4).


# Overview
Source: https://docs.fingerprint.com/docs/cloudfront-proxy-integration-v2



*Fingerprint CloudFront Proxy Integration* is responsible for proxying identification and agent-download requests between your website and Fingerprint through your AWS infrastructure. Your website does not strictly need to be behind CloudFront or run on AWS to use this proxy integration, although that is optimal for ease of setup and maximum accuracy benefits.

<img alt="Cloudfront diagram" />

<Note>
  **JavaScript Agent V4 Support**

  Support for JavaScript Agent V4 was introduced in version **2.2.0**.
</Note>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).
</Warning>

<Warning>
  **Update expectations**

  The underlying data contract in the identification logic can change to keep up with browser and device releases. Using the AWS CloudFront Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.
</Warning>

The integration consists of several components:

* Your website, which may be running on AWS CloudFront but doesn't have to.
* An [AWS CloudFront](https://aws.amazon.com/cloudfront/) distribution
  * If your website is already running on CloudFront, you can use the same distribution for the proxy integration. This is the recommended setup to maximize the accuracy benefits of the integration.
  * If your website is not running on CloudFront, you can create a new CloudFront distribution just for the proxy integration.
* [AWS Lambda@Edge Function](https://aws.amazon.com/lambda/edge/) that handles proxying requests to Fingerprint resources. We will refer to it as *"Lambda function*" going forward. It is available on a specific path on your site. The rest of your site is not affected.
* Additional cache behavior that enables using a Lambda function for proxying requests.
* AWS Secrets that store settings for Lambda and Management functions.
* If you choose the [CloudFormation installation method](/docs/install-cloudfront-integration-using-cloudformation), the integration also includes:
  * Management Lambda function that is responsible for updating the integration. We will refer to it as *"Management function"* going forward.
  * A [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) template and stack responsible for deploying the AWS resources listed above.

The Lambda proxy function code and the entire CloudFormation stack are 100% open-source and [available on GitHub](https://github.com/fingerprintjs/aws-cloudfront-proxy). Once the Fingerprint JavaScript agent is configured on your site correctly, the Lambda function is responsible for delivering the latest fingerprinting client-side logic as well as proxying identification requests and responses between your site and Fingerprint APIs.

## The benefits of using the CloudFront Integration

* Ad blockers will not block the Fingerprint JavaScript agent from loading. Connecting to an external URL is stopped by most ad blockers but connecting to the same site URL is allowed.
* Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox.
* Cookies are now recognized as “first-party.” This means they can live in the browser even when third-party cookies are blocked and extend the lifetime of visitor information.
* Insight and control over the identification requests that can be combined with other AWS features like [CloudWatch](https://aws.amazon.com/cloudwatch/).
* With the CloudFront Integration, you can manage an unlimited number of subdomains and paths. You can package and provide Fingerprint services to all your customers at any scale while benefiting from all the 1st-party integration improvements.
* Cookie security: CloudFront integration drops all cookies sent from the origin website. The Lambda function code is open-source so this behavior can be transparently verified and audited.
* Easy to meet compliance and auditing requirements.

## Prerequisites

* An AWS account.
* Optionally: An existing CloudFront distribution that serves your web application.
  * If your application does not run on CloudFront, the installation guide will help you create a new CloudFront distribution deployed on the same [eTLD + 1](https://developer.mozilla.org/en-US/docs/Glossary/eTLD) domain as your website, or any of its subdomains.

## Integration setup overview

The integration setup consists of several manual and automatic steps. Each step is discussed in detail below.

1. Issue a proxy secret in the Fingerprint Dashboard.
2. Create a path variable that is used by the AWS configuration and the client agent configuration on your website or mobile app.
3. Install and configure the integration in your AWS account. You have 2 options:
   1. [Using a CloudFormation template](/docs/install-cloudfront-integration-using-cloudformation) and the AWS user interface.
   2. [Using Terraform](/docs/aws-cloudfront-integration-via-terraform).

Finally, configure the Fingerprint JavaScript agent on your website or client application.

## Step 1: Issue a proxy secret

Your integration needs a proxy secret to authenticate requests from your Lambda function to Fingerprint servers.

1. Go to the Fingerprint [Dashboard](https://dashboard.fingerprint.com) and select your workspace in the top left.
2. Navigate to [**API Keys**](https://dashboard.fingerprint.com/api-keys).
3. Click **Create proxy key**.
4. Name it something like `CloudFront integration`.
5. Optionally, you can [choose an environment](/docs/multiple-environments#proxy-integrations-and-proxy-secrets) for the proxy secret.
   1. By default, the proxy secret works for all environments in your workspace.
   2. A proxy secret scoped to a specific environment can only authenticate identification requests made with a public API key from the same environment.
6. Click **Create API key**.
7. Save the secret value somewhere. You will use it later as the `FPJS_PRE_SHARED_SECRET` variable.

## Step 2: Create path variable

Set the path variable you will use throughout your AWS configuration and the JavaScript agent configuration on your website. This value is arbitrary. Just decide what your value is and write it down somewhere.

In this guide, we will use readable values corresponding to the variable names to make it easier to follow:

```dotenv theme={"theme":"github-dark-dimmed"}
FPJS_BEHAVIOR_PATH="FPJS_BEHAVIOR_PATH"
```

However, your values used in production should look more like random strings:

```dotenv theme={"theme":"github-dark-dimmed"}
FPJS_BEHAVIOR_PATH="ore54guier"
```

That is because some adblockers might automatically block requests from any URL containing fingerprint-related terms like "fingerprint", "fpjs", "track", etc. Random strings are the safest. So whenever you see a value like `FPJS_BEHAVIOR_PATH` in this guide, you should use your random value instead.

## Step 3: Install and configure the integration in your AWS account

You can choose from two available installation methods.

### Using Terraform

If you manage your infrastructure as code using Terraform, you can use the Fingerprint CloudFront proxy integration Terraform module. This installation method does not include any mechanism for automatic updates. The proxy function code is updated every time you run `terraform apply`.

If you prefer the Terraform installation method, continue with [**Install CloudFront integration using Terraform**](/docs/aws-cloudfront-integration-via-terraform).

### Using a CloudFormation template

If you don't use Terraform to manage your infrastructure, you can deploy the integration inside the AWS Console using a CloudFormation template. This installation method includes a Management Lambda function responsible for keeping your integration up-to-date. You will need to provide credentials for the Management function to the Fingerprint Dashboard to enable automatic updates.

If you prefer the CloudFormation installation method, continue with [**Install CloudFront integration using CloudFormation**](/docs/install-cloudfront-integration-using-cloudformation).

## Configure the Fingerprint JavaScript agent on your client

Use the path variable created in [Create path variable](#step-2-create-path-variable) to construct the endpoint URL.

If your website and the proxy integration are behind the same CloudFront distribution, the JavaScript Agent configuration will use randomized paths inside your domain, for example:

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: 'https://yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us'
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  const url = 'https://yourwebsite.com/FPJS_BEHAVIOR_PATH/web/v4/PUBLIC_API_KEY';
  const fpPromise = import(url)
    .then(Fingerprint => Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: 'https://yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us',
    }));

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

If you set up a separate CloudFront distribution on your subdomain, the JavaScript Agent configuration will use that subdomain to interact with Fingerprint, for example:

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: 'https://metrics.yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us'
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  const url = 'https://metrics.yourwebsite.com/FPJS_BEHAVIOR_PATH/web/v4/PUBLIC_API_KEY';
  const fpPromise = import(url)
    .then(Fingerprint => Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: 'https://metrics.yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us',
    }));

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

If everything is configured correctly, you should receive the latest Fingerprint client-side script and the identification result through your CloudFront distribution.

<Note>
  **Parameter URL nuances**

  * Pass a `region` query parameter to the `endpoints` URL in the following format: `?region=eu`. The value needs to reflect the [region](/docs/regions) of your workspace.
</Note>

## Monitoring and managing the integration

Go to **Dashboard** > [**SDKs & integrations**](https://dashboard.fingerprint.com/integrations) > **AWS CloudFront** to see the status of your integration. Here you can monitor:

* If automatic updates are enabled (only relevant for the [CloudFormation installation method](/docs/install-cloudfront-integration-using-cloudformation)).
* If the integration is up to date.
* How many identification requests are coming through the integration (and how many are not).
* The error rate of proxied identification requests (caused by a missing, incorrect, or environment-mismatched proxy secret).

The information on the status page is cached, so allow a few minutes for the latest data points to be reflected.

<img alt="" />

If you installed the integration [using CloudFormation](/docs/install-cloudfront-integration-using-cloudformation), you can also disable automatic updates (not recommended) or update the provided Management function details.

<img alt="" />

## Cost calculation for AWS

You can use [AWS Calculator](https://calculator.aws/) to estimate your expenses.

**Lambda\@Edge service**

* The **number of requests** is roughly equal to visitor identification events multiplied by three.
  There are up to 3 requests for each visitor identification.
  * The first request downloads the agent script. This request is typically cached by the browser.
  * The second request calls the identification endpoint. Caching the identification request is up to you, but most of our [frontend libraries](/docs/frontend-libraries) have a caching mechanism built in.
  * Potentially, a third helper request may be used to improve accuracy. This request is typically cached by the browser.
* The **duration of each request** depends on your CloudFront availability settings. The typical duration of the agent download request is 200ms, for identification requests it is 500ms.
* The **amount of memory allocated** is 128MB.
* The Lambda function has [CloudWatch logs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/edge-functions-logs.html) enabled.

**Secrets Manager**

* The **number of secrets** is 2.
* The **number of API calls** is approximately 12 calls per hour for each used AWS region.

**Additional costs for the CloudFront distribution**

* Data transfer **from** CloudFront distribution to clients:
  * The agent’s size is approximately 50-60 KB, depending on the exact version and network compression algorithm used (some browsers may not support `br` encoding).
  * The identification request result is up to 1 KB per request.
* Data transfer from clients **to** the CloudFront distribution:
  * The payload size for the identification requests is approximately 5-10kB.


# Configuring resources
Source: https://docs.fingerprint.com/docs/configuration

The Dashboard allows you to manage all the resources and settings that govern how your Fingerprint implementation operates.

## API keys

API keys are necessary for your Fingerprint setup. Primarily to be able to identify visitors and generate visitor IDs, but also interact with other Fingerprint APIs and features.

To manage API keys, go to **Dashboard** > [**API keys**](https://dashboard.fingerprint.com/api-keys).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 51 22@2x" />
</Frame>

| Keys                      | Description                                                                                                                                                                              |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Public**                | Used to make **client-side requests** to identify visitors and generate the visitor ID. Used in the [browser](/docs/identify-visitors) or in [mobile apps](/docs/mobile-identification). |
| **Server API**            | Used to make **server-side requests** to the Fingerprint [Server API](/reference/server-api) to securely obtain visitor and request information.                                         |
| **Management API**        | Used to access the [**Management API**](/reference/management-api), allowing management of dashboard resources.                                                                          |
| **Sealed Client Results** | Used to enable **Sealed Client Results** to [encrypt client-side payloads](/docs/sealed-client-results).                                                                                 |
| **Proxy**                 | Used to authenticate with third-party **proxy integrations** which allow you to [evade ad blockers](/docs/protecting-the-javascript-agent-from-adblockers).                              |

To monitor API key usage, throttling, and latency, see [API key monitoring](/docs/health#api-key-monitoring).

## Request filtering

Request filtering is a feature that enables you to filter out unwanted identification requests using specific rules. On the Dashboard, you can **manage filtering rules** by adjusting which events should be allowed or denied.

To learn more information, see [request filtering](/docs/request-filtering).

To manage webhooks, go to **Dashboard** > [**Security**](https://dashboard.fingerprint.com/traffic-rules).

## Webhooks

Webhooks allow you to receive an HTTP request to your server with Fingerprint results for every identification event the moment it happens. On the Dashboard, you can **manage webhooks** and monitor their activity.

To learn more information, see [webhooks](/docs/webhooks).

To manage webhooks, go to **Dashboard** > [**Webhooks**](https://dashboard.fingerprint.com/webhooks).

To inspect webhook delivery attempts and diagnose failures, see [Webhook monitoring](/docs/health#webhook-monitoring).

## Custom subdomains

By using a custom subdomain, Fingerprint cookies are treated as "first-party", which increases identification accuracy while also allows you to avoid ad blockers. On the Dashboard, you can **register your subdomains** and manage their certificates.

To learn more information, see [Custom subdomain setup](/docs/custom-subdomain-setup).

To manage subdomains, go to **Settings** > [**Subdomains**](https://dashboard.fingerprint.com/subdomains).

## Proxy integrations

Proxy integrations are an alternative to custom subdomains, they allow you to proxy requests to Fingerprint through your own domain. Our cookies are treated as "first-party", which increased identification accuracy while allowing you to avoid ad blockers. On the Dashboard, you can **setup proxy integrations** and monitor their status and activity.

To learn more information, see [Evading ad blockers with proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers).

To manage proxy integrations, go to **Dashboard** > [**Libraries & integrations**](https://dashboard.fpjs.sh/integrations/active)

## Suspect Score

Suspect Score is an easy way to integrate Smart Signals into your fraud protection workflow. It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. On the Dashboard, you can configure the **weights for suspect scoring** by adjusting for each detected Smart Signal.

To learn more information, see [Suspect Score](/docs/suspect-score).

To manage suspect score weights, go to **Dashboard** > **Smart Signals** > [**Suspect Score**](https://dashboard.fpjs.sh/suspect-score)

***

[Viewing analytics](/docs/analytics)


# Coupon Abuse
Source: https://docs.fingerprint.com/docs/coupon-abuse-use-case-tutorial

Learn how to prevent coupon abuse and protect your promotions from fraud

## Overview

This tutorial walks through implementing Fingerprint to prevent coupon abuse, where customers or fraudsters repeatedly redeem a discount code meant for one-per-user use.

You'll begin with a starter app that includes a mock checkout page and a basic coupon flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to check if they've already redeemed the coupon. This way, you can block repeat coupon redemptions from the same visitor.

By the end, you'll have a sample app that enforces one-time coupon usage per visitor and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `coupon-abuse` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Checkout page with coupon form" />

    <Tree.File name="index.js - Front-end logic to handle coupon submission" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="server.js - Serves static files and coupon validation endpoint" />

    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="coupons.js - Coupon validation logic" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock checkout page from the starter app. You can test out the basic coupon flow by entering a valid coupon code (e.g., `WELCOME20`, `SAVE10`) and clicking **Apply**. You'll notice the same coupon can currently be redeemed multiple times.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Apply**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the coupon code. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including the verified visitor ID and risk signals such as browser tampering or bot activity.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Apply** button already has an event handler set up for submitting a coupon. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the coupon to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
applyBtn.addEventListener("click", async () => {
  // ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/validate-coupon", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ coupon: code, eventId }),
    });
    const data = await res.json();

    // ...
  }
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your coupon validation logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/validate-coupon` route there to also extract `eventId` from the request body and pass it into the `validateCoupon` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/validate-coupon", async (req, reply) => {
  const { coupon, eventId } = req.body || {};
  const code = (coupon || "").toUpperCase().trim();

  const result = await validateCoupon(code, eventId);
  return reply.send(result);
});
```

2. The `server/coupons.js` file contains the logic for validating coupons. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/coupons.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `validateCoupon` function to accept `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/coupons.js theme={"theme":"github-dark-dimmed"}
export async function validateCoupon(code, eventId) {
  if (!code) {
    console.error("Missing coupon code.");
    return { success: false, error: "Coupon validation failed." };
  }

  if (!eventId) {
    console.error("Missing eventId.");
    return { success: false, error: "Coupon validation failed." };
  }

  const coupon = getValidCoupon(code);
  if (!coupon) {
    console.error("Invalid coupon code.");
    return { success: false, error: "Coupon validation failed." };
  }

  const event = await fpServerApiClient.getEvent(eventId);

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection and Suspect Score Smart Signals, which are only
  available on paid plans.
</Note>

A simple but powerful way to prevent fraudulent coupon abuse is to block automated applications that come from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found.

1. Continuing in the `validateCoupon` function in `server/coupons.js`, check the bot signal returned in the `event` object:

```javascript server/coupons.js theme={"theme":"github-dark-dimmed"}
export async function validateCoupon(code, eventId) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";

  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, error: "Coupon validation failed." };
  }

  // ...
}
```

You can also use Fingerprint's [Suspect Score](/docs/suspect-score) to flag suspicious coupon redemption attempts. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload, helping to identify suspicious activity. While it's not typical to block actions based solely on a high risk score, this example shows how you might incorporate it. In a real application, a better approach would be to flag the attempt for review or add some additional friction.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the coupon if it exceeds a chosen threshold (for example, 20):

```javascript server/coupons.js theme={"theme":"github-dark-dimmed"}
export async function validateCoupon(code, eventId) {
  // ...

  const suspectScore = event.suspect_score || 0;

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, error: "Coupon validation failed." };
  }

  // ...
}
```

## 6. Prevent multiple uses of coupons per visitor

Next, use the trusted visitor ID from the `event` object to enforce one-time coupon usage per visitor. If the same visitor ID tries to reuse the same coupon code, return a failure; otherwise, record the redemption and allow it. *(This example simplifies coupon redemption logic for demonstration purposes.)*

This makes coupon rules enforceable at the device level, not just the account level. Even if someone creates new accounts or checks out as a guest, the redemption is still linked to their device, keeping one-time coupons truly one-time.

Note: The starter app includes a SQLite database with these tables already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
coupons - Stores available coupon codes and discounts
  code TEXT PRIMARY KEY
  discountPct INTEGER NOT NULL

redemptions - Records which devices (visitorId) have redeemed a coupon
  id INTEGER PRIMARY KEY AUTOINCREMENT
  code TEXT NOT NULL
  visitorId TEXT
  createdAt INTEGER NOT NULL
```

1. Add some helper functions to the bottom of the `server/coupons.js` file to check and record coupon redemptions:

```javascript server/coupons.js theme={"theme":"github-dark-dimmed"}
// Check if the visitor has already redeemed the coupon code
function hasRedeemed(code, visitorId) {
  return !!db
    .prepare(`SELECT 1 FROM redemptions WHERE code = ? AND visitorId = ? LIMIT 1`)
    .get(code, visitorId);
}

// Record the visitor redeeming the coupon
function recordRedemption(code, visitorId) {
  db.prepare(`INSERT INTO redemptions (code, visitorId, createdAt) VALUES (?, ?, ?)`).run(
    code,
    visitorId,
    Date.now(),
  );
}
```

2. Update `validateCoupon` to retrieve the `visitorId` and use it to enforce the one-per-visitor coupon redemption rule and record successful redemptions:

```javascript server/coupons.js theme={"theme":"github-dark-dimmed"}
export async function validateCoupon(code, eventId) {
  // ...

  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, error: "Coupon validation failed." };
  }

  const visitorId = event.identification.visitor_id;

  if (hasRedeemed(coupon.code, visitorId)) {
    console.error("Coupon has already been redeemed.");
    return { success: false, error: "Coupon has already been redeemed." };
  }

  recordRedemption(coupon.code, visitorId);

  return { success: true, ...coupon };
}
```

This gives you a system to detect and block coupon abuse. You can extend it by allowing a limited number of redemptions per device, tailoring responses to your business rules, checking only recent redemption activity, etc.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error checking, and data handling that align with your
  production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full protected coupon flow using the checkout page.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. In the checkout form, enter a valid coupon (e.g., `WELCOME20`, `SAVE10`) and click **Apply**. You will see the discount applied.
3. Try applying the same coupon again. The second attempt will be rejected since the visitor has already redeemed that coupon.
4. Open the page in incognito and try to use the coupon again, your visitor ID will remain the same and the redemption is still blocked.
5. Bonus: Test the flow using a headless browser or automation tool to see bot detection in action. A sample script is available in `test-bot.js`. While your app is running, run the script with `node test-bot.js` in your terminal and observe that the automated coupon redemptions are blocked.

## Next steps

You now have a working coupon redemption flow secured with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your business policies, or layer in additional checks for suspicious visitors.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Credential Stuffing
Source: https://docs.fingerprint.com/docs/credential-stuffing-use-case-tutorial

Learn how to protect your application from credential stuffing attacks

## Overview

This tutorial walks through implementing Fingerprint to prevent credential stuffing, where attackers use bots to rapidly test stolen or guessed usernames and passwords across many accounts.

You'll begin with a starter app that includes a mock login page and a basic login flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to detect and block automated login attempts.

By the end, you'll have a sample app that rejects credential stuffing bots and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

<Note>
  This tutorial requires the Bot Detection Smart Signal, which is only available on paid plans.
</Note>

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `credential-stuffing` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Login page" />

    <Tree.File name="index.js - Front-end logic to handle login" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="server.js - Serves static files and login endpoint" />

    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="accounts.js - Credential stuffing prevention logic" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock login page from the starter app. You can test the basic login form using the included test account (`demo@example.com` / `password123`) and clicking **Log in**.
7. Then try to log in using the included headless bot test script `test-bot.js`. While the app is running, execute `node test-bot.js` and observe that the automated script logs in successfully. By default, the server does not distinguish between bots and real users.

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Log in**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the login payload. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including bot detection and other signals.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Log in** button already has an event handler for submitting the credentials. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the login to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
loginBtn.addEventListener("click", async () => {
  // ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
	    body: JSON.stringify({ email, password, eventId }),
    });
    const data = await res.json();

    // ...
  }
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your login logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and Bot Detection [Smart Signal](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/login` route there to also extract `eventId` from the request body and pass it into the `attemptLogin` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/login", async (req, reply) => {
  const { email, password, eventId } = req.body || {};
  const result = await attemptLogin({ email, password, eventId });
  return reply.send(result);
});
```

2. The `server/accounts.js` file contains the logic for handling logins. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `attemptLogin` function to accept `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  if (!email || !password) {
    console.error("Missing credentials.");
    return { success: false, error: "Login failed." };
  }

  if (!eventId) {
    console.error("Missing eventId.");
    return { success: false, error: "Login failed." };
  }

  const event = await fpServerApiClient.getEvent(eventId);

  const user = findAccountByEmail(email);
  if (!user || user.password !== password) {
    console.error("Invalid credentials");
    return { success: false, error: "Login failed." };
  }

  return { success: true };
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block credential stuffing bots

Credential stuffing attacks rely heavily on automated login attempts, so rejecting bots outright can stop the abuse. Fingerprint returns `not_detected` if no bot activity is found, `good` for known bots, like search engines, and `bad` for other automation tools. Any visitor identification that does not return `not_detected` can be blocked from logging in.

1. Continuing in the `attemptLogin` function in `server/accounts.js`, check the bot signal returned in the `event` object and block bots:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, error: "Bot detected. Login failed." };
  }

  // ...
}
```

You can also add [Suspect Score](/docs/suspect-score) as a secondary layer. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload, helping to identify suspicious activity. While you wouldn't normally block logins based only on a high risk score, you could flag them for review, modify rate-limits, or add step-up authentication.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the login if it exceeds a chosen threshold (for example, 20):

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  // ...

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, error: "Bot detected. Login failed." };
  }

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, error: "Login failed." };
  }

  // ...
}
```

## 6. Recognize repeat offenders by visitor ID

As a secondary measure, you can log the visitor ID from failed login attempts to spot repeat attackers. This way, even if they change accounts or rotate IPs, you can recognize and block the same device when it comes back or tries other actions on your site.

Note: The starter app includes a SQLite database with these tables already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
accounts - Stores login credentials for test accounts
  email TEXT PRIMARY KEY
  password TEXT NOT NULL

failed_logins - Logs visitorIds tied to repeated failed attempts
  id INTEGER PRIMARY KEY AUTOINCREMENT
  visitorId TEXT NOT NULL
  createdAt INTEGER NOT NULL
```

1. Add some helper functions to the bottom of the `server/accounts.js` file to record and check failed attempts:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
// Log a failed login attempt
function logFailedAttempt(visitorId) {
  db.prepare(`INSERT INTO failed_logins (visitorId, createdAt) VALUES (?, ?)`).run(
    visitorId,
    Date.now(),
  );
}

// Get the number of recent failed login attempts
function getRecentFailedAttempts(visitorId) {
  const since = Date.now() - 24 * 60 * 60 * 1000; // 24 hours ago
  const row = db
    .prepare(
      `SELECT COUNT(*) as count 
       FROM failed_logins 
       WHERE visitorId = ? AND createdAt >= ?`,
    )
    .get(visitorId, since);
  return row.count;
}
```

2. Update `attemptLogin` to retrieve the `visitorId`, log failed attempts, and block repeat offenders:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptLogin({ email, password, eventId }) {
  if (!email || !password) {
    console.error("Missing email or password.");
    return { success: false, error: "Login failed." };
  }

  if (!eventId) {
    console.error("Missing eventId.");
    return { success: false, error: "Login failed." };
  }

  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id;

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    logFailedAttempt(visitorId);
    console.error("Bot detected.");
    return { success: false, error: "Bot detected. Login failed." };
  }

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    logFailedAttempt(visitorId);
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, error: "Login failed." };
  }

  if (getRecentFailedAttempts(visitorId) >= 3) {
    logFailedAttempt(visitorId);
    console.error("Too many failed login attempts.");
    return { success: false, error: "Too many failed login attempts." };
  }

  const user = findAccountByEmail(email);
  if (!user || user.password !== password) {
    logFailedAttempt(visitorId);
    console.error("Invalid credentials");
    return { success: false, error: "Login failed." };
  }

  return { success: true };
}
```

Together with the bot detection Smart Signal, this allows you to protect your logins and prevent credential stuffing. You can extend it by analyzing additional signals, changing rate limit thresholds, varying your response, etc.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error checking, and password handling that align with your
  production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full protected login flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Try logging in with the valid test account (`demo@example.com` / `password123`). You should see a success response.
3. Now try a few failed login attempts using the wrong password. After 3 repeated failures, additional attempts from the same device will be blocked based on the failed login check.
4. Next, run the included headless bot test script from the `credential-stuffing` folder. This will attempt to log in using a headless browser, which will be flagged by the Bot Detection signal and rejected:

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

*Note: If you encounter errors launching the automated browser, make sure you have the testing browser installed:*

```bash Terminal theme={"theme":"github-dark-dimmed"}
npx puppeteer browsers install chrome
```

## Next steps

You now have a working login flow that blocks credential stuffing bots with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your business policies, or layer in additional defenses, such as rate limiting with multi-factor authentication.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Custom subdomain setup
Source: https://docs.fingerprint.com/docs/custom-subdomain-setup

Using a custom subdomain is required for correct identification while using Fingerprint.

## The benefits of using a custom subdomain

* Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox.
* Ad blockers can't block the JavaScript agent. Most ad blockers stop requests sent to an external URL, but allow requests sent to an internal URL like a subdomain.
* Cookies are recognized as "first-party." This means they can be saved in the visitor's browser and used to reliably identify visitors when third-party cookies are blocked completely (for example, Safari blocks all third-party cookies).
* Fingerprint becomes harder to detect. Requests made directly to the Fingerprint domain are easy to detect. Routing through a subdomain on your own domain makes Fingerprint harder for automated blockers and fraudsters to detect.

<Info>
  **Limitations of the subdomain integration**

  * Since Safari 16.4, cookie lifetime in Safari is reduced to 7 days when using the custom subdomain setup. To keep cookies lasting up to one year in Safari, use a cloud proxy integration such as the [Cloudflare proxy integration](/docs/cloudflare-integration).
</Info>

<Info>
  **A note on DNS setup**

  This process requires adding DNS records to your domain, so make sure you have access to your DNS through your DNS provider. Here are guides for accessing DNS with some popular providers:

  * [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/)
  * [Route53](https://repost.aws/knowledge-center/route-53-create-alias-records)
  * [GoDaddy](https://www.godaddy.com/help/add-a-cname-record-19236)
  * [Netlify](https://docs.netlify.com/domains-https/custom-domains/configure-external-dns)
  * [Dreamhost](https://help.dreamhost.com/hc/en-us/articles/360035516812-Adding-custom-DNS-records)
  * [Bluehost](https://my.bluehost.com/hosting/help/resource/714)

  If your DNS provider supports [one-click setup](#one-click-setup-with-domain-connect), you can skip adding records by hand.
</Info>

<Tip>
  Prefer to automate setup? You can create, verify, list, and delete subdomains programmatically with the Management API instead of the dashboard. See [Manage subdomains with the Management API](#manage-subdomains-with-the-management-api).
</Tip>

## 1. Register your custom subdomain

To use a custom subdomain, the connection between your site and Fingerprint must be secure, so Fingerprint registers every subdomain with an SSL certificate. Each workspace can have up to 50 unique subdomains. During your free trial, you can use up to 5. If you need more than 50, contact the [support team](https://fingerprint.com/support/).

To start, go to **Settings** > [**Subdomains**](https://dashboard.fingerprint.com/subdomains) and select **New subdomain**.

<Frame>
  <img alt="Subdomains page listing each subdomain and its status" />
</Frame>

Enter your domain, then select **Add domain**. Add each subdomain individually. After you add a subdomain, you can't edit it. You can view its DNS details at any time, but to change a subdomain, delete it and add it again.

<Frame>
  <img alt="New subdomain form with a field to enter your domain and a step to add DNS records" />
</Frame>

Follow these guidelines when choosing a subdomain:

* Use the subdomain only for sending requests to Fingerprint.
* Match the subdomain's primary domain to the request origin. For example, use `metrics.yourwebsite.com` when you run Fingerprint on `yourwebsite.com`.
* Avoid the words `fingerprint` and `fp` in the subdomain name. Names like `fingerprint.yourwebsite.com` or `fp.yourwebsite.com` are easier for ad blockers to detect and block. Use a neutral name like `metrics.yourwebsite.com` instead.

## 2. Add DNS records

Your subdomain needs three DNS records:

* **One CNAME record** verifies that you own the domain.
* **Two A records** route identification traffic to Fingerprint.

There are two ways to add them. If your DNS provider supports [Domain Connect](https://www.domainconnect.org/) you can authorize the change directly. Otherwise, add the records manually.

### One-click setup with Domain Connect

Domain Connect is an open standard that lets Fingerprint apply DNS records to your domain once you authorize it with your DNS provider.

If your DNS provider supports one-click setup, use it instead of adding the records yourself.

These DNS providers support one-click setup with Fingerprint:

* Cloudflare

Fingerprint is working with other DNS providers to add support.

After you add your domain, the dashboard checks whether your DNS provider supports Domain Connect. If it does, a one-click setup card appears above the DNS records showing the provider it detected:

1. Select **Connect**. The dashboard redirects you to your DNS provider.
2. Sign in to your DNS provider if you aren't signed in already.
3. Review the consent page. It lists the exact CNAME and A records Fingerprint adds. With Cloudflare, the records are shown as **DNS only**, make sure that proxying stays off.
4. Select **Authorize**. Your DNS provider adds the records right away and returns you to the dashboard.

<Info>
  Authorizing through Domain Connect is a one-time action for a single subdomain. It doesn't give Fingerprint ongoing access to your DNS or the ability to make later changes. To set up another subdomain, run the flow again.
</Info>

If you close your DNS provider's page without authorizing, no records are added. The subdomain stays pending, so you can start the flow again or add the records manually.

### Add DNS records manually

If your DNS provider doesn't support Domain Connect, or you prefer to add the records yourself, the dashboard shows every record you need in one place.

To add every record at once, select **Copy all records** and paste them into your DNS provider. This uses the standard zone file format, which providers like Cloudflare and Route 53 accept for bulk import. You can also copy each record individually.

<Info>
  You can add the two A records right away. They start routing traffic once your certificate is issued.
</Info>

<Frame>
  <img alt="DNS records that need to be set" />
</Frame>

### Conflicting CAA records

Fingerprint also checks your domain for a conflicting CAA record. A CAA record controls which certificate authorities can issue certificates for your domain, and a conflicting one prevents Fingerprint's SSL provider (Cloudflare) from issuing yours. If Fingerprint finds a conflict, the dashboard shows an extra CAA record to add alongside the others, for example:

```
metrics.yourwebsite.com. CAA 0 issue "pki.goog"
```

Add this record yourself. One-click setup doesn't cover CAA records.

### Verify your records

Once the records are in place, whether you added them through one-click setup or by hand, Fingerprint checks for them automatically and updates the status on the Subdomains page. To run a check right away, click **Check DNS records**. Fingerprint also emails you once your certificate is issued.

DNS changes can take up to 24 hours to propagate. If Fingerprint doesn't detect your records yet, wait a while and click **Check DNS records** again. If your records aren't validated within 14 days, the subdomain times out. Add your DNS records and restart verification to try again.

### Subdomain statuses

Each subdomain shows one of these statuses:

* **Pending**: Fingerprint is validating your DNS records and issuing the SSL certificate. This can take up to 24 hours. To confirm a record was added correctly, run `dig HOST +short` in your terminal, using the host value of the record. If the record is set up correctly, its value is returned.
* **Active**: Your records are validated and the certificate is issued. Your subdomain is ready to use.
* **Timed out**: DNS validation timed out because the required records weren't added in time. Add the DNS records, then restart verification.
* **Failed**: The records were found, but the certificate can't be issued. This usually happens when a conflicting CAA record blocks Fingerprint's SSL provider (Cloudflare) from issuing certificates. Add the CAA record shown in the dashboard, wait for it to propagate, then delete the failed subdomain and add it again.

<Info>
  **Using Cloudflare as your DNS provider?**

  * Disable DNS proxying for all records associated with your subdomain. One-click setup does this for you by adding the records in **DNS only** mode.
  * Cloudflare sometimes adds CAA records that aren't visible in the DNS panel. To see them, run `dig caa yourwebsite.com`, replacing `yourwebsite.com` with your domain.
  * Cloudflare's [CNAME flattening](https://developers.cloudflare.com/dns/cname-flattening/) can prevent CNAME validation from working. Disable it if you have validation issues with Cloudflare DNS.
</Info>

## 3. Configure the JavaScript agent

Once your subdomain is active, update the JavaScript agent [`endpoints`](/reference/js-agent-start-function#endpoints) property to point to your subdomain.

<CodeGroup>
  ```ts CDN theme={"theme":"github-dark-dimmed"}
  <script>
    // Initialize the agent at application startup:
    // The JavaScript agent will now download from your new subdomain
    const fpPromise = import('https://metrics.yourwebsite.com/web/v4/PUBLIC_API_KEY')
      .then(Fingerprint => Fingerprint.start({
        endpoints: 'https://metrics.yourwebsite.com',
      }));

    // When you need the visitor identifier:
    fpPromise
      .then(fp => fp.get())
      .then(result => console.log(result.visitor_id));

  </script>
  ```

  ```javascript NPM theme={"theme":"github-dark-dimmed"}
  import Fingerprint from '@fingerprint/agent';

  // Initialize the agent at application startup:
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://metrics.yourwebsite.com',
  });

  // When you need the visitor identifier:
  fp.get().then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

This snippet is also available in the dashboard on the subdomain setup page, prefilled with your custom subdomain.

<Info>
  **Notes:**

  * The endpoint subdomain should match the domain of your website.
  * If you use a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) on your website, add the custom subdomain to the `connect-src` directive of your policy. See [the CSP guide](/docs/js-agent-csp) for more details.
  * If you issued a wildcard SSL certificate, the URL shows an asterisk, for example `*.yourwebsite.com`. Replace the asterisk with the subdomain you plan to use, for example `metrics.yourwebsite.com`.
</Info>

## Manage subdomains with the Management API

Instead of the dashboard, you can manage the full subdomain lifecycle programmatically with the [Management API](/reference/management-api). This is useful when you automate your workspace setup, provision a subdomain per customer, or manage subdomains from a CI/CD pipeline. A subdomain works the same way whether you create it in the dashboard or through the API, and subdomains appear in both places regardless of how you created them.

One-click setup with Domain Connect is only available in the dashboard, because it requires you to authorize the change with your DNS provider in a browser. With the API, add the returned DNS records to your provider yourself.

To use these endpoints, you need a [Management API key](/reference/management-api-authentication). All requests use the base URL `https://management-api.fpjs.io` and follow the standard Management API [authentication](/reference/management-api-authentication) and [versioning](/reference/management-api-versioning) conventions.

### Available endpoints

* [Register a subdomain](/reference/subdomainscontroller_create) (`POST /subdomains`): Registers the subdomain and returns every DNS record you need, the verification `CNAME` and the routing `A` records, in a single response.
* [List subdomains](/reference/subdomainscontroller_findall) (`GET /subdomains`): Lists every subdomain in the workspace and its status. Filter by `status` to find, for example, subdomains still in the `pending` state.
* [Get subdomain](/reference/subdomainscontroller_findone) (`GET /subdomains/{id}`): Retrieves a single subdomain with its DNS records and current status.
* [Verify subdomain](/reference/subdomainscontroller_verify) (`POST /subdomains/{id}/verify`): Triggers an on-demand DNS check instead of waiting for the next background check. Use this right after you add your DNS records.
* [Delete subdomain](/reference/subdomainscontroller_delete) (`DELETE /subdomains/{id}`): Deletes the subdomain and revokes its SSL certificate.

### Typical flow

<Steps>
  <Step title="Register the subdomain">
    Send a `POST /subdomains` request with your subdomain, then read the DNS records from the response. All records, the verification `CNAME` and both routing `A` records, are returned at once, so you can add them in a single pass.
  </Step>

  <Step title="Add the DNS records">
    Add the returned records to your DNS provider. You can add the `A` records right away; they start routing traffic once your certificate is issued.
  </Step>

  <Step title="Wait for the subdomain to become active">
    Fingerprint validates your records automatically. To check immediately, call `POST /subdomains/{id}/verify`. Poll `GET /subdomains/{id}` until the status is `active`, or pass a `webhook_url` when you register the subdomain to receive a signed callback on every status change instead of polling.
  </Step>

  <Step title="Configure the JavaScript agent">
    Once the subdomain is `active`, [configure the JavaScript agent](#3-configure-the-javascript-agent) to point at it.
  </Step>
</Steps>

The API reports the same [subdomain statuses](#subdomain-statuses), returned as the values `pending`, `active`, `timed_out`, and `failed`. A `timed_out` or `failed` subdomain is safe to delete and recreate.

<Warning>
  * Subdomains are immutable. To change a subdomain, delete it and register a new one.
  * Deleting a subdomain that is `active` stops routing its traffic to Fingerprint. Any JavaScript agent still pointing at it will fail to identify visitors, so update your agent configuration before you delete a subdomain that is in use.
</Warning>

The same limits apply as in the dashboard: each workspace can have up to 50 subdomains, or 5 during a free trial.

## Frequently asked questions

### My DNS provider doesn't offer one-click setup. What should I do?

Add the DNS records manually. The dashboard shows all of them at once, and the setup works the same way. See the [supported providers](#one-click-setup-with-domain-connect) for the current list.

### I completed the setup. How can I add more subdomains?

To add more subdomains, add them individually at any time:

1. Go to **Settings** > [**Subdomains**](https://dashboard.fingerprint.com/subdomains) and select **New subdomain**.
2. Repeat the [setup steps](/docs/custom-subdomain-setup#1-register-your-custom-subdomain) for each new subdomain.

Each workspace can have up to 50 unique subdomains. During your free trial, you can use up to 5. If you need to manage more subdomains easily, check out the [Cloudflare proxy integration](/docs/cloudflare-integration). To request additional subdomains, contact the [support team](https://fingerprint.com/support/).

## What's next

* [Start your free workspace now](https://dashboard.fingerprintjs.com/signup/)


# Bots and AI agents
Source: https://docs.fingerprint.com/docs/dashboard-bots-ai-agents

Analyze bot and AI agent traffic in the Fingerprint Dashboard, and investigate individual automation events.

The **Bots & AI agents** section of the Dashboard shows the automated traffic Fingerprint detected in your workspace, from AI agents and assistants to search crawlers and browser automation tools.

It groups your detections by category, provider, and identity, so you can see which bots reach your application and whether each one is who it claims to be. Use it to understand how much of your traffic is automated, find bots that fail identity verification, and inspect the full context of a single automation event.

<Warning>
  **Feature in Public Preview**

  The [Automation Intelligence API](/reference/automation-intelligence-api) is currently in a Public Preview testing phase. All feedback is welcome! If you encounter any issues, [contact the Fingerprint support team](https://fingerprint.com/support/).
</Warning>

## Availability

While the Automation Intelligence API is in Public Preview, the **Overview** page is available to every Fingerprint workspace on any plan.

| Surface                             | Availability                                                 |
| ----------------------------------- | ------------------------------------------------------------ |
| **Overview** page                   | All workspaces                                               |
| **Automation Intelligence API** tab | All workspaces, while the API is in Public Preview           |
| **JS Agent** tab                    | Workspaces with the Bot Detection Smart Signal in their plan |
| **Events** page                     | All workspaces, while the API is in Public Preview           |

To add Bot Detection to your plan, upgrade to Pro Plus. If you have an Enterprise plan, contact your Customer Success Manager or the [Fingerprint support team](https://fingerprint.com/support/).

## Overview page

The Overview page shows bot traffic trends across your workspace as a row of key metrics, a timeline chart, distribution lists, and an identity breakdown.

You can access the Overview page by visiting **Dashboard** > [**Bots & AI agents**](https://dashboard.fingerprint.com/bot-detection) > **Overview**.

<Frame>
  <img alt="The Bots and AI agents Overview page, showing key metrics, a timeline chart of bots by category, distribution lists, and the identity breakdown table" />
</Frame>

### Data sources

Fingerprint detects automation in two ways. Switching tabs changes the data behind every metric, chart, and list on the page.

| Tab                             | Data source                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| **Automation Intelligence API** | Automation tools detected at the edge from HTTP request metadata, without a JavaScript agent |
| **JS Agent**                    | Automation tools identified in the browser by the JavaScript agent                           |

Each tab shows the number of events recorded from that source. For guidance on which detection method fits your traffic, see [Bot Detection overview](/docs/bot-detection/overview#automation-intelligence-api-detecting-automation-without-a-browser).

### Filters

The filter bar applies to every metric, chart, and list on the page. Filter state is stored in the page URL, so **Copy link** shares the exact view you are looking at.

<Expandable title="available filters">
  | Filter          | Description                                                             |
  | --------------- | ----------------------------------------------------------------------- |
  | **Bot name**    | Find detections of a specific bot, such as `Claude-User` or `Googlebot` |
  | **Category**    | Find detections in a specific bot category                              |
  | **Provider**    | Find detections of bots operated by a specific provider                 |
  | **Identity**    | Find detections with a specific identity verification result            |
  | **Confidence**  | Find detections reported with high, medium, or low confidence           |
  | **Proxy**       | Find detections coming from an IP address detected as a proxy           |
  | **VPN**         | Find detections coming from an IP address detected as a VPN             |
  | **Environment** | Find detections associated with a specific environment                  |
</Expandable>

### Key metrics

The key metrics show the size and composition of your bot traffic for the selected period, each with a change compared to the previous period.

| Metric           | Description                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| **Total events** | Number of events recorded for the selected data source                                             |
| **Total bots**   | Number of events classified as a bot, and the share of all events they represent                   |
| **AI traffic**   | Share of bot detections that came from an AI category, such as AI agents, assistants, and crawlers |
| **Trusted**      | Share of bot detections with a verified identity                                                   |
| **Spoofed**      | Share of bot detections that claim a public identity but fail verification                         |
| **Unknown**      | Share of bot detections that do not publish a verifiable identity                                  |

**Spoofed** and **Unknown** are highlighted only when the count is above zero.

### Timeline charts

The timeline chart plots one view of your bot traffic over time. Select the chart from the dropdown above it, and switch between **Hourly** and **Daily** granularity.

| Timeline chart            | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| **Bots by category**      | Shows detected bots over time, split by category          |
| **AI agents by provider** | Shows AI bot traffic over time, split by provider         |
| **Trusted bots**          | Shows trusted bot detections over time, split by identity |
| **Total bots**            | Shows total events and detected bots over time            |
| **Spoofed bots**          | Shows spoofed bot detections over time                    |
| **Unknown bots**          | Shows unknown bot detections over time                    |

### Distribution lists

The distribution lists rank the entities that generated the most detections for your current filters.

| Distribution list  | Description                                      |
| ------------------ | ------------------------------------------------ |
| **Top bot names**  | The individual bots detected most often          |
| **Top providers**  | The bot providers generating the most detections |
| **Top categories** | The most common bot categories detected          |

### Identity breakdown

The identity breakdown is a matrix of bot categories against identity results, with the number of detections in each cell. Use it to see how trust varies by category. Verified AI assistants and unknown AI agents are different kinds of traffic, even though both appear as bots.

<Expandable title="identity results">
  | Identity     | Description                                                                            |
  | ------------ | -------------------------------------------------------------------------------------- |
  | **Verified** | Well-known bot with publicly verifiable identity, directed by the bot provider         |
  | **Signed**   | Bot that signs its platform via Web Bot Auth, directed by the bot provider's customers |
  | **Unknown**  | Bot that does not publish a verifiable identity                                        |
  | **Spoofed**  | Bot that claims a public identity but fails verification                               |
</Expandable>

<Expandable title="bot categories">
  * **AI Agent**
  * **AI Assistant**
  * **AI Browser**
  * **AI Crawler**
  * **AI Search**
  * **Advertising and Marketing**
  * **Aggregator**
  * **Browser Automation**
  * **Ecommerce**
  * **Monitoring and Analytics**
  * **Scraping**
  * **Search Engine Crawler**
  * **Search Engine Optimization**
  * **Security**
  * **Other**
  * **Unknown**
</Expandable>

To register your own bot so it is detected with a verified identity, use **Submit bot** on the Overview page, or see [Web Bot Auth implementation](/docs/bot-detection/web-bot-auth-implementation).

## Events page

The Events page lists individual automation events, so you can find a specific event and open its full details.

You can access the Events page by visiting **Dashboard** > [**Bots & AI agents**](https://dashboard.fingerprint.com/bot-detection) > **Events**.

<Frame>
  <img alt="The Events page, showing the activity scrubber above the filter bar and a table of individual bot events" />
</Frame>

<Info>
  The Events page lists events recorded with the Automation Intelligence API only. To investigate bots detected by the JavaScript agent, use the [Identification](/docs/analytics#identification-events) page and filter by bot detection.
</Info>

Above the filter bar, the activity scrubber shows event volume across the whole retention window. Drag the selection to narrow the table to a shorter period, or use the date range picker for a fixed range.

The Events page uses the same filters as the Overview page, plus two more:

| Filter           | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| **Bot detected** | Find only events that were, or were not, classified as a bot |
| **IP address**   | Find events coming from a specific IP address                |

Select any row to open its event details.

<Expandable title="Available columns">
  * **Date**
  * **Bot**
  * **Identity**
  * **Category**
  * **URL**
  * **IP Address**
  * **Country**
  * **Provider**
  * **Confidence**
  * **Proxy**
  * **VPN**
  * **Event ID**
</Expandable>

## Event details page

The event details page shows the full context Fingerprint recorded for a single automation event.

<Frame>
  <img alt="The event details page, showing the bot identity card, geolocation with a map, network details, and VPN and proxy results" />
</Frame>

On the page you can find:

1. **Bot identity**: the category, provider, name, and confidence of the detection. The card is titled with the identity result, and reads **Bot not detected** when the event was not classified as a bot.
2. **Geolocation**: the IP address, country, city, timezone, coordinates, postal code, ASN, and a map of the approximate location.
3. **Network**: the origin, referrer, and User-Agent of the request.
4. **VPN**: whether a VPN was detected, with confidence and the methods that contributed to the result.
5. **Proxy**: whether a proxy was detected, with confidence.

Use **Show JSON** to explore the entire event payload, and **Copy link** to share the event with your team.

## Data retention

Retention differs by data source, because Automation Intelligence API events are stored separately from identification events.

| Data source                     | Available history                                         |
| ------------------------------- | --------------------------------------------------------- |
| **Automation Intelligence API** | Up to the last 7 days, while the API is in Public Preview |
| **JS Agent**                    | Up to the last 30 days                                    |

## Related guides

<Columns>
  <Card title="Bot Detection overview" icon="bot" href="/docs/bot-detection/overview">
    How Fingerprint detects AI agents, browsers, and automation tools, and what each result means.
  </Card>

  <Card title="Automation Intelligence API" icon="code" href="/reference/automation-intelligence-api">
    Detect automation from HTTP request metadata alone, without a JavaScript agent.
  </Card>

  <Card title="Bot Directory" icon="book-open" href="/docs/bot-detection/bot-directory">
    The bots and AI agents Fingerprint can detect, with their result types.
  </Card>
</Columns>


# Deploy Fastly Compute Proxy Integration Manually
Source: https://docs.fingerprint.com/docs/deploy-fastly-compute-manually



<Note>
  **Before you start: Read the general Fastly Compute guide**

  This document only covers deploying the Fingerprint Fastly Compute proxy integration using the Fastly web interface. It assumes you have already read the general [Fastly Compute guide](/docs/fastly-compute-proxy-integration) and completed the [step 1](/docs/fastly-compute-proxy-integration#step-1-create-a-fingerprint-proxy-secret).
  If you want to use Terraform instead of the Fastly web interface to install the integration, see [Deploy Fastly Compute using Terraform](/docs/deploy-fastly-compute-using-terraform).
</Note>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).
</Warning>

## Step 2.1: Create a Compute Service

Create a Compute service in your Fastly account.

1. Go to [Fastly Compute services](https://manage.fastly.com/compute).
2. Click **Create service** > **Create an empty service**.
3. On the top of the page, click **Options** > **Edit service name**.
4. Give it a readable name, for example, `fingerprint-fastly-compute-proxy-integration`, and click **Apply**.

## Step 2.2: Add a domain to the service

To get the proxy integration's accuracy benefits, we recommend using a subdomain of the website you want to use Fingerprint on, for example, `metrics.yourwebsite.com`.

To avoid ad blockers, do not use subdomains like `fingerprint`, `fpjs`, and other fingerprint-related terms.

1. Inside the service configuration left-hand menu, click **Domains** > **Add domain**.
2. Input your domain for the proxy integration, for example, `metrics.yourwebsite.com`.
3. Click **Create** to save changes.

<Note>
  **Safari accuracy on non-Fastly websites**

  For maximum accuracy, both your website and your proxy integration should be served by Fastly.

  You can use the Fastly Compute proxy integration even if your website is not served by Fastly, but this setup will likely limit Safari cookie lifetime to 7 days, resulting in lower accuracy. Because your website and the proxy integration will likely have different IP ranges, Safari will apply the same cookie lifetime cap as for third-party CNAME cloaking. This is still an improvement over third-party cookies getting blocked entirely by Safari.
</Note>

## Step 2.3: Configure the service backend in Fastly

Fingerprint API is available in three different [regions](/docs/regions): `api.fpjs.io` (Global), `eu.api.fpjs.io` (EU), and `ap.api.fpjs.io` (Asia). Use the right regional hostname depending on your Fingerprint workspace data region.

1. Go back to [Compute services](https://manage.fastly.com/compute) and open the configuration of your service.
2. Inside the service configuration left-hand menu, click **Origins**.
3. Under **Hosts**, type `fingerprint` and click **Add**.
4. Click **Edit** on the created host.
   * Keep the name as `fingerprint`. The proxy integration expects this exact name.
   * Set the **Address** and **Override host** to the regional Fingerprint API host for your workspace:
     * `api.fpjs.io` - Global (US)
     * `eu.api.fpjs.io` - EU
     * `ap.api.fpjs.io` - Asia
   * Click **Update** to save changes.

## Step 2.4: Add a secret store to the service

1. In Fastly, navigate to **Resources** > [**Secret stores**](https://manage.fastly.com/resources/secret-stores).
2. Click **Create store**.
3. Name the config store `Fingerprint_Compute_Secret_Store_<SERVICE_ID>`, where the suffix is your proxy integration's [Compute Service ID](https://docs.fastly.com/en/guides/about-services). Make sure you don't have any spaces in the Secret store name after copy-pasting your service ID.
4. Click **Create**.
5. In the **Linked Services** tab, click on **Link service** and select `fingerprint-fastly-compute-proxy-integration`.
6. Click **Next**, select the current (draft) version of your service, and click **Link only**.
7. Click **Finish**.
8. Click **Add item** and set `PROXY_SECRET` to the proxy secret value you generated in [Step 1](/docs/fastly-compute-proxy-integration#step-1-create-a-fingerprint-proxy-secret).

<Note>
  **Note: Proxy secret required**

  Proxied identification requests without a valid proxy secret will result in an authentication error and not receive identification results.
</Note>

## Step 2.5: Deploy the proxy package and activate your service

Deploy the proxy service code to your Fastly Compute Service.

1. Go to the [latest release](https://github.com/fingerprintjs/fastly-compute-proxy/releases/latest) in the Fastly Compute Proxy Integration GitHub Repository.
2. Download `fingerprint-fastly-compute-proxy-integration.tar.gz` to your computer.
3. Inside Fastly, navigate to **Compute** > [**Compute services**](https://manage.fastly.com/compute), open your proxy integration service, and switch to the **Service configuration** tab.
4. In the left-hand menu, click **Package**.
5. Click to **Browse For Package** and upload the `fingerprint-fastly-compute-proxy-integration.tar.gz` package.
6. Click **Activate** in the top right corner of the page (if you see **Validating** instead, wait for it to complete).

Wait a couple of minutes for the activation. You can go to `metrics.yourwebsite.com/status` to verify that your integration is running.

## Step 2.6: Issue a TLS certificate for your subdomain

1. Inside the Fastly Dashboard, navigate to **Domains** > **TLS Management** > [**Domains**](https://manage.fastly.com/network/domains).
2. Click **Secure domain** or **Secure another domain**.
3. Select **Use certificates Fastly obtains for you**.
4. Enter your domain (for example `metrics.yourwebsite.com`) and click **Add**.
5. Configure *Certification Authority* and *TLS configuration* according to your needs and click **Submit**.
6. Follow the instructions on the screen to [verify ownership of your domain](https://docs.fastly.com/en/guides/setting-up-tls-with-certificates-fastly-manages#verifying-domain-ownership). This usually involves creating a CNAME DNS record on your domain like `_acme-challenge.metrics.yourwebsite.com`.

Give Fastly some time to verify the DNS record. Once verified, Fastly will issue a certificate for your domain and display a green **Issued** status.

## Step 2.7: Point your subdomain to Fastly

Once your domain is verified and active, you need to [choose the right hostname for your DNS record](https://docs.fastly.com/en/guides/working-with-cname-records-and-your-dns-provider#choosing-the-right-fastly-hostname-value-for-your-cname-record).

1. Go to **Security** > **TLS Management** > [**Domains**](https://manage.fastly.com/network/domains).
2. Find your domain and under *TLS configuration and DNS details,* click **View/Edit**.
3. The **CNAME records** section contains the value for your CNAME record, for example, `t.sni.global.fastly.net`.
4. [Add a subdomain CNAME record](https://docs.fastly.com/en/guides/working-with-cname-records-and-your-dns-provider#setting-up-the-cname-record-with-your-dns-provider) to your domain's DNS and point it to the Fastly hostname from the previous step. For example:
   ```txt theme={"theme":"github-dark-dimmed"}
   metrics.yourwebsite.com.    3600    CNAME    t.sni.global.fastly.net.
   ```

## Step 3: Configure the client agent

Go back to the general Fastly Compute guide to [Configure the Fingerprint client agent to use your service](/docs/fastly-compute-proxy-integration#step-3-configure-the-fingerprint-client-agent-to-use-your-service).


# Deploy Fastly Compute Proxy Integration with Terraform
Source: https://docs.fingerprint.com/docs/deploy-fastly-compute-using-terraform



<Note>
  **Before you start: Read the general Fastly Compute guide**

  This document only covers deploying the Fingerprint Fastly Compute proxy integration using the [Terraform module](https://github.com/fingerprintjs/terraform-fastly-compute-fingerprint-proxy-integration). It assumes you have already read the general [Fastly Compute guide](/docs/fastly-compute-proxy-integration) and completed the [step 1](/docs/fastly-compute-proxy-integration#step-1-create-a-fingerprint-proxy-secret).
  If you want to deploy manually using the Fastly web interface instead of the Terraform module to install the integration, see [Deploy Fastly Compute manually](/docs/deploy-fastly-compute-manually).
</Note>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).
</Warning>

## Step 2.1: Create an empty Fastly Compute service

Due to Terraform's resource dependency limitations, you must create an empty Fastly Compute service using the Fastly web interface before using the Terraform module:

1. Log in to your [Fastly web interface](https://manage.fastly.com/).
2. Navigate to **Compute** > **Create service** and click **Create an Empty Service**.
3. Set a name that suits you, for example, `fingerprint-fastly-compute-proxy-integration`.
4. Copy the Compute Service ID displayed below the service name at the top of the page. You'll need it in the next steps to import the service into the Terraform state.

## Step 2.2: Get a Fastly API token

Grab your existing Fastly API token or [create a new one](https://manage.fastly.com/account/personal/tokens/new).

* Your token needs to have a `global` scope.
* See the [Fastly documentation](https://www.fastly.com/documentation/guides/account-info/account-management/using-api-tokens/#creating-api-tokens) for more details.

## Step 2.3: Add and configure the Terraform module

Create the `main.tf` file in your Terraform project directory. Populate the properties with the values generated in the previous steps.

```terraform theme={"theme":"github-dark-dimmed"}
terraform {
  required_version = ">=1.5"
}

module "fingerprint_fastly_compute_integration" {
  source             = "fingerprintjs/compute-fingerprint-proxy-integration/fastly"
  fastly_api_token   = "FASTLY_API_TOKEN"
  integration_domain = "metrics.yourwebsite.com"
  service_id         = "FASTLY_COMPUTE_SERVICE_ID"
  region             = "us" # or "eu" or "ap"
}
```

You can see the full list of the Terraform module's variables below:

| Variable                             | Description                                                                                                                                                                                    | Required | Example                                                 |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------- |
| `fastly_api_token`                   | Your Fastly API token                                                                                                                                                                          | Required | `"ABC123...xyz"`                                        |
| `integration_domain`                 | Domain used for your proxy integration                                                                                                                                                         | Required | `"metrics.yourwebsite.com"`                             |
| `service_id`                         | ID of your empty Fastly Compute service                                                                                                                                                        | Required | `"SU1Z0isxPaozGVKXdv0eY"`                               |
| `region`                             | Region for the Fingerprint API. One of: `us`, `eu`, `ap`.                                                                                                                                      | Optional | `"us"`                                                  |
| `agent_script_download_path`         | Path to download the JavaScript agent (only required for JavaScript agent v3)                                                                                                                  | Optional | `"4fs80xgx"`                                            |
| `get_result_path`                    | Path for identification requests (only required for JavaScript agent v3)                                                                                                                       | Optional | `"vpyr9bev"`                                            |
| `integration_name`                   | Name of the Fastly service                                                                                                                                                                     | Optional | `"fingerprint-fastly-compute-proxy-integration"`        |
| `download_asset`                     | Whether to auto-download the latest release                                                                                                                                                    | Optional | `true`                                                  |
| `compute_asset_name`                 | Custom filename if not downloading the official artifact                                                                                                                                       | Optional | `"fingerprint-fastly-compute-proxy-integration.tar.gz"` |
| `asset_version`                      | GitHub release version of the proxy integration (See [GitHub releases](https://github.com/fingerprintjs/terraform-fastly-compute-fingerprint-proxy-integration/releases))                      | Optional | `"latest"`                                              |
| `manage_fastly_config_store_entries` | Manage Fastly Config Store entries via terraform, see [Fastly documentation](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/configstore_entries#manage_entries-1) | Optional | `false`                                                 |

> Updating Config Store Entries
>
> To have Terraform manage your Fastly Config Store entries, set the `manage_fastly_config_store_entries` variable to `true`.
> By default, these entries must be managed outside of Terraform.
> You can learn more about the reason behind this default behavior in the [official Fastly documentation](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/configstore_entries#manage_entries-1).
> After updating Config Store Entries, whether through Terraform or manually, it may take a few minutes for the changes to take effect.

## Step 2.4: Deploy your changes

1. Initialize Terraform:

```shell theme={"theme":"github-dark-dimmed"}
terraform init
```

2. Download the latest available proxy integration release artifact:

```shell theme={"theme":"github-dark-dimmed"}
terraform apply -target=module.fingerprint_fastly_compute_integration.module.compute_asset
```

You will get this warning: `Warning: Resource targeting is in effect...`. You can safely ignore it. The module is downloading the latest release artifact so that it can upload it as a Compute package in the next `apply` command.

3. Import your empty Compute service into Terraform state:

```shell theme={"theme":"github-dark-dimmed"}
terraform import module.fingerprint_fastly_compute_integration.fastly_service_compute.fingerprint_integration "<your service ID>"
```

> Note: The module appends the service ID to all resource names to support multiple integrations in the same Fastly account.

4. Deploy the integration:

```shell theme={"theme":"github-dark-dimmed"}
terraform apply
```

<Note>
  **Safari accuracy on non-Fastly websites**

  For maximum accuracy, both your website and your proxy integration should be served by Fastly.

  You can use the Fastly Compute proxy integration even if your website is not served by Fastly, but this setup will likely limit Safari cookie lifetime to 7 days, resulting in lower accuracy. Because your website and the proxy integration will likely have different IP ranges, Safari will apply the same cookie lifetime cap as for third-party CNAME cloaking. This is still an improvement over third-party cookies getting blocked entirely by Safari.
</Note>

## Step 2.5: Add the proxy secret

Fastly [does not allow](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/secretstore) storing or setting secrets using Terraform. Instead, you need to add the proxy secret manually:

1. Navigate to the Fastly web interface > **Resources** > **Secret Stores**.
2. Find the secret store created by Terraform: `Fingerprint_Compute_Secret_Store_<your service ID>`.
3. Open it and click **Add item**.
4. Set **Key** to `PROXY_SECRET`.
5. Set **Value** to your Fingerprint proxy secret created in [Step 1](/docs/fastly-compute-proxy-integration#step-1-create-a-fingerprint-proxy-secret).

Alternatively, you could use the Fastly API or CLI to set the secret.

<Note>
  **Note: Proxy secret required**

  Proxied identification requests without a valid proxy secret will result in an authentication error and not receive identification results.
</Note>

## Step 2.6: Configure your domain

To complete your domain setup, see [Issue a TLS certificate for your subdomain](/docs/deploy-fastly-compute-manually#step-2-6-issue-a-tls-certificate-for-your-subdomain).

## Step 3: Configure the client agent

Go back to the general Fastly Compute guide to [Configure the Fingerprint client agent to use your service](/docs/fastly-compute-proxy-integration#step-3-configure-the-fingerprint-client-agent-to-use-your-service).

## Updating the integration

The Terraform installation of the Fastly Compute proxy integration does not include any mechanism for automatic updates. To keep your integration up to date, please run `terraform apply` regularly.

## Removing the integration

To remove the integration, run:

```shell theme={"theme":"github-dark-dimmed"}
terraform destroy
```


# Deploy Fastly VCL Manually
Source: https://docs.fingerprint.com/docs/deploy-fastly-vcl-manually



<Note>
  **Before you start: Read the general Fastly VCL guide**

  This document only covers deploying the Fingerprint Fastly VCL proxy integration using the Fastly web interface. It assumes you have already read the general [Fastly VCL guide](/docs/fastly-vcl-proxy-integration) and completed the following steps:

  * [Step 1](/docs/fastly-vcl-proxy-integration#step-1-create-a-fingerprint-proxy-secret): You have issued a proxy secret in the Fingerprint Dashboard (`PROXY_SECRET`).
  * [Step 2](/docs/fastly-vcl-proxy-integration#step-2-create-integration-path-variable): You have defined the path variable for the integration (`INTEGRATION_PATH`)
    If you want to use Terraform instead of the Fastly web interface to install the integration, see [Deploy Fastly VCL using Terraform](/docs/deploy-fastly-vcl-using-terraform).
</Note>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).
</Warning>

## Step 3: Deploy Fastly VCL manually

The recommended setup is to add the VCL template to your existing Fastly CDN Service serving your website.
If your website is running on Fastly CDN, skip to [Step 3.1](#step-3-1-create-a-dictionary-for-your-cdn-service).

If your website is not running on Fastly, you can still use the Fastly proxy integration by creating a dedicated Fastly CDN Service for it and hosting it on the subdomain of your website.
If so, please follow [Step 3.0](#step-3-0-create-a-new-fastly-cdn-service-if-required) to create a new Fastly CDN Service.

<Note>
  **Safari accuracy on non-Fastly websites**

  For maximum accuracy, both your website and your proxy integration should be served by Fastly.

  You can use the Fastly VCL proxy integration even if your website is not served by Fastly, but this setup will likely limit Safari cookie lifetime to 7 days, resulting in lower accuracy. Because your website and the proxy integration will likely have different IP ranges, Safari will apply the same cookie lifetime cap as for third-party CNAME cloaking. This is still an improvement over third-party cookies getting blocked entirely by Safari.
</Note>

### Step 3.0: Create a new Fastly CDN service (if required)

1. Go to **Fastly** > **CDN Services** and click **Create Service** in the top right.
2. Fill in the form:
   1. Set **Name** to something descriptive, for example: `Fingerprint Proxy Integration`.
   2. Set **Domain** to the subdomain you have chosen for the integration, for example, `metrics.yourwebsite.com`. Avoid terms commonly blocked by ad blockers like `fingerprint`, `fpjs`, etc.
   3. Set **Origin** to something like `metrics-origin.yourwebsite.com`. This origin does not need to exist because the VCL template will forward all valid requests to the appropriate Fingerprint servers.
   4. If your website needs to be accessible on HTTP (not just HTTPS), disable **Force TLS & HSTS**.
3. Click **Activate**.
4. Using the left-hand menu, go to **Domains** > **TLS Management** > **Domains**.
5. Click **Secure my domain** and pick **Use certificates Fastly obtains for you**.
6. Enter your domain (for example, `metrics.yourwebsite.com`) and click **Add**.
7. Keep the default settings and click **Submit**.
8. Follow the instructions on the screen to [verify ownership of your domain](https://docs.fastly.com/en/guides/setting-up-tls-with-certificates-fastly-manages#verifying-domain-ownership).
   This usually involves creating a CNAME DNS record on your domain like `_acme-challenge.metrics.yourwebsite.com`.
   Give Fastly some time to verify the DNS record. After verification is completed, Fastly will issue a certificate for your domain and display a green **Active** status.
9. Once your domain is verified and active, you need to [choose the right hostname for your DNS record](https://docs.fastly.com/en/guides/working-with-cname-records-and-your-dns-provider#choosing-the-right-fastly-hostname-value-for-your-cname-record).
   1. Your hostname is likely [TLS-enabled](https://docs.fastly.com/en/guides/working-with-cname-records-and-your-dns-provider#tls-enabled-hostnames) so you can go to **Domains** > **TLS Management** > **Domains**.
   2. Find your domain and click **View details**.
   3. The **CNAME records** section contains the value for your CNAME record, for example: `t.sni.global.fastly.net`.
10. [Add a subdomain CNAME record](https://docs.fastly.com/en/guides/working-with-cname-records-and-your-dns-provider#setting-up-the-cname-record-with-your-dns-provider) to your domain's DNS and point it to the Fastly hostname from the previous step. For example:
    ```txt theme={"theme":"github-dark-dimmed"}
    metrics.yourwebsite.com.    3600    CNAME    t.sni.global.fastly.net.
    ```

### Step 3.1: Create a dictionary for your CDN Service

In this step, you are going to create a dictionary for your CDN Service and use it to store the configuration of your proxy integration.

1. Navigate to **CDN** > **CDN Services** and find your CDN service.
2. If you don't have an editable version of your service, navigate to the **Service configuration** tab, then click **Clone to edit**.
3. Using the left-hand Service menu, navigate to **Data** > **Dictionaries**.
4. Click **Create Dictionary**.
5. Set the name to `fingerprint_config` and click **Add**. The default VCL template relies on this exact name.
6. Click **Add Item** to add the following key-value pairs:
   1. Set `PROXY_SECRET` to the proxy secret you created in the Fingerprint Dashboard in [Step 1](/docs/fastly-vcl-proxy-integration#step-1-create-a-fingerprint-proxy-secret).
   2. Set `INTEGRATION_PATH` to the random string you defined in [Step 2](/docs/fastly-vcl-proxy-integration#step-2-create-integration-path-variable).

<Note>
  **Note: Proxy secret required**

  Proxied identification requests without a valid proxy secret will result in an authentication error and not receive identification results.
</Note>

### Step 3.2: Download the Fastly VCL template

Go to [the latest integration release on GitHub](https://github.com/fingerprintjs/fastly-vcl-proxy/releases/latest), and download the artifact named `fingerprint-pro-fastly-vcl-integration.vcl`.

### Step 3.3: Upload VCL template

1. Using the left-hand Service menu, navigate to **VCL** > **Custom VCL** and click **Upload custom VCL**.
2. Set a name that suits you, for example, `fingerprint_proxy_integration`.
3. Upload the `fingerprint-pro-fastly-vcl-integration.vcl` file that you've downloaded in the previous step.
4. Click **Add**.

### Step 3.4: Activate your version and verify your setup

1. Scroll up to the Service version toolbar and click **Activate** to deploy your changes.
2. Go to `https://metrics.yourwebsite.com/INTEGRATION_PATH/status`. You should see an integration status page showing the template version and a checklist of the set dictionary variables.

## Step 4: Configure the client agent

Go back to the general Fastly VCL guide to [Configure the Fingerprint client agent to use your service](/docs/fastly-vcl-proxy-integration#step-4-configure-the-fingerprint-javascript-agent-on-your-client).


# Deploy Fastly VCL using Terraform Module
Source: https://docs.fingerprint.com/docs/deploy-fastly-vcl-using-terraform



<Note>
  **Before you start: Read the general Fastly VCL guide**

  This document only covers deploying the Fingerprint Fastly VCL proxy integration using the official [Terraform module](https://github.com/fingerprintjs/terraform-fastly-vcl-fingerprint-proxy-integration). It assumes you have already read the general [Fastly VCL guide](/docs/fastly-vcl-proxy-integration) and completed the following steps:

  * [Step 1](/docs/fastly-vcl-proxy-integration#step-1-create-a-fingerprint-proxy-secret): You have issued a proxy secret in the Fingerprint Dashboard (`PROXY_SECRET`).
  * [Step 2](/docs/fastly-vcl-proxy-integration#step-2-create-integration-path-variable): You have defined the path variable for the integration (`INTEGRATION_PATH`)
    If you want to deploy manually using the Fastly web interface instead of the Terraform module to install the integration, see [Deploy Fastly VCL manually](/docs/deploy-fastly-vcl-manually).
</Note>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).
</Warning>

## Step 3.1: Get a Fastly API token

Grab your existing Fastly API token or [create a new one](https://manage.fastly.com/account/personal/tokens/new).

* Your token needs to have a `global` scope.
* See the [Fastly documentation](https://www.fastly.com/documentation/guides/account-info/account-management/using-api-tokens/#creating-api-tokens) for more details.

## Step 3.2: Add and configure the Terraform module

Create the `main.tf` file in your Terraform project directory. Populate the properties with the values generated in the previous steps.

```terraform theme={"theme":"github-dark-dimmed"}
  terraform {
    required_version = ">=1.5"
  }
  module "fingerprint_fastly_vcl_integration" {
    source                     = "fingerprintjs/vcl-fingerprint-proxy-integration/fastly"
    fastly_api_token           = "FASTLY_API_TOKEN"
    integration_domain         = "metrics.yourwebsite.com"
    integration_path           = "INTEGRATION_PATH"
    main_host                  = "origin.mydomain.com" # Your website's origin server domain
    proxy_secret               = "abcdef01234"
  }
```

* Proxied identification requests without a valid proxy secret will result in an authentication error and not receive identification results.
* This module configures a Fastly dictionary named `fingerprint_config` by default. You can change it using the `dictionary_name` variable, for example to avoid conflicts with your existing Fastly dictionaries.
  If you want to change the `dictionary_name`, you must also use a [custom VCL asset](https://github.com/fingerprintjs/terraform-fastly-vcl-fingerprint-proxy-integration?tab=readme-ov-file#using-a-custom-vcl-asset-optional).
  In that case, skip the download step, place your file at `<project root>/assets/my_vcl_file.vcl`, and set `vcl_asset_name` to `my_vcl_file.vcl`.

You can see the full list of the Terraform module's variables below:

| Variable                         | Description                                                                                                                                                                                   | Required | Example                                        |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------- |
| `fastly_api_token`               | Your Fastly API token                                                                                                                                                                         | Required | `"ABC123...xyz"`                               |
| `integration_domain`             | Domain used for the proxy integration                                                                                                                                                         | Required | `"metrics.yourwebsite.com"`                    |
| `main_host`                      | Your origin server domain                                                                                                                                                                     | Required | `"yourwebsite.com"`                            |
| `proxy_secret`                   | Your Fingerprint proxy secret                                                                                                                                                                 | Required | `"9h7jk2s1"`                                   |
| `integration_path`               | Path prefix for proxy requests                                                                                                                                                                | Required | `"kyfy7t0a"`                                   |
| `dictionary_name`                | Name of the Fastly Dictionary for config values                                                                                                                                               | Optional | `"fingerprint_config"`                         |
| `integration_name`               | Name of the Fastly CDN service                                                                                                                                                                | Optional | `"fingerprint-fastly-vcl-proxy-integration"`   |
| `download_asset`                 | Whether to auto-download the latest VCL release                                                                                                                                               | Optional | `true`                                         |
| `vcl_asset_name`                 | Custom VCL asset file if not downloading the official one                                                                                                                                     | Optional | `"fingerprint-pro-fastly-vcl-integration.vcl"` |
| `asset_version`                  | GitHub release version used for the VCL asset (See [GitHub releases](https://github.com/fingerprintjs/terraform-fastly-vcl-fingerprint-proxy-integration/releases))                           | Optional | `"latest"`                                     |
| `manage_fastly_dictionary_items` | Manage Fastly Dictionary items via terraform, see [Fastly documentation](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/service_dictionary_items#manage_items-1) | Optional | `false`                                        |

> Updating Dictionary Items
>
> To have Terraform manage your Fastly Dictionary items, set the `manage_fastly_dictionary_items` variable to `true`.
> By default, these items — `integration_path`, and `proxy_secret` — must be managed outside of Terraform.
> You can learn more about the reason behind this default behavior in the [official Fastly documentation](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/service_dictionary_items#manage_items-1).
> After updating Dictionary Items, whether through Terraform or manually, it may take a few minutes for the changes to take effect.

## Step 3.3: Deploy your changes

1. Initialize Terraform:

   ```shell theme={"theme":"github-dark-dimmed"}
   terraform init
   ```

2. Import the VCL asset into the Terraform state:

   ```shell theme={"theme":"github-dark-dimmed"}
   terraform apply -target=module.fingerprint_fastly_vcl_integration.module.vcl_asset
   ```

   You will get this warning: `Warning: Resource targeting is in effect...`. You can safely ignore it. The module is downloading the latest release artifact so that it can upload it as a VCL file in the next `apply` command.

3. Deploy the integration:

   ```shell theme={"theme":"github-dark-dimmed"}
   terraform apply
   ```

   <Note>
     **Safari accuracy on non-Fastly websites**

     For maximum accuracy, both your website and your proxy integration should be served by Fastly.

     You can use the Fastly VCL proxy integration even if your website is not served by Fastly, but this setup will likely limit Safari cookie lifetime to 7 days, resulting in lower accuracy. Because your website and the proxy integration will likely have different IP ranges, Safari will apply the same cookie lifetime cap as for third-party CNAME cloaking. This is still an improvement over third-party cookies getting blocked entirely by Safari.
   </Note>

## Step 4: Configure your domain

If you are creating a dedicated Fastly service for this integration, go to [Step 3.0: Create a new Fastly CDN Service](/docs/fastly-vcl-proxy-integration#step-3-add-fingerprint-vcl-to-your-fastly-cdn-service) and follow sub-steps 4 to 10 to complete your domain setup.

## Step 5: Configure the client agent

Go back to the general Fastly VCL guide to [Configure the Fingerprint client agent to use your service](/docs/fastly-vcl-proxy-integration#step-4-configure-the-fingerprint-javascript-agent-on-your-client).

## Updating the integration

The Terraform installation of the Fastly VCL proxy integration does not include any mechanism for automatic updates.
To keep your integration up to date, run `terraform apply` regularly.

## Removing the integration

To remove the integration, run:

```shell theme={"theme":"github-dark-dimmed"}
terraform destroy
```


# C#/.NET Server Quickstart
Source: https://docs.fingerprint.com/docs/dotnet-server-quickstart

Get started using the C#/.NET Server SDK

## Overview

In this quickstart, you'll add Fingerprint to a [C# ASP.NET Core](https://dotnet.microsoft.com/en-us/apps/aspnet) server using [ASP.NET APIs](https://dotnet.microsoft.com/en-us/apps/aspnet/apis) to prevent fraudulent account creation.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. You can flag and block suspicious users by identifying the device behind each sign-up attempt, login, or transaction.

In this quickstart, you'll learn how to:

* Set up a ASP.NET Core API server with a Fingerprint integration
* Retrieve visitor identification data using the Server API
* Block bots and suspicious devices
* Prevent multiple signups from the same device

This guide focuses on the backend integration and must be completed after identifying a visitor and generating an event ID. **Before starting this quickstart, start with one of the [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview) quickstarts to see how to identify a visitor in your frontend.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* **A completed frontend or mobile Fingerprint implementation (See the quickstarts)**
* [.NET SDK](https://learn.microsoft.com/en-us/dotnet/core/install/) (.NET 8.0 or later)
* Your favorite code editor
* Basic knowledge of C# and .NET

## 1. Get your secret API key

<Note>
  Before starting this quickstart, you should already have a frontend Fingerprint implementation
  that sends the `event_id` to your server. If not, pause here and check out one of our
  [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview)
  quickstarts first.
</Note>

If you're ready:

1. Sign in and go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the Fingerprint dashboard.
2. Create a new **secret API key**.
3. Copy it somewhere safe so you can use it to retrieve full visitor identification data from the Server API.

## 2. Set up your project

To get started, set up a basic server. If you already have a project you want to use, you can skip to the next section.

1. Create a new [ASP.NET](http://asp.net/) project and add the Fingerprint .NET Server SDK:

```bash Terminal theme={"theme":"github-dark-dimmed"}
dotnet new web -o fingerprint-dotnet-quickstart -f net9.0
cd fingerprint-dotnet-quickstart
dotnet add package Fingerprint.ServerSdk
```

*Note: This quickstart is written for version 8.x of the Fingerprint .NET Server SDK*

2. The `dotnet new web` command creates a starter `Program.cs` file. Replace the entire contents of `Program.cs` with the following code:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.UseUrls("http://localhost:3000");

var app = builder.Build();

app.MapPost("/api/create-account", () => Results.Ok("{ status: \"Account created!\" }"));

app.Run();
```

Here we are running the server at port 3000 and have created a new POST route for account creation. Note that the `/api/create-account` route should match what you have set up in your frontend implementation where you are sending the Fingerprint `event_id` to your server. Your server will receive the initial identification information from identifying a visitor on the frontend and use it to get the full visitor data on the backend.

## 3. Initialize Fingerprint and retrieve visitor data

Now you'll configure the Fingerprint .NET Server SDK using your secret API key and use it to fetch detailed visitor data for each signup attempt.

When making the initial visitor identification request in the frontend, you received an `event_id`. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. At the top of your `Program.cs` file, import and initialize the SDK with your secret API key just after the builder object is constructed:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
using Fingerprint.ServerSdk.Api;
using Fingerprint.ServerSdk.Extensions;
using Fingerprint.ServerSdk.Client;
using Fingerprint.ServerSdk.Model;

...

builder.Services.AddFingerprint(options =>
{
    options.AddTokens(new BearerToken("SECRET_API_KEY")); // Replace with your actual secret key
    // Uncomment and change if necessary:
    // options.Region = Region.Eu;
});
```

*For a production implementation make sure to store and reference your secret key securely.*

2. In your `/api/create-account` route, retrieve the `event_id` you are sending from the frontend and fetch the full visitor identification details with `GetEventAsync()`:

<Note>
  **requestId vs event\_id:** Depending on which quickstart you completed, your frontend may send
  either `requestId` (older SDKs) or `event_id` (v4 and newer). Both refer to the same
  identification event and work with the Server API in the same way. Use whichever value your
  frontend sends (`requestId` or `event_id`) as the event identifier below.
</Note>

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
app.MapPost("/api/create-account", async (CreateAccountRequest request, IFingerprintApi api) =>
{
    var getEvent = await api.GetEventAsync(request.EventId);
    return Results.Ok("{ status: \"Account created!\" }");
});
```

3. Add the declaration of `CreateAccountRequest` to the bottom of `Program.cs`:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
public record CreateAccountRequest(string EventId, string Username, string Password);
```

Using the `eventId` the Fingerprint server client will retrieve the full data for the visitor identification request. The returned object will contain the visitor ID, IP address, device and browser details, and Smart Signals like bot detection, incognito mode detection, and detections for VPN or virtual machine use.

You can see a full example of the event structure, and test it with your own device, in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 4. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection Smart Signal which is available only on paid plans.
</Note>

A simple but powerful way to prevent fraudulent account creation is to block automated signups that come from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

1. Continuing in your `/api/create-account` route, after getting `getEvent`, check the operation status:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
if (!getEvent.TryOk(out var result))
{
    return Results.InternalServerError("{ status: \"Internal server error!\" }");
}
```

Now we can check the bot signal returned in the object:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
if (result.Bot != BotResult.NotDetected)
{
    return Results.Problem("{ error: \"Failed to create account.\" }", statusCode: 403);
}
```

This signal returns `BotResult.Good` for known bots like search engine crawlers, `BotResult.Bad` for automation tools, headless browsers, or other signs of automation, and `BotResult.NotDetected` when no bot activity is found. You can also layer in other Smart Signals to catch more suspicious devices. For example, you can use Fingerprint's [Suspect Score](/docs/suspect-score) to determine when to add additional friction to create an account.

## 5. Prevent multiple signups from the same device

To catch repeated signups from the same device, you can use the `visitorId` from the Fingerprint identification event. By saving this ID alongside each created account, you can detect and block duplicate signups from the same device. We'll be using a simple database to demonstrate how this works with SQLite.

1. Install the SQLite package:

```bash Terminal theme={"theme":"github-dark-dimmed"}
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
```

2. At the top of your `Program.cs` file, import and initialize the database:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
using Microsoft.Data.Sqlite;
var connectionString = "Data Source=database.db";
using var connection = new SqliteConnection(connectionString);
connection.Open();

var command = connection.CreateCommand();
command.CommandText = @"
    CREATE TABLE IF NOT EXISTS accounts (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        username TEXT,
        password TEXT,
        visitorId TEXT
    )";
command.ExecuteNonQuery();

```

3. In your `/api/create-account` route handler, after getting the event and the bot detection code, extract the `visitorId`:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
var visitorId = result.Identification.VisitorId;
```

4. Then check if this device (visitor ID) has already created an account; if yes, block the account creation:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
using var checkConnection = new SqliteConnection(connectionString);
checkConnection.Open();

var checkCommand = checkConnection.CreateCommand();
checkCommand.CommandText = "SELECT COUNT(*) FROM accounts WHERE visitorId = @visitorId";
checkCommand.Parameters.AddWithValue("@visitorId", visitorId);

var count = (long?)checkCommand.ExecuteScalar();

if (count.HasValue && count > 0)
{
    return Results.Problem("{ error: \"Failed to create account.\" }", statusCode: 429);
}

// Otherwise, insert the new account
var insertCommand = checkConnection.CreateCommand();
insertCommand.CommandText = "INSERT INTO accounts (username, password, visitorId) VALUES (@username, @password, @visitorId)";
insertCommand.Parameters.AddWithValue("@username", request.Username);
insertCommand.Parameters.AddWithValue("@password", request.Password);
insertCommand.Parameters.AddWithValue("@visitorId", visitorId);
insertCommand.ExecuteNonQuery();

```

This gives you a basic system to detect and block repeat signups. You can expand on this by allowing a limited number of accounts per device, adjusting your response based on business rules, only evaluating recent signups, etc.

<Info>
  This is a minimal example to show how to use the Fingerprint .NET Server SDK. In a real
  application, make sure to implement proper security practices, especially around password handling
  and storage.
</Info>

## 6. Test your implementation

Now that everything is set up, you can test the full flow using your existing frontend.

### Before you test

If your frontend is running on a different port (like localhost:5173 or localhost:3001), you may run into CORS issues for testing. To quickly fix this for local development & testing:

1. Add the following lines in `Program.cs`, just after the builder object is constructed:

```csharp Program.cs theme={"theme":"github-dark-dimmed"}
builder.Services.AddCors(options =>
{
    options.AddDefaultPolicy(policy =>
    {
        policy.AllowAnyOrigin()
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});

var app = builder.Build(); // <- Existing code!
app.UseCors();

```

### Test the implementation

1. Start your [ASP.NET](http://asp.net/) server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
dotnet run
```

2. In your frontend, trigger a sign-up request that sends the `event_id`, `username`, and `password` to your `/api/create-account` endpoint. To see the reply messages make sure to parse and display or console log the response from your server.
3. Within your frontend, input a username and password to create a user. Then try to create another user and see that the second attempt will be rejected.
4. Bonus: Try creating an account using a headless browser.

## Next steps

You now have a working backend fraud check using Fingerprint. From here, you can expand your logic with more Smart Signals, adjust thresholds based on your risk tolerance, or introduce additional checks for suspicious users.

These same techniques apply to a wide range of fraud prevention use cases, from detecting fake reviews to blocking payment abuse or preventing account takeovers.

To go further, check out the use case tutorials for step-by-step guides tailored to specific problems you can solve with Fingerprint.

Check out these related resources:

* [.NET SDK Reference](/reference/net-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Overview
Source: https://docs.fingerprint.com/docs/fastly-compute-proxy-integration



Fingerprint Fastly Compute Proxy Integration is responsible for proxying identification and agent-download requests between your website and Fingerprint through your Fastly infrastructure. Your website does not strictly need to be behind Fastly to use this proxy integration, although that is optimal for maximum accuracy benefits.

<img alt="" />

The integration is a JavaScript WebAssembly Compute Service you can deploy to your Fastly account. The source code is [available on GitHub](https://github.com/fingerprintjs/fastly-compute-proxy).

<Warning>
  **Limitations and expectations**

  **Integration in Beta**

  This integration is currently in Beta. If you find any issues, please contact our [support team](https://fingerprint.com/support).

  **Limited to Enterprise plan**

  Support for the Fastly Compute Proxy Integration is provided only for customers on the **Enterprise** Plan.  Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).

  **Manual updates occasionally required**

  The underlying data contract in the identification logic can change to keep up with browser and device releases. Using the Fastly Compute Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.
</Warning>

## The benefits of using the Fastly Compute Proxy Integration

* Significant increase in accuracy in browsers with strict privacy features, such as Safari or Firefox.
* Cookies are now recognized as "first-party". This means they can live longer in the browser and extend the lifetime of visitor IDs.
* Ad blockers will not block the Fingerprint JavaScript agent from loading. Requests to Fingerprint domains are stopped by most ad blockers, but requests to same-site URLs are always allowed.
* Ad blockers will not block Fingerprint identification requests since they are sent to a subdomain that belongs to the same site.
* Insight and control over the identification requests that can be combined with other Fastly features like Compute and traffic reports.
* Cookie security: Fastly Compute Proxy Integration drops all the cookies sent from the origin website. The code is open-source, so you can transparently verify this behavior.
* Easy to meet compliance and auditing requirements.

## Integration setup overview

The integration setup consists of the following three steps. Each step is described in detail below.

1. Issue a proxy secret in the Fingerprint dashboard.
2. Deploy Fingerprint proxy integration Compute service in your Fastly account.
3. Configure the Fingerprint client agent on your website or mobile app.

## Step 1: Create a Fingerprint proxy secret

Issue a Fingerprint proxy secret to authenticate requests from your Fastly infrastructure.

1. Go to the [Fingerprint dashboard](https://dashboard.fingerprint.com/) and select your workspace.
2. In the left menu, click [**API keys**](https://dashboard.fingerprint.com/api-keys).
3. Click **Create Proxy Key**.
4. Give it a name, for example, `Fastly Compute proxy integration`.
5. Optionally, you can [choose an environment](/docs/multiple-environments#proxy-integrations-and-proxy-secrets) for the proxy secret.
   1. By default, the proxy secret works for all environments in your workspace.
   2. A proxy secret scoped to a specific environment can only authenticate identification requests made with a public API key from the same environment.
6. Click **Create API Key**.

You will use the proxy secret value in the following steps, so store it somewhere safe.

## Step 2: Deploy the proxy integration Compute service

You can choose from two available installation methods.

### Using Terraform

If you manage your infrastructure using Terraform, you can use the official Fastly Compute Proxy Integration Terraform module. This is the recommended method for deploying the integration. It provides a streamlined, versioned setup with fewer manual steps.

Continue to [Deploy Fastly Compute Proxy integration using Terraform](/docs/deploy-fastly-compute-using-terraform).

### Deploying Manually

If you don't use Terraform, you can manually deploy the integration using the Fastly web interface. This method requires more manual steps.

If you prefer the manual installation method, continue to [Deploy Fastly Compute Proxy integration manually](/docs/deploy-fastly-compute-manually).

## Step 3: Configure the Fingerprint client agent to use your service

Configure the Fingerprint client agent on your website or mobile app accordingly:

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  // The same pattern applies to React SDK, Vue SDK, etc.
  import * as Fingerprint from '@fingerprint/agent';

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://metrics.yourwebsite.com/',
    region: 'us',
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN installation theme={"theme":"github-dark-dimmed"}
  const url = 'https://metrics.yourwebsite.com/web/v4/PUBLIC_API_KEY';
  const fpPromise = import(url)
    .then(Fingerprint => Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: 'https://metrics.yourwebsite.com/',
      region: 'us',
    }));

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

If everything is configured correctly, you should receive the latest Fingerprint client-side script and the identification result through your Fastly Compute proxy integration.

## Monitoring and troubleshooting the integration

You can go to the integration's status page at `/status` (for example `https://metrics.yourwebsite.com/status`) to check that the integration is running and all required configuration variables have been set correctly.

Inside your [Fingerprint Dashboard](https://dashboard.fingerprint.com/integrations), go to **SDKs & integrations** > **Fastly Compute** to see the usage metrics of your integration. Here you can monitor:

* If the integration is up to date.
* How many identification requests are coming through the integration (and how many are not).
* The error rate of proxied identification requests (caused by missing or incorrect proxy secret).

The information on the status page is cached so allow a few minutes for the latest data points to be reflected.

<img alt="" />

If you have any questions, reach out to our [support team](https://fingerprint.com/support).

### Fastly logging

If your integration isn't working as expected, it can be useful to look at the Fastly Compute service logs. Fastly offers a [variety of logging options and integrations](https://www.fastly.com/documentation/guides/integrations/logging).

For simple debugging purposes, we recommend using [Fastly log-tail](https://www.fastly.com/documentation/guides/compute/testing/):

1. [Install and configure the Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli/#installing) on your machine.
2. Run `fastly log-tail --service-id <SERVICE_ID>` to see a stream of log messages from the integration Compute service.

## Keeping your integration up to date

The Fastly Compute proxy integration does not update automatically. To stay current:

* **If you're managing your integration manually**, regularly check the [GitHub Releases](https://github.com/fingerprintjs/fastly-compute-proxy/releases/) page and follow the [manual deployment steps](/docs/deploy-fastly-compute-manually) to update your service package when needed.
* **If you're using Terraform**, refer to the [Terraform deployment guide](/docs/deploy-fastly-compute-using-terraform#updating-the-integration) to redeploy your package after reviewing the latest release.

If there is a new major version or another reason you need to update your integration, our support team will get in touch with you.

## Cost calculation

The resources required by the proxy integration fit within the Fastly Free Tier:

* The integration uses 1 out of the 5 available Origins per Compute Service.
* The integration uses 0-2 out of the 100 available Config Store Items (only if supporting JavaScript agent v3).
* By default, the integration uses 200 out of the 1000 [theoretically](https://docs.fastly.com/products/network-services-resource-limits#service-domain-and-origin-limits) available connections per Compute service. Please contact our support team if you need to configure this value.

For more details on limitations affecting your setup see [Compute resource limits](https://docs.fastly.com/products/network-services-resource-limits).


# Migrate Fastly Compute proxy integration to JavaScript agent v4
Source: https://docs.fingerprint.com/docs/fastly-compute-v3-to-v4-migration-guide



This guide covers upgrading the Fastly Compute proxy integration from `v0.3` to `v0.4`. The new version adds support for [JavaScript agent v4](/reference/migrating-from-v3-to-v4) while maintaining compatibility with v3, and also includes the following breaking changes:

* **Single backend**: The integration now uses one backend named `fingerprint` instead of region-specific backend names (`api.fpjs.io`, `eu.api.fpjs.io`, `ap.api.fpjs.io`). The `fpcdn.io` (CDN) backend has also been removed. Agent script downloads now go through the same `fingerprint` backend.
* **Plugin system removed**: Open Client Response plugins, sealed result decryption, and KV store saving are no longer supported.
* **Path variables now optional**: `AGENT_SCRIPT_DOWNLOAD_PATH` and `GET_RESULT_PATH` are only needed for backward compatibility with JavaScript agent v3.

## Migration overview

1. Upgrade the proxy integration to v0.4. Choose the migration path that matches how you deployed your integration: [using Terraform](#migrate-using-terraform) or [manually](#migrate-manually).
2. [Switch to JavaScript agent v4](#switch-to-javascript-agent-v4).
3. [Remove the plugin configuration resources](#removing-plugin-configuration-resources-optional) (if you were using them).

## Migrate using Terraform

### Step 1: Add the `region` variable

Add the `region` variable to your module configuration. Set it to the [region](/docs/regions) of your Fingerprint workspace:

```terraform theme={"theme":"github-dark-dimmed"}
module "fingerprint_fastly_compute_integration" {
  source             = "fingerprintjs/compute-fingerprint-proxy-integration/fastly"
  fastly_api_token   = "FASTLY_API_TOKEN"
  integration_domain = "metrics.yourwebsite.com"
  service_id         = "FASTLY_COMPUTE_SERVICE_ID"
  region             = "us" # or "eu" or "ap" // [!code ++]
  # agent_script_download_path and get_result_path are only needed for JS agent v3
}
```

You can also remove `kv_store_enabled = true` if you had it set, see [Removing plugin configuration resources](#removing-plugin-configuration-resources-optional) for more details.

### Step 2: Apply the Terraform changes

```shell theme={"theme":"github-dark-dimmed"}
terraform apply
```

Terraform automatically replaces the old region-specific backends and the `fpcdn.io` backend with a single `fingerprint` backend. If you had `kv_store_enabled = true`, the KV Store is also destroyed.

## Migrate manually

### Step 1: Update the proxy package

1. Go to the [latest release](https://github.com/fingerprintjs/fastly-compute-proxy/releases/latest) in the Fastly Compute Proxy Integration GitHub repository and download `fingerprint-fastly-compute-proxy-integration.tar.gz`.
2. In Fastly, open your proxy integration Compute service and go to **Package**.
3. Upload the new package and click **Activate**.

### Step 2: Replace the service backends

Replace all existing backends with a single backend named `fingerprint`:

1. In Fastly, open your proxy integration Compute service and go to **Origins**.
2. Add a new backend:
   * Set the **Name** to `fingerprint`. The proxy integration expects this exact name.
   * Set the **Address** and **Override host** to the Fingerprint API host for your workspace region:
     * `api.fpjs.io` — Global (US)
     * `eu.api.fpjs.io` — EU
     * `ap.api.fpjs.io` — Asia
3. Delete the old region-specific backends (`api.fpjs.io`, `eu.api.fpjs.io`, `ap.api.fpjs.io`) and the CDN backend (`fpcdn.io`).
4. Click **Activate** to deploy the changes.

## Switch to JavaScript agent v4

With the proxy upgraded, update your JavaScript agent to v4. See [Migrating from JavaScript agent v3 to v4](/reference/migrating-from-v3-to-v4) for more details.

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro' // [!code --]
  import * as Fingerprint from '@fingerprint/agent' // [!code ++]

  const fpPromise = FingerprintJS.load({ // [!code --]
  const fp = Fingerprint.start({ // [!code ++]
    apiKey: 'PUBLIC_API_KEY',
    scriptUrlPattern: [ // [!code --:4]
      'https://metrics.yourwebsite.com/AGENT_SCRIPT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
      FingerprintJS.defaultScriptUrlPattern,
    ],
    endpoint: [ // [!code --:4]
      'https://metrics.yourwebsite.com/GET_RESULT_PATH?region=us',
      FingerprintJS.defaultEndpoint,
    ],
    endpoints: 'https://metrics.yourwebsite.com/', // [!code ++]
    region: 'us', // [!code ++]
  })
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  const fpPromise = import( // [!code --]
  const fp = import( // [!code ++]
    'https://metrics.yourwebsite.com/AGENT_SCRIPT_DOWNLOAD_PATH?apiKey=PUBLIC_API_KEY' // [!code --]
    'https://metrics.yourwebsite.com/web/v4/PUBLIC_API_KEY' // [!code ++]
  ).then((FingerprintJS) => FingerprintJS.load({ // [!code --]
  ).then((Fingerprint) => Fingerprint.start({ // [!code ++]
    endpoint: [ // [!code --:4]
      'https://metrics.yourwebsite.com/GET_RESULT_PATH?region=us',
      FingerprintJS.defaultEndpoint,
    ],
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://metrics.yourwebsite.com/', // [!code ++]
    region: 'us', // [!code ++]
  }))
  ```
</CodeGroup>

> Note: The `?region=us` query parameter inside the `endpoints` URL is no longer needed.

Once all your clients are on v4, you can also remove `AGENT_SCRIPT_DOWNLOAD_PATH` and `GET_RESULT_PATH` from your Config Store and Terraform configuration. They are only needed for JavaScript agent v3 support.

## Removing plugin configuration resources (optional)

If you were using the [Open Client Response plugins](/docs/v3/using-open-client-response-with-fastly-compute-proxy-integration-plugins), remove the following resources from your Fastly service.

### Remove plugin configuration from your Secret Store

1. In Fastly, go to **Resources** > [**Secret stores**](https://manage.fastly.com/resources/secret-stores).
2. Open `Fingerprint_Compute_Secret_Store_<SERVICE_ID>`.
3. Delete the `DECRYPTION_KEY` item.

> Note: Terraform does not manage Secret Store items. Remove `DECRYPTION_KEY` manually if you had it set.

### Remove plugin configuration from your Config Store

1. In Fastly, go to **Resources** > [**Config stores**](https://manage.fastly.com/resources/config-stores).
2. Open `Fingerprint_Compute_Config_Store_<SERVICE_ID>`.
3. Delete `OPEN_CLIENT_RESPONSE_PLUGINS_ENABLED` and `SAVE_TO_KV_STORE_PLUGIN_ENABLED` if they exist.

### Remove the KV Store

If you had the KV Store plugin enabled, remove the associated KV Store resource.

#### Manually

1. In Fastly, go to **Resources** > [**KV Stores**](https://manage.fastly.com/resources/kv-stores).
2. Find `Fingerprint_Results_<SERVICE_ID>`, unlink it from your service, and delete it.

#### Using Terraform

1. In Terraform, remove the `kv_store_enabled` variable from your module configuration.
2. Run `terraform apply` to remove the KV Store resource.


# Overview
Source: https://docs.fingerprint.com/docs/fastly-vcl-proxy-integration



Fingerprint Fastly VCL (Varnish Configuration Language) Proxy Integration is responsible for proxying identification and agent-download requests between your website and Fingerprint through your Fastly infrastructure. The integration consists of a set of VCL rules you can add to your Fastly CDN Service. The VCL template is available on [GitHub](https://github.com/fingerprintjs/fastly-vcl-proxy/releases/latest).

<img alt="Fastly VCL Diagram" />

<Warning>
  **Limitations and expectations**

  **Limited to Enterprise plan**

  The Fastly VCL Proxy Integration is supported only for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).

  **Manual updates occasionally required**

  The underlying data contract in the identification logic can change to keep up with browser and device releases. Using the Fastly VCL Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.

  **We recommend using a subdomain instead of using the apex domain**

  Fastly recommends configuring this integration on a subdomain (e.g. `www.yourwebsite.com` or `metrics.yourwebsite.com`) rather than an apex domain (e.g. `example.com`). Apex domains cannot use CNAME records per DNS specification, and while Fastly does offer anycast IP addresses (A/AAAA records) as a workaround, these may be less performant. See [Fastly's documentation on using Fastly with apex domains](https://www.fastly.com/documentation/guides/full-site-delivery/domains-and-origins/using-fastly-with-apex-domains) for more details.
</Warning>

## The benefits of using the Fastly VCL Proxy Integration

* Significant increase in accuracy in browsers with strict privacy features, such as Safari or Firefox.
* Cookies are now recognized as “first-party.” This means they can live longer in the browser and extend the lifetime of visitor IDs.
* Ad blockers will not block our Fingerprint JavaScript agent from loading. Attempts to connect to an external URL will be stopped by most ad blockers, but attempts to connect to the same site URL will be allowed.
* Ad blockers will not block our identification requests since they are sent to the specific path or subdomain that belongs to the same site.
* Insight and control over the identification requests that can be combined with other Fastly features like VCL and traffic reports.
* With the Fastly VCL Proxy Integration, you can manage unlimited subdomains and paths and provide Fingerprint services to all your customers at any scale while benefiting from all the 1st-party integration improvements.
* Cookie security: Fastly VCL Proxy Integration drops all the cookies sent from the origin website. The code is open-source, so this behavior can be transparently verified and audited.
* Easy to meet compliance and auditing requirements.

## Integration setup overview

The integration setup consists of the following four steps. Each step is described in detail below.

1. Issue a proxy secret in the Fingerprint dashboard.
2. Create integration path variable.
3. Apply Fingerprint VCL and configuration values to your Fastly CDN Service.
4. Configure the Fingerprint JavaScript agent on your website.

## Step 1: Create a Fingerprint proxy secret

Issue a Fingerprint proxy secret to authenticate requests from your Fastly infrastructure.

1. Go to the [Fingerprint dashboard](https://dashboard.fingerprint.com) and select your workspace.
2. In the left menu, navigate to [**API keys**](https://dashboard.fingerprint.com/api-keys).
3. Click **Create Proxy Key**.
4. Give it a name, for example, `Fastly VCL proxy integration`.
5. Optionally, you can [choose an environment](/docs/multiple-environments#proxy-integrations-and-proxy-secrets) for the proxy secret.
   1. By default, the proxy secret works for all environments in your workspace.
   2. A proxy secret scoped to a specific environment can only authenticate identification requests made with a public API key from the same environment.
6. Click **Create API Key**.

You will use the proxy secret value during deployment, so store it somewhere safe.

## Step 2: Create integration path variable

You need to set the path variable for your integration you will use throughout your Fastly configuration ([Step 3.1](/docs/deploy-fastly-vcl-manually)) and the JavaScript agent configuration on your website ([Step 4](#step-4-configure-the-fingerprint-javascript-agent-on-your-client)). This value is arbitrary. Just decide what your value is and write them down somewhere.

In this guide, we will use a readable value corresponding to the variable name to make it easier to follow:

```text theme={"theme":"github-dark-dimmed"}
INTEGRATION_PATH="INTEGRATION_PATH"
```

However, your value used in production should look more like random string:

```text theme={"theme":"github-dark-dimmed"}
INTEGRATION_PATH="ore54guier"
```

That is because some ad blockers might automatically block requests from any URL containing fingerprint-related terms like "fingerprint", "fpjs", "track", etc. Random strings are the safest. So whenever you see a value like `INTEGRATION_PATH` in this guide, you should use your random value instead.

## Step 3: Add Fingerprint VCL to your Fastly CDN Service

You can choose from two available installation methods.

### Using Terraform

If you manage your infrastructure using Terraform, you can use the official Fastly VCL Proxy Integration Terraform module. This is the recommended method for deploying the integration. It provides a streamlined, versioned setup with fewer manual steps.

Continue to [Deploy Fastly VCL Proxy integration using Terraform](/docs/deploy-fastly-vcl-using-terraform).

### Deploying Manually

If you don’t use Terraform, you can manually deploy the integration using the Fastly web interface. This method requires more manual steps.

If you prefer the manual installation method, continue with [Deploy Fastly VCL Proxy integration manually](/docs/deploy-fastly-vcl-manually).

## Step 4: Configure the Fingerprint JavaScript agent on your client

Use the integration path variable created in [Step 2](#step-2-create-integration-path-variable) to construct the integration endpoint URLs.

Configure the Fingerprint JavaScript agent on your website accordingly:

<CodeGroup>
  ```javascript NPM Package theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: ['https://metrics.yourwebsite.com/INTEGRATION_PATH?region=us'],
      region: 'us',
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  const url = 'https://metrics.yourwebsite.com/INTEGRATION_PATH/web/v4/PUBLIC_API_KEY?region=us';
  const fpPromise = import(url)
  .then(Fingerprint => Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: ['https://metrics.yourwebsite.com/INTEGRATION_PATH?region=us'],
      region: 'us',
  }));

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

<Note>
  **Pay attention to differences in query parameters**

  **Pass region** to the `endpoints` URL in the following format: `?region=eu`. The value needs to reflect the [region](/docs/regions) of your application.
</Note>

If everything is configured correctly, you should receive the latest Fingerprint client-side script and the identification result through your Fastly VCL integration. If you have any questions, reach out to our [support team](https://fingerprint.com/support/?_gl=1*1f8iyeh*_ga*MTM2ODkyMjcyNS4xNzA1MDk5MjQ0*_ga_XVKDT0L5WV*MTcxNjQ1NTczOS40OC4xLjE3MTY0NTg4ODIuMTIuMC41MTAwNTMzMTA.).

## Monitoring and troubleshooting the integration

Go to **Dashboard** > [**SDKs & integrations**](https://dashboard.fingerprint.com/integrations) > **Fastly VCL** to see the status of your integration. Here you can monitor:

* If the integration is up to date.
* How many identification requests are coming through the integration (and how many are not).
* The error rate of proxied identification requests (caused by a missing, incorrect, or environment-mismatched proxy secret).

The information on the status page is cached so allow a few minutes for the latest data points to be reflected.

<img alt="Fingerprint Dashboard Fastly VCL Status Page" />

If you run into problems:

1. Go to the integration's status page at `https://metrics.yourwebsite.com/INTEGRATION_PATH/status` to check if the integration is running and all required configuration variables have been set correctly.
2. When contacting our [support team](https://fingerprint.com/support/?_gl=1*1f8iyeh*_ga*MTM2ODkyMjcyNS4xNzA1MDk5MjQ0*_ga_XVKDT0L5WV*MTcxNjQ1NTczOS40OC4xLjE3MTY0NTg4ODIuMTIuMC41MTAwNTMzMTA.), please provide them with the VCL file of your CDN service.
   1. Navigate to **CDN** > **CDN Services**, open your CDN service, and pick the **Active** version.
   2. Click **Show VCL** and then **Download**.

<img alt="Fastly Dashboard VCL Overview page" />

## Cost calculation

The resources required by the proxy integration fit within the Fastly Free Tier:

* The integration uses 3 out of the 5 available Origins per CDN Service.
* The integration uses 2 out of the 1000 available Dictionary Items.
* By default, the integration uses 200 out of the 1000 [theoretically](https://docs.fastly.com/products/network-services-resource-limits#service-domain-and-origin-limits) available connections per CDN service. Please contact our support team if you need to configure this value.

For more details and other limitations affecting your setup, please see [Fastly Network services resource limits](https://docs.fastly.com/products/network-services-resource-limits).


# Migrate from API v3 to API v4
Source: https://docs.fingerprint.com/docs/fastly-vcl-v3-to-v4-migration-guide



**Welcome!** This guide helps you migrate your Fastly VCL integration from API v3 to API v4.

You will first gather your existing integration details, then upgrade your Fastly VCL config so it can handle both v3 and v4 routes, validate v4 traffic through the proxy before changing production, update your app to JavaScript Agent v4, and finally monitor the rollout and clean up any temporary migration paths once v3 traffic has fully stopped.

<Note>
  Follow the steps below in order. If you keep v3 working while you validate v4, you can roll
  forward safely and avoid user impact.
</Note>

## Step 0: Collect Inputs (no changes yet)

You should have:

* Your current integration domain (example: `https://metrics.yourwebsite.com`)
* Your current proxy secret variable (the one you already use with the v3 guide) `PROXY_SECRET`
* Your current integration path variables (the ones you already use with the v3 guide)
  * `INTEGRATION_PATH`
  * `AGENT_SCRIPT_DOWNLOAD_PATH`
  * `GET_RESULT_PATH`
  * Note: once migration is complete and your website is fully on agent v4, `AGENT_SCRIPT_DOWNLOAD_PATH` and `GET_RESULT_PATH` are no longer required
* Your public API key
* Your region (example: `us`, `eu`, `ap`)

## Step 1: Upgrade your Fastly VCL integration first

Update the VCL asset / configuration to a version that supports agent v4.
The steps below are for the manual deployment method. For Terraform, run `terraform apply` to update to the latest version.

### 1.1 Get the latest VCL file from GitHub

* Go to our [GitHub repository](https://github.com/fingerprintjs/fastly-vcl-proxy) for the Fastly VCL proxy integration.
* Open [Releases](https://github.com/fingerprintjs/fastly-vcl-proxy/releases).
* Download the [latest release](https://github.com/fingerprintjs/fastly-vcl-proxy/releases/latest) artifact for the VCL file.

### 1.2 Update your Fastly service

* In Fastly, open your CDN service and **clone** the active version.
* Replace the **corresponding VCL file** with the contents of the downloaded VCL file.
  * If you see a separate fingerprint related file you should update that.
  * If you only have main.vcl file you can just replace it.
* Publish (activate) the new version.

### 1.3 Verify

Acceptance criteria:

* The integration can still serve the v3 agent download path and v3 identification path.
* The integration can also route v4 requests, for example requests under `/web/v4/...`.

Verification ideas:

* Open `https://INTEGRATION_DOMAIN/INTEGRATION_PATH/status` and confirm the integration is healthy.
* Confirm your existing (v3) production client still works and can identify.
* Validate your v4 traffic through the proxy. Try the code snippet below.
  ```javascript NPM theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent';

  const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: ['https://metrics.yourwebsite.com/INTEGRATION_PATH?region=us'], // Replace "?region" query param with your region as well
  });

  fp.get().then((result) => console.log(result));
  ```

## Step 2: Validate v4 routing before changing your production client

Before flipping your app, test v4 through the proxy.

Options:

* Use a staging site / feature flag to load agent v4.
* Temporarily run agent v4 in a dev environment.

What to check:

* The agent script loads through the proxy (no ad blocker or CDN errors)
  * You may use browser dev tools' network tab to confirm the script is loaded from the proxy.
* Identification requests go through the proxy (not directly to Fingerprint default endpoints)
* Results are returned successfully

## Step 3: Update your application to JavaScript Agent v4

Update your website to load and initialize agent v4 using your proxy base URL.
Replace the placeholders with your values:

<CodeGroup>
  ```javascript NPM theme={"theme":"github-dark-dimmed"}
  // Replace `region` query param with your region
  // Replace `PUBLIC_API_KEY` with your public API key
  // Replace `INTEGRATION_PATH` with your integration path
  import * as Fingerprint from '@fingerprint/agent';

  const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: ['https://metrics.yourwebsite.com/INTEGRATION_PATH?region=us'], // Replace "?region" query param with your region as well
  })

  fp.get()
  .then((result) => {
      console.log(result);
  })
  .catch((err) => {
      // Optional: log errors; endpoint fallback is controlled via the `endpoints` option
      console.error(err);
  });
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  // Replace `region` query param with your region
  // Replace `PUBLIC_API_KEY` with your public API key
  // Replace `INTEGRATION_PATH` with your integration path
  const fp =
  import('https://metrics.yourwebsite.com/INTEGRATION_PATH/web/v4/PUBLIC_API_KEY?region=us').then(
    (Fingerprint) =>
      Fingerprint.start({
        apiKey: 'PUBLIC_API_KEY',
        region: 'us', // Replace with your region
        endpoints: ['https://metrics.yourwebsite.com/INTEGRATION_PATH?region=us'], // Replace "?region" query param with your region as well
      }),
  );

  fp
  .then((fp) => fp.get())
  .then((result) => {
    console.log(result);
  })
  .catch((err) => {
    // Optional: log errors; endpoint fallback is controlled via the `endpoints` option
    console.error(err);
  });
  ```
</CodeGroup>

## Step 4: Monitor and finalize

After rollout:

* Monitor proxied traffic and error rate from the integration status UI
* Confirm the majority of traffic is using v4 paths

Optional cleanup (later):

* If you introduced any temporary parallel paths for testing, remove them
* When you are confident no clients use v3, you can simplify any v3-specific configuration
  * You may remove the `AGENT_SCRIPT_DOWNLOAD_PATH` and `GET_RESULT_PATH` variables from your dictionary.


# Google Chrome Extension
Source: https://docs.fingerprint.com/docs/fingerprintjs-pro-and-chrome-extension



### Using Fingerprint in Google Chrome Extensions

A typical use-case represents getting a valid [`visitor_id`](/reference/js-agent-get-function#visitor_id) via your extension. After validating it with the [Server API](/reference/server-api) or [webhooks](/docs/webhooks), data provided by Fingerprint might be crucial for your internal decision making, user scoring, and protecting sensitive actions for your business.

There are two general strategies to integrate Fingerprint into an extension. You can get Fingerprint result by opening your website temporarily in a new window. Another way demonstrates injecting the [Fingerprint JavaScript agent](/reference/js-agent) into the website's iframe and performing fingerprinting there.

Both solutions are showcased in the [Chrome extension repository](https://github.com/fingerprintjs/fingerprintjs-pro-chrome-extension-example). The example extension is also available on the [Chrome Web Store](https://chrome.google.com/webstore/detail/fingerprintjs-example-bro/knppbjgkegnlbhddedbilnfmnkdocekn).

<Warning>
  The example extension is currently still implemented using JavaScript agent v3, see the [migration
  guide](/reference/migrating-from-v3-to-v4) for more information.
</Warning>

### New window strategy

With this approach, the Chrome extension creates a new window that points to an external website hosted by you. This website uses our Fingerprint agent to obtain the `result`. This data is then passed back to the extension using a [native communication channel](https://developer.chrome.com/docs/extensions/mv3/messaging/#external-webpage).

#### Sample use

1. Configure and serve a publicly available web page containing the Fingerprint JavaScript agent. It's recommended to use the [Custom subdomain setup](/docs/custom-subdomain-setup) or one of our cloud proxy integration to [protect the JavaScript agent from ad blockers](/docs/protecting-the-javascript-agent-from-adblockers) and increase accuracy. This website must be served over HTTPS.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// Script on your website

// Your chrome extension id
const extensionId = 'CHROME_EXTENSION_ID';

// Initialize the agent
const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY').then((Fingerprint) =>
  Fingerprint.start({
    endpoints: 'https://metrics.yourwebsite.com/',
  }),
);

fpPromise
  .then((fp) => fp.get())
  .then((result) => {
    // Pass the result back to the chrome extension
    // Note: this API is only available in chromium based browsers and only on pages served via HTTPS
    chrome.runtime.sendMessage(extensionId, {
      type: 'fpjs-result',
      data: result,
    });
  });
```

2. In the extension's `manifest.json`, add the `externally_connectable` manifest property. Make sure you've specified the `service_worker` property in the `background` section as well.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// manifest.json of your chrome extension
{
...
"externally_connectable": {
	// URL to the external site that uses our Agent
  "matches": ["https://your-website.com/*"]
},
...
"background": {
  // Name of your background script file
  "service_worker": "background.js"
},
...
}
```

3. Add the following code snippet into your background script. It will allow you to obtain results from Fingerprint inside your extension's codebase.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
let currentWindow;

async function closeCurrentWindow() {
  if (currentWindow?.id) {
    try {
      await chrome.windows.remove(currentWindow.id);
      currentWindow = undefined;
    } catch (error) {
      // Handle error
    }
  }
}

async function getFingerprint() {
  await closeCurrentWindow();

  currentWindow = await chrome.windows.create({
    url: 'WEBSITE_URL',
    type: 'popup',
    focused: false,
  });

  return new Promise((resolve) => {
    const handleExternalMsg = async (externalMessage) => {
      if (externalMessage?.type === 'fpjs-result' && externalMessage?.data?.visitor_id) {
        resolve(externalMessage.data);

        chrome.runtime.onMessageExternal.removeListener(handleExternalMsg);

        // Close created window after receving result
        await closeCurrentWindow();
      }
    };

    // Register listener for messages from our website
    chrome.runtime.onMessageExternal.addListener(handleExternalMsg);
  });
}

// Add a listener for messages from your extension requesting data from the JavaScript agent
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'get-visitor-id') {
    getFingerprint().then(sendResponse);

    // Required for async operations, otherwise, chrome won't pass the result back to the sender
    return true;
  }
});
```

4. Receive and use the `result` data in your extension's logic.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
export function getFingerprintResult() {
  return new Promise((resolve, reject) => {
    chrome.runtime.sendMessage(
      {
        type: 'get-visitor-id',
      },
      (message) => {
        if (message?.visitor_id) {
          resolve(message);
        } else {
          reject(new Error('Failed to get visitor data'));
        }
      },
    );
  });
}

getFingerprintResult().then((result) => {
  // Use result
});
```

### Iframe strategy

With this strategy, the extension appends an iframe into the DOM with the URL of the external website and communicates with it using [Window.postMessage() API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).

Alternatively, you can append the iframe into the DOM served on the extension page (e.g. in the popup). There are several benefits of not using a content script:

* Other extensions don't have access to the iframe content (e.g. adblockers).
* There are no required special permissions in the `manifest.json`.
* Several anti-fingerprinting techniques and tracking protections can't identify and block this approach.

#### Sample use

1. Configure and serve a publicly available web page containing the Fingerprint JavaScript agent. It's recommended to use the [Custom subdomain](/docs/custom-subdomain-setup). The website must be served over HTTPS.

```javascript theme={"theme":"github-dark-dimmed"}
// Script on your website

const parentOrigin = 'chrome-extension://CHROME_EXTENSION_ID';

// Check if we are in iframe
if (window.parent !== window) {
  // Initialize the agent
  const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY').then((Fingerprint) =>
    Fingerprint.start({
      endpoints: 'https://fp.yourdomain.com', // Subdomain setup URL
    }),
  );

  fpPromise
    .then((fp) => fp.get())
    .then((result) => {
      // Send the result to parent window
      window.parent.postMessage(
        {
          type: 'fpjs-result',
          data: result,
        },
        parentOrigin,
      );
    });
}
```

2. Add the following code to your extension where you need to get `result` data.

<Note>
  **DOM API and background scripts**

  With this approach, your extension needs access to the DOM API, therefore, according to the [Manifest v3 limitations](https://developer.chrome.com/docs/extensions/mv3/intro/), it's not possible to use the following snippet in the background script.
</Note>

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
export function getFingerprintResult(container) {
  const iframeUrl = new URL('https://yourwebsite.com');
  const iframe = document.createElement('iframe');

  // Apply styles to the iframe
  iframe.style.width = '100%';
  iframe.style.height = '200px';
  iframe.style.border = 'none';

  iframe.src = iframeUrl.href;

  return new Promise((resolve) => {
    const handler = (event) => {
      if (event.origin !== iframeUrl.origin || event.source !== iframe.contentWindow) {
        return;
      }

      const eventData = event.data;

      if (eventData?.type === 'fpjs-result' && eventData?.data?.visitor_id) {
        window.removeEventListener('message', handler);
        iframe.remove();
        resolve(eventData.data.visitor_id);
      }
    };

    // Listen for messages from iframe
    window.addEventListener('message', handler);
    container.appendChild(iframe);
  });
}

const container = document.querySelector('.main');

getFingerprintResult(container).then((result) => {
  // Use result
});
```

### Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/fingerprintjs-pro-chrome-extension-example).


# Next
Source: https://docs.fingerprint.com/docs/fingerprintjs-pro-nextjs



The [Fingerprint React SDK](https://github.com/fingerprintjs/react) is an easy way to integrate Fingerprint into your Next.js application. It supports all capabilities of the JavaScript agent and provides a built-in caching mechanism.

### How to install

Add `@fingerprint/react` as a dependency to your application via npm or yarn.

<CodeGroup>
  ```shell NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/react
  ```

  ```shell Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/react
  ```

  ```shell PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/react
  ```
</CodeGroup>

Wrap your application (or component) in `FingerprintProvider`. You need to specify your public API key and other configuration options based on your chosen region and active integration.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// pages/_app.tsx
import {FingerprintProvider} from '@fingerprint/react'
import {AppProps} from 'next/app'

export default function MyApp({Component, pageProps}: AppProps) {
  return (
    <FingerprintProvider
      apiKey="PUBLIC_API_KEY"
      endpoints="https://metrics.yourwebsite.com"
    >
      <Component {...pageProps} />
    </FingerprintProvider>
  )
}
```

Use the `useVisitorData` hook in your components to identify visitors.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// pages/index.tsx
import {useVisitorData} from '@fingerprint/react'

export default function Home() {
  const { isLoading, error, data, getData } = useVisitorData(
    { immediate: true },
  )

  return (
    <div>
      <button onClick={() => getData()}>
        Reload data
      </button>
      <p>VisitorId: {isLoading ? 'Loading...' : data?.visitor_id}</p>
      <p>Full visitor data:</p>
      <pre>{error ? error.message : JSON.stringify(data, null, 2)}</pre>
    </div>
  )
}
```

### Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/react). The repository also contains [an example app](https://github.com/fingerprintjs/react/tree/main/examples/next) demonstrating the usage of the library.

### Migration guide for React SDK v3.0.0

You can find the migration guide on the [React SDK page](/docs/react).


# React Native
Source: https://docs.fingerprint.com/docs/fingerprintjs-pro-react-native



<Warning>
  ### JavaScript agent v4 support coming soon

  This client SDK currently supports JavaScript agent v3. For the current v3 documentation, see [React Native SDK (v3)](/docs/v3/fingerprintjs-pro-react-native). You can also check the current [integration compatibility table](/reference/migrating-from-v3-to-v4#client-sdk-compatibility-for-javascript-agent-v4).
</Warning>


# Flow deployments on Cloudflare (Beta)
Source: https://docs.fingerprint.com/docs/flow-deployments

Deploy Fingerprint identification and protection to the edge with little to no changes to your application code.

<Warning>
  **Feature in Beta**

  This feature is currently in an open Beta testing phase. We recommend testing it inside an isolated staging environment. All feedback is welcome! If you encounter any issues, please [contact](https://fingerprint.com/support/) our support team.
</Warning>

<Note>
  **Pre-requisites**

  * A Fingerprint account with an **Admin** role.
  * A website [proxied](https://developers.cloudflare.com/dns/proxy-status/) (not DNS-only) through Cloudflare.
</Note>

**Flow** is a Fingerprint deployment method that requires little to no application code changes, currently supported for websites hosted on **Cloudflare**.

The Flow worker sits between the browser accessing your website and the origin server. It automatically handles all the steps required to identify visitors on your website and protect sensitive actions:

* It injects the JavaScript agent into the pages you define.
* For the API endpoints you define, it triggers visitor identification. Optionally, it can protect those endpoints using the Rules engine.
* Requests are naturally same-site, no need for a separate proxy integration to deal with ad blockers.

For a more detailed conceptual overview, see [How Cloudflare Flow deployments work](#how-cloudflare-flow-deployments-work).

There are two ways to use Flow workers:

* [**In combination with the Rules engine (Protection mode)**](#using-a-flow-worker-with-the-rules-engine)
* [**On its own (Monitoring mode)**](#using-a-flow-worker-on-its-own-monitoring-mode)

## Using a Flow worker with the Rules Engine

The Rules Engine allows you to define rules evaluated against the Fingerprint identification events. For example, you can define a ruleset that prevents browsers in incognito mode from creating accounts in your application. See [Rules engine](/docs/rules-engine) for more details.

One way of using the ruleset is by deploying it using a Flow worker. For example, you can protect the `POST api.yourwebsite.com/create-account` API, called from the `yourwebsite.com/signup` page.

<Note>
  You cannot protect the signup page itself, only the API endpoint it calls. Calling the protected API endpoint from the identification page is necessary to trigger visitor identification.
</Note>

1. Open your ruleset and switch to the **Settings** tab.

2. Under **Deployment**, click **Deploy with Cloudflare**.

3. Enter your **Cloudflare Account ID**, your Cloudflare **Token**, and click **Validate**.
   1. You can get your Cloudflare Account ID from the [Cloudflare Dashboard -> Workers and Pages](https://dash.cloudflare.com/?to=/:account/workers-and-pages), on the bottom right corner of the page.
   2. You need to get or create a Cloudflare token with the following permissions. [Click here to create a Cloudflare token from a pre-filled template](https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%2C%7B%22key%22%3A%22workers_routes%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%5D\&name=fingerprint.com+flow+worker+deployment\&accountId=*\&zoneId=all):
      1. `Account:Workers Scripts:Edit`
      2. `Zone:Workers Routes:Edit` for the zone the worker will use
      3. `Zone:DNS:Read` for the zone you want to deploy to

         <img alt="" />

4. Pick the [environment](/docs/multiple-environments) of the Public and Secret API keys generated for the deployment.

5. Define at least one page for identifying visitors. For example, to identify visitors on your sign-up page, add:
   1. `[no subdomain]`
   2. `yourwebsite.com`
   3. `/signup`

6. Define at least one API endpoint to protect with your ruleset. These protected APIs need to be called from the pages in the last step. They can be on a different subdomain, but must be inside the same zone. See [How Cloudflare Flow deployments work](#how-cloudflare-flow-deployments-work) for more details. For example, to protect the sign-up endpoint, add:
   1. `api.`
   2. `yourwebsite.com`
   3. `POST`
   4. `/create-account`.

7. Define the Failure mode. By default, the worker will *Fail open*, meaning it will let requests through if an unexpected identification error occurs. We recommend starting with this configuration for the initial testing, then switching to *Fail closed* for security use cases.

8. Click **Create Cloudflare worker**.

<img alt="" />

Within a few seconds, the Flow worker is deployed into your Cloudflare account.

* You can open your Cloudflare dashboard to confirm.
* You can navigate to the identification page in Incognito mode and try triggering the protected API. You will be blocked by the ruleset and receive the response you defined in your [rule action](/docs/rules-engine#rule-action).

<img alt="" />

<Warning>
  Note: The Flow worker will start intercepting protected requests and applying rules immediately after deployment. If the failure mode is set to *Fail closed*, any errors in the [request instrumentation](#how-cloudflare-flow-deployments-work) (e.g., missing or corrupted browser data) will be treated as tampering attempts and blocked with a `403` Error response from the Flow worker.

  * We recommend testing your ruleset and Flow deployment in a separate staging environment before applying it to production.
  * You can deploy the Flow worker set to *Fail open* for the initial test of your configuration.
  * You can deploy an empty or [disabled](/docs/rules-engine#ruleset-settings) ruleset first to test the Flow worker without applying any rules.
  * You can delete the Flow deployment at any time using the Fingerprint Dashboard, or even manually remove the worker from your Cloudflare dashboard if needed.
</Warning>

### Editing Flow deployments

You can update your Flow deployment any time:

1. Navigate to **\<Your ruleset>** > **Settings** tab.
2. Under **Deployment**, click **⋯ (More actions)**, then **Edit worker**.
3. Add, remove, or update the identification pages and protected APIs.
4. Click **Save and redeploy** to save your changes.

This redeploys the Flow worker with the updated configuration. Do not make manual changes to the worker code or environment variables directly through Cloudflare as they will be overwritten by Fingerprint on the next redeployment.

<img alt="" />

<Info>
  **Rules are part of the Ruleset, not the Flow deployment**

  * The Flow worker only knows its Ruleset ID. Rulesets are stored and evaluated inside the Fingerprint platform, not on Cloudflare.
  * To update rules, make changes to the Ruleset and save it. It might take up to 60 seconds for the changes to take effect on your website.
  * We recommend testing your rule changes in a separate staging ruleset and staging web environment before applying them to production.
</Info>

### Deleting Flow deployment

To delete the Flow deployment:

1. Navigate to **\<Your ruleset>** > **Settings** tab.
2. Under **Deployment**, click **⋯ (More actions)**, then **Delete worker**.
3. Confirm by typing your domain name and clicking **Delete deployment**.

This completely removes the Flow worker and its associated routes from your Cloudflare account. The ruleset itself remains stored in your Fingerprint workspace. Note that you cannot delete a deployed ruleset without removing the Flow deployment first.

## Using a Flow worker on its own (Monitoring mode)

You can deploy a Flow worker without a ruleset. This allows you to identify visitors on your website and collect data about your traffic without applying any protective actions.

To deploy a Flow worker in monitoring mode:

1. In the Fingerprint Dashboard, navigate to **Libraries & integrations** -> **Directory** ->  [**Cloudflare No-Code Worker**](https://dashboard.fingerprint.com/integrations/cloudflare-flow).
2. Click **New worker**.
3. Provide your **Cloudflare credentials**, define the **Identification pages** and **API endpoints**.
   1. It works the same as when [using Flow with the Rules engine](#using-a-flow-worker-with-the-rules-engine); see that section above for more details. The only difference is that there is no ruleset associated with the Flow worker.
   2. Note that you still need to define the API endpoints even if you are not using any ruleset. The identification page calling the API endpoint is what triggers visitor identification and sends the data to the worker, even if no protection is applied.
   3. In Monitoring mode, we recommend keeping the **Failure mode** set to *Fail open* to let requests through if an unexpected identification error occurs.
4. Click **Create Cloudflare worker** to deploy.

<img alt="" />

You can switch to the **Workers** tab to see all your workers, whether they are using rulesets or not.

<img alt="" />

Clicking on a worker opens the worker detail, where you can view, manage, or delete the worker.

<img alt="" />

## Using a Flow worker to detect bots at the edge

Flow workers can detect AI agents, AI assistants, and bots that access your pages and API endpoints.

To enable this capability, when deploying or editing a Flow worker, expand the **Advanced** section, below the **Cloudflare credentials** section, and select the toggle labeled **Edge Bot Detection**.

<img alt="A screenshot of the Edge Bot Detection toggle, in the expanded Advanced section" />

After enabling **Edge Bot Detection**, the Flow worker provides bot detection data to your pages and APIs by setting HTTP request headers in the requests it forwards.

This data falls into two categories: [IP intelligence](#ip-intelligence-request-headers) and [bot intelligence](#bot-intelligence-request-headers). The following tables list the request headers and a description of their values for each category. For the mapping from each header to its corresponding [Server API event](/reference/server-api-get-event) property, see [Flow worker request headers](/reference/flow-worker-headers).

### IP intelligence request headers

<Info>
  IP intelligence headers are provided for all requests, including those that are made by AI automation, bots, or humans.

  A single request is either IPv4 or IPv6, so only the matching set of `fp-ip-info-v4-*` or `fp-ip-info-v6-*` headers is set. Headers with no detected value are omitted (for example, `fp-ip-info-v4-datacenter-name` is only set when a datacenter is identified).

  Header values are encoded as [RFC 9651 structured fields](https://www.rfc-editor.org/info/rfc9651/): strings are quoted (`"AWS"`), booleans are sent as `?1` only for true values (false values are omitted entirely), and Unix timestamps use the `@` prefix (`@1733943233`).
</Info>

#### Address

| Request Header          | Description                                        |
| ----------------------- | -------------------------------------------------- |
| `fp-ip-info-v4-address` | The IPv4 address of the requesting browser or bot. |
| `fp-ip-info-v6-address` | The IPv6 address of the requesting browser or bot. |

#### Geolocation, ASN, and datacenter

The following headers are provided for both IPv4 and IPv6 (replace `v4` with `v6` for IPv6 requests).

| Request Header                              | Description                                                                                                          |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `fp-ip-info-v4-geolocation-accuracy-radius` | Radius in kilometers around the estimated location.                                                                  |
| `fp-ip-info-v4-geolocation-latitude`        | Estimated latitude of the IP address.                                                                                |
| `fp-ip-info-v4-geolocation-longitude`       | Estimated longitude of the IP address.                                                                               |
| `fp-ip-info-v4-geolocation-postal-code`     | Postal code associated with the IP address.                                                                          |
| `fp-ip-info-v4-geolocation-timezone`        | IANA timezone, for example, `"America/Los_Angeles"`.                                                                 |
| `fp-ip-info-v4-geolocation-city-name`       | City associated with the IP address.                                                                                 |
| `fp-ip-info-v4-geolocation-country-code`    | ISO 3166-1 alpha-2 country code, for example, `"US"`.                                                                |
| `fp-ip-info-v4-geolocation-continent-code`  | Two-letter continent code, for example, `"NA"`.                                                                      |
| `fp-ip-info-v4-asn-name`                    | Name of the organization that owns the ASN.                                                                          |
| `fp-ip-info-v4-asn-network`                 | ASN network range in CIDR notation.                                                                                  |
| `fp-ip-info-v4-asn-type`                    | ASN type, for example, `"hosting"`, `"isp"`, `"business"`.                                                           |
| `fp-ip-info-v4-datacenter-name`             | Datacenter operator name when the IP belongs to a known datacenter, for example, `"AWS"`. Omitted when not detected. |

#### Proxy

Proxy headers are only set when a proxy is detected. When no proxy is detected, none of the `fp-proxy-*` headers are sent.

| Request Header                  | Description                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------ |
| `fp-proxy`                      | `?1` when the request is identified as coming through a proxy.                       |
| `fp-proxy-confidence`           | Confidence level of the proxy detection, for example, `"low"`, `"medium"`, `"high"`. |
| `fp-proxy-details-proxy-type`   | Type of proxy, for example, `"residential"`, `"datacenter"`.                         |
| `fp-proxy-details-last-seen-at` | Unix timestamp of when the proxy was last seen, for example, `@1733943233`.          |
| `fp-proxy-details-provider`     | Provider operating the proxy, when known.                                            |

#### VPN

VPN headers are only set when a VPN is detected. Individual `fp-vpn-methods-*` headers are only set for detection methods that triggered; methods that did not trigger are omitted.

| Request Header                     | Description                                                                        |
| ---------------------------------- | ---------------------------------------------------------------------------------- |
| `fp-vpn`                           | `?1` when the request is identified as coming through a VPN.                       |
| `fp-vpn-confidence`                | Confidence level of the VPN detection, for example, `"low"`, `"medium"`, `"high"`. |
| `fp-vpn-methods-timezone-mismatch` | `?1` when the browser timezone does not match the IP location.                     |
| `fp-vpn-methods-public-vpn`        | `?1` when the IP belongs to a known public VPN service.                            |
| `fp-vpn-methods-auxiliary-mobile`  | `?1` when an auxiliary mobile-network signal indicates VPN use.                    |
| `fp-vpn-methods-os-mismatch`       | `?1` when OS-level signals indicate VPN use.                                       |
| `fp-vpn-methods-relay`             | `?1` when the IP belongs to a known relay service (e.g. iCloud Private Relay).     |

#### IP blocklist

| Request Header             | Description                                                                   |
| -------------------------- | ----------------------------------------------------------------------------- |
| `fp-ip-blocklist-tor-node` | `?1` when the IP address is a known Tor exit node. Omitted when not detected. |

### Bot intelligence request headers

<Info>
  Bot intelligence headers are provided for bots and AI automation. If the request cannot be attributed to a bot or AI automation, the fp-bot-info-\* request headers will not be set.
</Info>

| Request Header         | Description                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `fp-bot-info-category` | The `bot_info.category` for the bot e.g., `ai_agent`, `ai_browser`, `search_engine_crawler`. |
| `fp-bot-info-provider` | The organization that operates the bot, e.g., `OpenAI` or `AWS`.                             |
| `fp-bot-info-name`     | Human-readable bot name, e.g., `ChatGPT Agent`.                                              |
| `fp-bot-info-identity` | Verification status: `signed`, `verified`, `unknown`, or `spoofed`.                          |

### Learn more

* Refer to the [Bot directory](/docs/bot-detection/bot-directory) for a list of the bots and AI agents identified by edge bot detection, and the request header field values you can expect for each agent.
* Read the [AI agent detection](/docs/ai-agents) guide to learn how Fingerprint detects AI agents.
* Read the [AI assistant detection](/docs/ai-assistants) guide to learn how Fingerprint detects AI assistants.

## How Cloudflare Flow deployments work

Cloudflare Flow allows you to integrate Fingerprint protection into your website with little to no changes to your application code. It replaces the need to [install the JavaScript agent on your website](/docs/install-the-javascript-agent), [set up a proxy to avoid ad-blockers](/docs/protecting-the-javascript-agent-from-adblockers), [integrate Fingerprint Server API into your backend](/docs/get-server-side-intelligence), and write custom protection logic based on Fingerprint results.

<Info>
  Importantly, Cloudflare Flow deployment is different from the [Cloudflare Proxy Integration](/docs/cloudflare-integration), which only proxies requests between your website and Fingerprint when integrating Fingerprint manually.
</Info>

Here is how it works in detail:

* Using your Cloudflare API token and credentials, Fingerprint deploys a Cloudflare worker on your domain, which intercepts HTTP requests between browsers accessing your website and the origin server.
* When serving the pages that identify visitors (for example, `yourwebsite.com/signup` page), the worker injects the Fingerprint [JavaScript agent](/reference/js-agent) and an instrumentation script into the page markup.
  * Fingerprint creates a Public [API key](/docs/configuration#api-keys) and a Secret API key used only by the Flow worker and the injected JavaScript agent.
* For HTTP requests to APIs you want to protect (for example, the `POST api.yourwebsite.com/create-account` request), the instrumentation script collects information about the browser configuration and attaches it to the request as a custom header, `fp-data`.
  * The `fp-data` header takes up approximately 20 KB, around 16% of the Cloudflare's [total request header size limit](https://developers.cloudflare.com/workers/platform/limits/#request-limits) of 128 KB.
* The Flow worker intercepts the protected request and sends the browser information to the Fingerprint Identification API. If the worker is using a ruleset, the request also includes the ruleset ID.
* In return, the worker receives the full [identification event](/reference/server-api-get-event) and (if applicable) the [rule action](/docs/rules-engine#rule-action) produced by evaluating your ruleset.
* If using a ruleset, the Flow worker processes the rule action by blocking the protected request or allowing it to reach the origin server.
* The Flow worker code is [open-sourced on GitHub](https://github.com/fingerprintjs/flow-cloudflare-worker).

### Route pattern matching

The identification pages and protected APIs are converted to Cloudflare worker [route patterns](https://developers.cloudflare.com/workers/configuration/routing/routes/#matching-behavior) and follow the same format and [matching behavior](https://developers.cloudflare.com/workers/configuration/routing/routes/#matching-behavior).

* Each Cloudflare route can only be served by one Cloudflare worker. If you try to use a route pattern already served by another worker, your deployment will fail.
* You can use a wildcard (`*`) at the end of the path but not in the middle of it.
* Using a wildcard suffix (`/path*`) is [required to match requests with query parameters](https://developers.cloudflare.com/workers/configuration/routing/routes/#:~:text=Route%20pattern%20matching%20considers%20the%20entire%20request%20URL%2C%20including%20the%20query%20parameter%20string.%20Since%20route%20patterns%20may%20not%20contain%20query%20parameters%2C%20the%20only%20way%20to%20have%20a%20route%20pattern%20match%20URLs%20with%20query%20parameters%20is%20to%20terminate%20it%20with%20a%20wildcard%2C%20*.) like `path?query=value`.

<Note>
  You might encounter edge cases where Cloudflare caching interacts with wildcard route matching in a way that produces [unexpected behavior](https://community.cloudflare.com/t/presence-of-query-string-make-route-match-fail/63400). In that case, do not hesitate to contact our [support team](https://fingerprint.com/support/). Defensively using both the base and wildcard variants of the path (`path` and `path*`) can help.
</Note>

### Current limitations

* You can only protect API calls (actions, transactions) made by the visitor on the identification page. You cannot protect the page itself.
  * For example, you cannot block bots from visiting the sign-up page, but you can block the `create-account` API call made by the page if the bot clicks "Create account".
* You can define a maximum of 10 identification pages and 10 protected APIs per Flow deployment.
* You must define at least one identification page and one API endpoint per Flow deployment, even if you are using the worker in Monitoring mode. The identification page calling the API endpoint is what triggers visitor identification.
* Customizations of the JavaScript agent behavior, such as [tags](/reference/js-agent-get-function#tags), [linked IDs](/reference/js-agent-get-function#linkedid), [custom timeout](/reference/js-agent-get-function#timeout), etc., are not supported at this time.
* At the moment, you cannot rotate the Public and Secret [API keys](/docs/configuration#api-keys) used by the worker. The secret API key is encrypted in both the Fingerprint and Cloudflare dashboards, so exposing it is unlikely. If you need to replace either key anyway, you need to delete your Flow deployment and recreate it. Alternatively, you can contact our [support team](https://fingerprint.com/support/) for assistance.
* Protected API calls made with `fetch` must NOT use [`mode: 'no-cors'`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#mode). In `no-cors` mode, the browser strips the `fp-data` header, so identification fails and the request is either blocked or forwarded to the origin server (based on your chosen failure mode).

### Troubleshooting

If you encounter any issues with your Flow deployment, you can:

* Use the [Fingerprint Dashboard](https://dashboard.fingerprint.com/) > **Identification** page to confirm that Flow deployment is generating identification events as expected. Note that any Smart Signals not enabled for your workspace will always evaluate to false.

* Hard reload the identification page of your website to ensure you are getting the latest version from the Flow worker. Look for `instrumentor.iife.js` in the Network tab of your browser's developer tools to confirm.

* Make sure the protected API is actually called from the identification page you defined. Use the browser's developer tools to confirm that the `fp-data` header is being attached to the request.

* Navigate to your Cloudflare dashboard to confirm the worker configuration matches your Flow deployment (worker code, environment variables, routes, etc.).

* Enable [Worker logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs) and examine them for errors. Any error returned from the Fingerprint Identification API will only be visible here, not propagated to your application.

* Most common errors include [Request filtering](/docs/request-filtering-for-websites) blocking identification requests by origin.

* Contact our [support team](https://fingerprint.com/support/). Include relevant logs or screenshots of the above to aid troubleshooting.


# Flutter
Source: https://docs.fingerprint.com/docs/flutter



<Warning>
  ### JavaScript agent v4 support coming soon

  This client SDK currently supports JavaScript agent v3. For the current v3 documentation, see [Flutter SDK (v3)](/docs/v3/flutter). You can also check the current [integration compatibility table](/reference/migrating-from-v3-to-v4#client-sdk-compatibility-for-javascript-agent-v4).
</Warning>


# Flutter Quickstart
Source: https://docs.fingerprint.com/docs/flutter-quickstart



<Warning>
  ### JavaScript agent v4 support coming soon

  This client SDK currently supports JavaScript agent v3. For the current v3 quickstart, see [Flutter Quickstart (v3)](/docs/v3/flutter-quickstart). You can also check the current [integration compatibility table](/reference/migrating-from-v3-to-v4#client-sdk-compatibility-for-javascript-agent-v4).
</Warning>


# Overview
Source: https://docs.fingerprint.com/docs/frontend-libraries

Fingerprint offers SDKs for the most popular client-side frameworks and libraries.

If your application does not use a framework, or Fingerprint does not provide a dedicated SDK for your framework, use the [JavaScript agent](/reference/js-agent) directly. JavaScript agent v4 includes a built-in [cache option](/reference/js-agent-start-function#cache), so the deprecated SPA wrapper is no longer necessary.


# Generic JavaScript agent wrapper for SPAs
Source: https://docs.fingerprint.com/docs/generic-js-agent-wrapper-for-spas



<Warning>
  **Deprecated in v4**

  In Fingerprint v4, the caching functionality from `@fingerprintjs/fingerprintjs-pro-spa` has been incorporated directly into the [JavaScript agent](/reference/js-agent). You no longer need this wrapper library.

  If you are using Fingerprint v3, see the [v3 documentation](/docs/v3/generic-js-agent-wrapper-for-spas).
</Warning>

## Migration guide

Follow these steps to migrate from `@fingerprintjs/fingerprintjs-pro-spa` to the v4 JavaScript agent.

### 1. Update dependencies

Remove the SPA library and install the v4 agent:

```shell theme={"theme":"github-dark-dimmed"}
npm uninstall @fingerprintjs/fingerprintjs-pro-spa
npm install @fingerprint/agent
```

### 2. Update imports and initialization

The v4 agent uses `Fingerprint.start()` instead of creating a `FpjsClient` instance and calling `init()`.

```js SPA library to v4 agent theme={"theme":"github-dark-dimmed"}
import { FpjsClient, FingerprintJSPro } from "@fingerprintjs/fingerprintjs-pro-spa"; // [!code --]
import * as Fingerprint from "@fingerprint/agent"; // [!code ++]

const fpjsClient = new FpjsClient({
  // [!code --]
  loadOptions: {
    // [!code --]
    apiKey: "PUBLIC_API_KEY", // [!code --]
    endpoint: ["https://metrics.yourwebsite.com", FingerprintJSPro.defaultEndpoint], // [!code --]
    region: "eu", // [!code --]
  }, // [!code --]
  cacheLocation: "sessionStorage", // [!code --]
  cacheTimeInSeconds: 3600, // [!code --]
}); // [!code --]
await fpjsClient.init(); // [!code --]
const agent = Fingerprint.start({
  // [!code ++]
  apiKey: "PUBLIC_API_KEY", // [!code ++]
  endpoints: "https://metrics.yourwebsite.com", // [!code ++]
  region: "eu", // [!code ++]
  cache: {
    // [!code ++]
    storage: "sessionStorage", // [!code ++]
    duration: 3600, // [!code ++]
  }, // [!code ++]
}); // [!code ++]
```

### 3. Update identification calls

Replace `getVisitorData()` with `get()`.

```js getVisitorData to get theme={"theme":"github-dark-dimmed"}
const visitorData = await fpjsClient.getVisitorData(); // [!code --]
console.log(visitorData.visitorId); // [!code --]
const result = await agent.get(); // [!code ++]
console.log(result.visitor_id); // [!code ++]
```

<Info>
  The v4 agent no longer supports `extendedResult`. Extended data like IP address and geolocation
  should be retrieved server-side using the [Server API](/reference/server-api) or [Sealed Client
  Results](/docs/sealed-client-results).
</Info>

### 4. Update cache configuration

The cache options have been renamed:

| SPA library                       | v4 agent                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `cacheLocation: 'sessionStorage'` | `cache: { storage: 'sessionStorage', ... }`                                     |
| `cacheLocation: 'localStorage'`   | `cache: { storage: 'localStorage', ... }`                                       |
| `cacheLocation: 'memory'`         | `cache: { storage: 'agent', ... }`                                              |
| `cacheLocation: 'nocache'`        | Omit the `cache` option entirely                                                |
| `cacheTimeInSeconds: 3600`        | `cache: { duration: 3600, ... }` or `cache: { duration: 'optimize-cost', ... }` |

The v4 agent also provides two convenient duration presets:

* `'optimize-cost'` — caches for 1 hour
* `'aggressive'` — caches for 12 hours (not recommended for fraud prevention)

### 5. Check for cached results

The `cacheHit` property is now `cache_hit` in the response:

```js cacheHit to cache_hit theme={"theme":"github-dark-dimmed"}
const { cacheHit, ...visitorData } = await fpjsClient.getVisitorData(); // [!code --]
if (cacheHit) {
  // [!code --]
  console.log("Result was from cache"); // [!code --]
} // [!code --]
const result = await agent.get(); // [!code ++]
if (result.cache_hit) {
  // [!code ++]
  console.log("Result was from cache"); // [!code ++]
} // [!code ++]
```

For more details about the v4 JavaScript agent, see the [JavaScript agent reference](/reference/js-agent).


# Go Server Quickstart
Source: https://docs.fingerprint.com/docs/go-server-quickstart

Get started using the Go Server SDK

## Overview

In this quickstart, you'll add Fingerprint to a [Go](https://go.dev/) server to prevent fraudulent account creation.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. You can flag and block suspicious users by identifying the device behind each sign-up attempt, login, or transaction.

In this quickstart, you'll learn how to:

* Set up a Go server (using the [gorilla/mux](https://github.com/gorilla/mux) router) with a Fingerprint integration
* Retrieve visitor identification data using the Server API
* Block bots and suspicious devices
* Prevent multiple signups from the same device

This guide focuses on the backend integration and must be completed after identifying a visitor and generating an event ID. **Before starting this quickstart, start with one of the [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview) quickstarts to see how to identify a visitor in your frontend.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* A completed frontend or mobile Fingerprint implementation **(See the quickstarts)**
* [Go](https://go.dev/) (v1.24 or later)
* Your favorite code editor
* Basic knowledge of Go

## 1. Get your secret API key

<Note>
  Before starting this quickstart, you should already have a frontend Fingerprint implementation
  that sends the `event_id` to your server. If not, pause here and check out one of the
  [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview)
  quickstarts first.
</Note>

If you're ready:

1. Sign in and go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the Fingerprint dashboard.
2. Create a new **secret API key**.
3. Copy it somewhere safe so you can use it to retrieve full visitor identification data from the Server API.

## 2. Set up your project

To get started, set up a basic server. If you already have a project you want to use, you can skip to the next section.

1. Create a new Go module and install `gorilla/mux` and the Fingerprint Go Server SDK:

```bash Terminal theme={"theme":"github-dark-dimmed"}
mkdir fingerprint-go-quickstart && cd fingerprint-go-quickstart
go mod init fingerprint.com/go-quickstart
go get github.com/gorilla/mux github.com/fingerprintjs/go-sdk/v8
```

*Note: This quickstart is written for version 8.x of the Fingerprint Go Server SDK*

2. Create a new file called `main.go` and add a basic gorilla/mux server setup:

```go main.go theme={"theme":"github-dark-dimmed"}
package main

import (
  "encoding/json"
  "log"
  "net/http"

  "github.com/gorilla/mux"
)

func main() {
  r := mux.NewRouter()
  r.HandleFunc("/api/create-account", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]string{"status": "Account created!"})
  }).Methods("POST")

  http.Handle("/", r)
  srv := &http.Server{
    Handler: r,
    Addr:    "localhost:3000",
  }

  log.Printf("Server is running on http://localhost:3000")
  log.Fatal(srv.ListenAndServe())
}
```

Here we are running the server at port 3000 and have created a new POST route for account creation. Note that the `/api/create-account` route should match what you have set up in your frontend implementation where you are sending the Fingerprint `event_id` to your server. Your server will receive the initial identification information from identifying a visitor on the frontend and use it to get the full visitor data on the backend.

## 3. Initialize Fingerprint and retrieve visitor data

Now you'll configure the Fingerprint Go Server SDK using your secret API key and use it to fetch detailed visitor data for each signup attempt.

When making the initial visitor identification request in the frontend, you received an `event_id`. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. At the top of your `main.go` file, import the Fingerprint Go Server SDK:

```go main.go theme={"theme":"github-dark-dimmed"}
import (
  // ...
  // Add this import:
  "github.com/fingerprintjs/go-sdk/v8"
)
```

2. At the beginning of the `main()` function, initialize the client agent with your secret API key. Change the [region](/docs/regions), if required:

```go main.go theme={"theme":"github-dark-dimmed"}
func main() {
  client := fingerprint.New(
    fingerprint.WithAPIKey("SECRET_API_KEY"),
    fingerprint.WithRegion(fingerprint.RegionUS),
  )

  // Rest of function
  // ...
}
```

*For a production implementation make sure to store and reference your secret key securely.*

3. In your `/api/create-account` handler, retrieve the `event_id` you are sending from the frontend and fetch the full visitor identification details with `GetEvent()`:

<Note>
  **requestId vs event\_id:** Depending on which quickstart you completed, your frontend may send
  either `requestId` (older SDKs) or `event_id` (v4 and newer). Both refer to the same
  identification event and work with the Server API in the same way. Use whichever value your
  frontend sends (`requestId` or `event_id`) as the event identifier below.
</Note>

```go main.go theme={"theme":"github-dark-dimmed"}
r.HandleFunc("/api/create-account", func(w http.ResponseWriter, r *http.Request) {
  var createAccountRequest CreateAccountRequest
  err := json.NewDecoder(r.Body).Decode(&createAccountRequest)
  if err != nil {
    http.Error(w, "Invalid JSON", http.StatusBadRequest)
    return
  }

  event, _, err := client.GetEvent(r.Context(), createAccountRequest.EventID)
  if err != nil {
    // An error may occur because the event ID is invalid or missing, or there is an issue with the configuration.
    if errResp, ok := fingerprint.AsErrorResponse(err); ok {
      switch errResp.Error.Code {
      case fingerprint.ErrorCodeEventNotFound:
        log.Printf("Event not found")
      default:
        log.Printf("Error %s: %v", errResp.Error.Code, errResp)
      }
    }
    http.Error(w, "Error processing request", http.StatusBadRequest)
    return
  }

  w.Header().Set("Content-Type", "application/json")
  w.WriteHeader(http.StatusOK)
  json.NewEncoder(w).Encode(map[string]string{"status": "Account created!"})
}).Methods("POST")
```

4. To support the JSON decoding, declare the `CreateAccountRequest` struct just before the `main()` function:

```go main.go theme={"theme":"github-dark-dimmed"}
type CreateAccountRequest struct {
  EventID string `json:"event_id"`
  Username  string `json:"username"`
  Password  string `json:"password"`
}
```

Using the `event_id` the GetEvent method will retrieve the full data for the visitor identification request. The returned object will contain the visitor ID, IP address, device and browser details, and Smart Signals like bot detection, incognito mode detection, and detections for VPN or virtual machine use.

You can see a full example of the event structure, and test it with your own device, in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 4. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection Smart Signal which is available only on paid plans.
</Note>

A simple but powerful way to prevent fraudulent account creation is to block automated signups that come from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

1. Continuing in your `/api/create-account` route, check the bot signal returned in the `event` object:

```go main.go theme={"theme":"github-dark-dimmed"}
if *event.Bot != fingerprint.BotResultNotDetected {
  log.Printf("Bot detected")
  http.Error(w, "Failed to create account.", http.StatusForbidden)
  return
}
```

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found. You can also layer in other Smart Signals to catch more suspicious devices. For example, you can use Fingerprint's [Suspect Score](/docs/suspect-score) to determine when to add additional friction to create an account.

## 5. Prevent multiple signups from the same device

To catch repeated signups from the same device, you can use the `visitor_id` from the Fingerprint identification event. By saving this ID alongside each created account, you can detect and block duplicate signups from the same device. We'll be using a simple database to demonstrate how this works with SQLite.

1. Install the `modernc.org/sqlite` SQLite package:

```bash Terminal theme={"theme":"github-dark-dimmed"}
go get modernc.org/sqlite
```

2. At the top of your `main.go` file, add these imports:

```go main.go theme={"theme":"github-dark-dimmed"}
import (
  "database/sql"
  _ "modernc.org/sqlite"

  // ...
)
```

3. Then after the Fingerprint configuration code in `main()`, initialize the database:

```go main.go theme={"theme":"github-dark-dimmed"}
db, err := sql.Open("sqlite", "database.db")
if err != nil {
  log.Fatal(err)
  os.Exit(1)
}
db.Exec(`CREATE TABLE IF NOT EXISTS accounts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  username TEXT,
  password TEXT,
  visitorId TEXT
)`)
defer db.Close()
```

4. In your `/api/create-account` route handler, after getting the event, extract the `visitor_id`:

```go main.go theme={"theme":"github-dark-dimmed"}
visitorId := event.Identification.VisitorID
```

5. Check if this device has already created an account; if yes, block the account creation:

```go main.go theme={"theme":"github-dark-dimmed"}
// Check if the visitor ID already exists in the database
existingRow := db.QueryRow("SELECT COUNT(*) FROM accounts WHERE visitorId = ?", visitorId)
var count int
existingRow.Scan(&count)

if count > 0 {
  log.Printf("Device has already created an account")
  http.Error(w, "Failed to create account.", http.StatusTooManyRequests)
  return
}

_, err = db.Exec("INSERT INTO accounts (username, password, visitorId) VALUES (?, ?, ?)",
  createAccountRequest.Username, createAccountRequest.Password, visitorId)

if err != nil {
  log.Printf("Database error")
  http.Error(w, "Failed to create account.", http.StatusInternalServerError)
  return
}
```

This gives you a basic system to detect and block repeat signups. You can expand on this by allowing a limited number of accounts per device, adjusting your response based on business rules, only evaluating recent signups, etc.

<Info>
  This is a minimal example to show how to use the Fingerprint Go Server SDK. In a real application,
  make sure to implement proper security practices, especially around password handling and storage.
</Info>

## 6. Test your implementation

Now that everything is set up, you can test the full flow using your existing frontend.

### Before you test

If your frontend is running on a different port (like localhost:5173 or localhost:3001), you may run into CORS issues for testing. To quickly fix this for local development & testing:

1. Install the `gorilla/handlers` module:

```bash Terminal theme={"theme":"github-dark-dimmed"}
go get github.com/gorilla/handlers
```

2. Add `"github.com/gorilla/handlers"` to your imports in `main.go`, then set up the CORS configuration and attach it to the handler at the end of your `main()` function:

```go main.go theme={"theme":"github-dark-dimmed"}
originsOk := handlers.AllowedOrigins([]string{"*"})
methodsOk := handlers.AllowedMethods([]string{"GET", "HEAD", "POST", "PUT", "OPTIONS"})
headersOk := handlers.AllowedHeaders([]string{"Accept", "Accept-Language", "Content-Type", "Content-Language", "Origin"})

srv := &http.Server{
  Handler: handlers.CORS(originsOk, methodsOk, headersOk)(r),
  Addr:    "localhost:3000",
}

log.Printf("Server is running on http://localhost:3000")
log.Fatal(srv.ListenAndServe())
```

### Test the implementation

1. Start your Go server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
go run main.go
```

2. In your frontend, trigger a sign-up request that sends the `event_id`, `username`, and `password` to your `/api/create-account` endpoint. To see the reply messages make sure to parse and display or console log the response from your server.
3. Within your frontend, input a username and password to create a user. Then try to create another user and see that the second attempt will be rejected.
4. Bonus: Try creating an account using a headless browser.

## Next steps

You now have a working backend fraud check using Fingerprint. From here, you can expand your logic with more Smart Signals, adjust thresholds based on your risk tolerance, or introduce additional checks for suspicious users.

These same techniques apply to a wide range of fraud prevention use cases, from detecting fake reviews to blocking payment abuse or preventing account takeovers.

To go further, check out the use case tutorials for step-by-step guides tailored to specific problems you can solve with Fingerprint.

Check out these related resources:

* [Go SDK Reference](/reference/go-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Monitoring health
Source: https://docs.fingerprint.com/docs/health



The Dashboard allows you to stay on top of **integration health**, by informing you of required SDK updates, and monitoring throttling, latency, and error rates.

## Health overview

The Health page gives you a high-level view of your Fingerprint setup, surfacing issues that need attention and pointing you to where to fix them.

To check it out, visit **Dashboard** > [**Health**](https://dashboard.fingerprint.com/health).

<Frame>
  <img alt="Clean Shot 2026 06 09 At 14 15 40@2x" />
</Frame>

Three status widgets at the top of the page highlight anything that needs your attention:

* **Throttled requests** (1) shows the total number of requests throttled in the current period, along with the API keys responsible. Each key links to its API key details, where you can adjust the [RPS limit](/docs/billing#rate-limiting-burst-protection) or investigate the traffic pattern.
* **Webhooks** (2) shows your webhook failure rate and the webhooks with the most recent delivery failures. Each entry links to its delivery logs.
* **SDK versions** (3) shows how many SDK updates are available across your integrations. Each entry shows the current version and the latest available version, and links to corresponding library page for the full breakdown.

When everything is healthy, each widget shows a neutral state - no action needed.

Below the widgets, a single timeline chart (4) lets you switch between three views using the dropdown:

* **API Latency** show the average latency for JavaScript agent requests, in 5-minute buckets. This is the time it takes a Fingerprint identification request to return data from the server. Only requests from client-side JavaScript SDKs are counted.
* **API Errors** shows requests that timed out or returned an error, including both client and server-side errors from the JavaScript agent.
* **Webhook Failed Calls** shows webhook delivery failures over time, broken down by webhook endpoint.

## API key monitoring

For Public and Server API keys, you can view detailed monitoring information on the key details page.

To check it out, visit **Dashboard** > [**API keys**](https://dashboard.fingerprint.com/api-keys) and select a key to view its details.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 55 12@2x" />
</Frame>

The key details page shows when the key was last used, by which library version, and on what origin domains or mobile apps.

Two charts give you a closer look at how the key is being used:

* The Request usage chart shows incoming identification requests using this API key, broken down into:
  * **Success** - successful requests with response HTTP 200
  * **Throttled** - requests over the configured RPS limit, responded with HTTP 429
  * **Restricted** - requests filtered out by request filtering rules or that exceeded workspace/environment limits, responded with HTTP 403
* The Server-side latency chart shows percentiles for the average time to process identification requests. Client-side signal collection latency is not included.

## Webhook monitoring

For each registered webhook, you can view a log of every delivery attempt by clicking into the webhook on the Webhooks page.

To check it out, visit **Dashboard** > [**Webhooks**](https://dashboard.fingerprint.com/webhooks) and select a webhook.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 53 33@2x" />
</Frame>

The Webhook events page lists each delivery attempt with:

* **Request ID** - the identification request this delivery is associated with
* **Visitor ID** - the visitor ID from the event payload
* **Status** - whether the delivery succeeded or failed
* **Status code** - the HTTP response code returned by your endpoint
* **Date** - when the delivery was attempted

Clicking on a request row will expand it, so you can inspect the full request and response when diagnosing why a delivery failed.

For details on retry behavior and the expected response contract, see [Webhooks > Timeout and errors](https://docs.fingerprint.com/docs/webhooks#timeout-and-errors).

## Outdated libraries

The **Libraries & integrations** page shows you a detailed view of all SDKs in use across your integrations, including both web and mobile SDKs as well as Server API SDKs.

To check it out, visit **Dashboard** > [**Libraries & integrations**](https://dashboard.fingerprint.com/integrations/active).

<Frame>
  <img alt="Clean Shot 2026 06 09 At 14 19 38@2x" />
</Frame>

Each row in the Libraries list shows:

* The library (e.g. JavaScript, Next.js, Node.js, iOS) and where it runs (Website, Server, or App)
* The number of requests in the last 24 hours
* The version in use, and the latest version available

Libraries are refreshed once every 24 hours.

### Per-library health

Clicking an active library opens its **Health** tab, which gives you a detailed view of where that SDK is running and which deployments are out of date.

<Frame>
  <img alt="Clean Shot 2026 06 09 At 14 22 14@2x" />
</Frame>

At the top of the page, four summary cards show:

* The latest version of the library
* The number of outdated origins out of the total observed
* Total requests in the selected window
* How many of those requests came from outdated versions

Below the summary, the origins table lists every domain (for web SDKs) or app (for mobile SDKs) where this library is running:

* **Origin** - the domain or app ID
* **Version** - the SDK version in use, or a "Multiple" label when more than one version is detected
* **Requests** - the number of identification requests from this origin in the selected window
* **Last request** - timestamp of the most recent request
* **Severity** - whether the origin is up to date, or how far behind it is

**Domains**

For web SDKs, clicking a domain row expands it to show the specific URLs observed on that domain and the SDK version detected on each. When more than one version appears on the same URL, each version is listed with its own request count, so you can see whether stale clients are still trickling in or whether a deployment really is out of date.

**Mobile apps**

Mobile apps often have multiple SDK versions in use at once, since users update apps at different rates. Each version is shown with its request count so you can see the adoption of your latest release.

**Activity**

Below the origins table, the Activity chart shows total request volume over time, with errors and timeouts called out separately. This helps you spot whether an outdated origin is also experiencing reliability issues.


# Identification, accuracy, and confidence score
Source: https://docs.fingerprint.com/docs/identification-accuracy-and-confidence

Learn about the different methods Fingerprint uses to identify visitors, how Fingerprint defines and maintains accuracy, and how to use confidence score in your applications.

To identify a browser or a device, Fingerprint collects several properties from them. Our advanced machine-learning models use these properties to create a unique visitor ID.

# Identification methods

Fingerprint uses one of the following approaches to identify browsers and devices:

* **Deterministic Identification**: This method uses browser or device properties that are unique and reliable (*aka* deterministic properties). [HTTP cookie](https://en.wikipedia.org/wiki/HTTP_cookie) is an example of such a property. These properties are accurate, but may not be available in situations like:

  * Private or incognito browsing modes.
  * Browser storage is cleared.
  * Third-party cookies are not available in certain browsers. See [Safari Intelligent Tracking Prevention](/docs/browser-and-device-support#safari-intelligent-tracking-prevention). In such situations, Fingerprint identifies visitors using probabilistic identification.

* **Probabilistic identification:** This method uses non-deterministic properties such as screen resolution, timezone, etc. These properties are combined to create a unique identifier for a browser or device. To learn more, see [What is browser fingerprinting? 6 top techniques to fight fraud](https://fingerprint.com/blog/browser-fingerprinting-techniques/). This method introduces a probability of error because non-deterministic properties change over time and their values could be the same between two identical browsers. These factors can cause Fingerprint to create the same identifier for two different visitors or identify the same visitor differently.

# Identification accuracy

Identification accuracy primarily applies to probabilistic identification. It defines the ability to identify returning browsers and devices precisely.

## How is identification accuracy measured?

We measure accuracy by performing prediction experiments with two sets of data in which:

* The *control* dataset is the set of deterministically identified events.
* The *test* dataset is created by removing the deterministic properties.
* The events in the test dataset are re-identified.
* The visitor IDs in the test dataset are compared with the visitor IDs in the control dataset.

The comparison results can be categorized as one of:

* **True-positive:** The visitor ID remained the same in both control and test datasets.
* **False-positive:** The visitor ID in the test dataset is different from that of the control. This browser has been incorrectly identified as another **existing** browser.
* **False-negative:** The visitor ID does not exist in the control dataset. This browser has been incorrectly identified as a new browser.

<Check>
  **Identification accuracy for mobile devices is higher than that of browsers**

  We identify mobile devices using properties that remain stable for longer durations than those used to identify browsers.
</Check>

At Fingerprint, we maintain industry-leading accuracy by continually striving to minimize the false-positive and false-negative rates.

# Confidence Score

For every identification request, a confidence score is computed internally. You can get the confidence score for a specific request in one of the following ways:

* Via the [Server API](/reference/server-api-get-event)
* Via [webhooks](/reference/posteventwebhook)

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  {
    "event_id": "1708102555327.NLOjmg",
    "identification": {
      "visitor_id": "Ibk1527CUFmcnjLwIs4A9",
      "confidence": {
        "score": 0.97,
        "version": "1.1"
      },
      "visitor_found": false,
      "first_seen_at": 1708102555327,
      "last_seen_at": 1708102555327
    },
  }
  ```
</CodeGroup>

The confidence score indicates the probability of a false-positive identification. It is a floating-point number whose value ranges from 0 to 1. The higher the value, the more confident Fingerprint is about not misidentifying this browser as another.

## Using confidence score in your application

You can use the confidence score to improve security and user experience. A few examples:

* **Prevent account takeover**: You can use the confidence score to request additional verification. For example, request OTP for browsers whose confidence score is below 0.95.
* **Increase conversion:** You can use the confidence score to profile an anonymous user. For example, you can offer tailor-made promotions and enhance the user experience.

The thresholds given here are only examples. Finding the optimal threshold for your use case may require iterative experiments.

## How is the confidence score calculated?

In simple terms, the confidence score is calculated as

```
confidenceScore = 1 - falsePositiveProbability
```

Where `falsePositiveProbability` is deduced from our prediction experiments and represents the probability of a false-positive identification.

## Understanding the confidence score

**First-time browsers or devices**

Fingerprint identifies a browser or a device as new only when it cannot find a match for this browser in your data. In this case, the probability of a false-positive identification becomes 0. Hence, the confidence score for such new browsers or devices is **1.0**

An existing browser could also be incorrectly identified as a first-time browser. The confidence score in this case will still be 1.0. Because it doesn't state the probability of a false-negative identification, only false-positive rather.

**Returning visitors identified deterministically**

The deterministic properties are unique, even among identical browsers. It is not possible to incorrectly identify one browser as another. In other words, the `falsePositiveProbability` is **0**. Hence, the confidence score for these browsers or devices is **1.0.**

**Returning visitors identified probabilistically**

The probabilistic properties are not as unique as the deterministic properties. This increases the chances of incorrectly identifying a browser as another. In other words, the `falsePositiveProbability` is greater than 0. Hence the confidence score for these browsers or devices is always **less than 1.0.** Even when future identifications are deterministic (see Example).

## Example: Confidence score for different scenarios

<img alt="" />

# How is accuracy different from confidence score?

### Accuracy

* Represents the **overall value** that Fingerprint provides you. For example, a 98% true-positive rate would mean that, in the absence of deterministic properties, only 2% of your visitors may be identified incorrectly.
* It is not associated with an individual identification request.

### Confidence Score

* For an identification request, it represents the probability of **only** the false-positive identification. It should not be used to determine the overall accuracy of the product.
* Unlike accuracy, confidence score enables you to make real-time decisions as described in [using confidence score in your application](/docs/identification-accuracy-and-confidence#using-confidence-score-in-your-application).

***

[Planning your implementation](/docs/planning-implementation)


# Identify visitors
Source: https://docs.fingerprint.com/docs/identify-visitors

Learn best practices for timing identification requests, caching visitor IDs, or using linked IDs to associate your own identifiers with each visitor ID.

Once the [JavaScript agent is installed and initialized](/docs/install-the-javascript-agent), call the [`get()`](/reference/js-agent-get-function) function (or its [SDK equivalent](/docs/frontend-libraries)) to identify the browsers visiting your website. The `get()` function sends the collected browser signals to the Fingerprint Platform and returns a [response](/reference/js-agent-get-function#get-response) containing the visitor ID for the browser and associated metadata.

This guide covers best practices for timing identification requests, caching visitor IDs, and using linked IDs to associate your own identifiers with each visitor ID. To explore further, please refer to the [JavaScript Agent API reference](/reference/js-agent).

If you are looking to identify mobile devices instead, see [Android](/docs/native-android-integration) and [iOS](/docs/ios).

<Note>
  **Note:** The code snippets in this guide assume you have already set up some kind proxy integration for Fingerprint. Proxying requests through your own domain or subdomain like metrics.yourwebsite.com instead of connecting to Fingerprint servers directly helps avoid ad blockers and increases accuracy.

  See [Installing the JavaScript agent](/docs/install-the-javascript-agent) and [Evading ad-blockers (proxy integrations)](/docs/protecting-the-javascript-agent-from-adblockers) for more details.
</Note>

## Timing identification requests

For most use cases, we recommend identifying the visitor on demand, when they perform a specific action:

* Call [`start()`](/reference/js-agent-start-function) as early as possible, ideally, right after the page loads.
* Call [`get()`](/reference/js-agent-get-function) only when needed (e.g., upon login or product selection).
* Wait at least 1 second after calling `start()` before calling `get()`, to give the JavaScript Agent enough time to collect the required signals.

```ts HTML theme={"theme":"github-dark-dimmed"}
<script>
      // Initialize the agent on page load
      const fpPromise = import('https://metrics.yourwebsite.com/v4/PUBLIC_API_KEY')
        .then(Fingerprint => Fingerprint.start({/*...*/}))

      // Analyze the visitor if they submit a form
      document.querySelector('button[type="submit"]').addEventListener('click', async () => {
        const fp = await fpPromise
        const result = await fp.get()
        console.log(result.event_id, result.visitor_id)
      })

</script>
```

This just-in-time approach also helps you:

* Ensure browsers are identified only after receiving the required [consent](/docs/privacy-and-compliance#do-i-need-to-have-a-gdpr-consent-management-banner-if-using-fingerprint).
* Avoid unnecessary use of your [billable](/docs/billing#identification-api-request-as-a-billing-unit) API calls.

See [Optimizing the JavaScript agent](/docs/optimize-javascript-agent) to learn more about deploying Fingerprint effectively.

### Response

The `get()` function returns a promise of a [response](/reference/js-agent-get-function#get-response) object with the visitor ID and other metadata.

<CodeGroup>
  ```javascript get() response wrap theme={"theme":"github-dark-dimmed"}
  await fp.get()
  // response:
  {
    "event_id": "8nbmT18x79m54PQ0GvPq",
    "visitor_id": "2JGu1Z4d2J4IqiyzO3i4",
    "suspect_score": 0,
    "sealed_result": null // or BinaryOutput when Sealed Results are enabled
  }
  ```
</CodeGroup>

<Note>
  **JavaScript agent response limitations**

  Note that the response received by the JavaScript agent is limited on purpose. Since client-side code can be tampered with, we recommend consuming Fingerprint results securely through one of our server-side integrations. The full identification event including the visitor's [Smart Signals](/docs/smart-signals-reference) is available through the [Server API](/reference/server-api), [Webhooks](/docs/webhooks), or [Sealed results](/docs/sealed-client-results).

  See [Protecting from client-side tampering](/docs/protecting-from-client-side-tampering) to learn about getting Fingerprint results securely to your server.
</Note>

## Linking and tagging information

The `visitor_id` provided by Fingerprint Identification is especially useful when combined with information you already know about your users, for example, account IDs, order IDs, etc. You can follow user actions, track logged-in devices, and recognize malicious behavior.

You can pass a `linkedId` or `tags` parameter to the `get()` function (or its equivalent in your SDK) to associate your own metadata with the visitor ID.

```ts HTML theme={"theme":"github-dark-dimmed"}
<script>
      const fpPromise = import('https://metrics.yourwebsite.com/v4/PUBLIC_API_KEY')
        .then(Fingerprint => Fingerprint.start())

      // Pass your own data to get()
      fpPromise
        .then(fp => fp.get({
          linkedId: "accountNum12345",
          tags: {
            orders: ["orderNum6789"],
            location: { city: "Atlanta", country: "US" }
          }
        }))
        .then(result => console.log(result.visitor_id))

</script>
```

* [`linkedId`](/reference/js-agent-get-function#linkedid) is a string you can use to filter identification events in the Dashboard or to filter visitor history using the Server API.
* [`tags`](/reference/js-agent-get-function#tags) is a JavaScript object of any shape allowing you to store structured metadata. It is *not indexed*, you cannot use it to search for events.

For more details, see [Linking and tagging information](/docs/tagging-information).

## Caching the visitor ID

If your use case demands highly accurate identification, we recommend identifying the visitor [on demand](#timing-identification-requests) and always using a fresh visitor ID without caching.

Depending on your use case, you can choose to cache (store) the visitor ID in the browser to:

* Improve the responsiveness of your application.
* Stay within the limits of your monthly allowance of API calls.

Caching visitor IDs for extended periods can significantly reduce identification accuracy. Make sure to understand caching best practices and implications before caching visitor IDs.

### Caching using JavaScript agent

JavaScript agent provides caching out of the box but is disabled by default.
To use it, you need to specify the [cache](/reference/js-agent-start-function#cache) option when initializing the agent.

```ts HTML theme={"theme":"github-dark-dimmed"}
<script>
    const fpPromise = import('https://metrics.yourwebsite.com/v4/PUBLIC_API_KEY')
      .then(Fingerprint => Fingerprint.start({
            cache: {
                storage: 'sessionStorage',
                duration: 'optimize-cost',
            }
      }))
</script>
```

The `optimize-cost` value caches visitor data for one hour. For all available cache configuration options, see [`CacheConfig`](/reference/js-agent-start-function#cacheconfig) in the `start()` function reference.

### Cache expiration time

We strongly recommend a maximum cache expiration time of **1 hour**.

The properties (e.g. browser version, extensions, screen resolution, IP address, etc) that Fingerprint collects from a browser often change over time. When these incremental changes are captured as soon as they occur, Fingerprint can identify a returning browser with industry-leading accuracy.

Using a longer expiration time leads to:

* Lower identification accuracy. Fingerprint can miss out on the incremental changes thus increasing the risk of incorrectly identifying a returning browser as new.
* Outdated Smart Signals information returned from the [Server API](/reference/server-api-get-event).
* Increased risk of [replay attacks](https://en.wikipedia.org/wiki/Replay_attack).

### Cache location

We strongly recommend using [**sessionStorage**](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) to cache the visitor ID.

Our data indicates sessionStorage is the best option to minimize the impact on identification accuracy compared to both [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) and [cookies](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie).

> Note: A cached visitor ID stored in sessionStorage, localStorage, and cookies will not be available if the user switches to or from Incognito mode.

## What's next

* To protect the JavaScript agent from ad blockers and get maximum identification accuracy and coverage, see [Proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers).
* To improve your identification latency, see [Optimizing JavaScript agent usage](/docs/optimize-javascript-agent).
* See the full JavaScript agent [API Reference](/reference/js-agent).
* Integrate Fingerprint with your server using the [Server API](/reference/server-api), [Webhooks](/docs/webhooks), or [Sealed results](/docs/sealed-client-results).
* If you are looking for device intelligence about mobile devices instead of browsers, see [Android](/docs/native-android-integration) and [iOS](/docs/ios).


# Install CloudFront Integration using CloudFormation
Source: https://docs.fingerprint.com/docs/install-cloudfront-integration-using-cloudformation



<Note>
  **Before you start: Read the general CloudFront guide**

  This document only covers deploying the Fingerprint Cloudfront proxy integration to your AWS account using a CloudFormation template. It assumes you have already read the [general AWS CloudFront Proxy Integration v2 guide](/docs/cloudfront-proxy-integration-v2) and completed the following steps:

  * [Step 1](/docs/cloudfront-proxy-integration-v2#step-1-issue-a-proxy-secret): You have issued a proxy secret in the Fingerprint Dashboard (`FPJS_PRE_SHARED_SECRET`).
  * [Step 2](/docs/cloudfront-proxy-integration-v2#step-2-create-path-variable): You have defined a path variable for the integration (`FPJS_BEHAVIOR_PATH`)

  If want to use Terraform instead of CloudFormation to install the integration, see [Install CloudFront integration using Terraform](/docs/aws-cloudfront-integration-via-terraform).
</Note>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).
</Warning>

## Step 3: Install the CloudFormation application

The Lambda proxy function and associated resources are provided as a CloudFormation template.

### Step 3.1: Create CloudFormation stack

1. Go to the [CloudFormation installation wizard](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?stackName=Fingerprint-Pro-CloudFront-Integration-v2\&templateURL=https://fingerprint-pro-cloudfront-integration.s3.amazonaws.com/v2/template.yml) to open the deployment dialog.
2. Select the `us-east-1` region in your AWS console before deploying the application. Due to [AWS limitations](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-at-edge-function-restrictions.html#lambda-at-edge-restrictions-region), the Lambda proxy function, and therefore the entire CloudFormation stack, must be deployed to the `us-east-1` region.
3. Keep predefined settings:
   1. **Prepare template** is `Choose an existing template`.
   2. **Specify template** is `Amazon S3 URL`.
   3. **Amazon S3 URL** is `https://fingerprint-pro-cloudfront-integration.s3.amazonaws.com/v2/template.yml`
4. Click **Next**.

<img alt="Create CloudFormation stack" />

### Step 3.2: Specify stack details

Provide a stack name and fill in the required template parameters.

* Set **FpjsPreSharedSecret** to the `FPJS_PRE_SHARED_SECRET` value you created in Step 1.

<Info>
  The following parameters, **FpjsAgentDownloadPath** and **FpjsGetResultPath**, can be left at
  their default values because they are only required for JavaScript Agent v3.
</Info>

<Note>
  **Note: Proxy secret required**

  Proxied identification requests without a valid proxy secret will result in an authentication error and not receive identification results.
</Note>

In this step, you need to choose between using an existing CloudFront distribution or creating a new one.

#### A) Use an existing CloudFront distribution (recommended)

If your website is already running on CloudFront, you can use the same distribution and domain for the proxy integration.

This is the recommended setup. Your website and the proxy function will be same-site, served from the same IP address or IP address range. Having the same or similar IP improves cookie lifetimes in Safari — they will be stored in the browser for up to one year instead of 7 days.

* Set **DistributionId** to the identifier of your existing CloudFront distribution.

#### B) Create a new CloudFront distribution

If your website is not running on CloudFront, you can create a new CloudFront distribution and website subdomain just for the proxy integration.

This setup limits Safari cookie lifetime to 7 days. Because your website and the Lambda proxy function will likely have [different IP ranges](https://github.com/WebKit/WebKit/pull/5347), Safari will apply the same cookie lifetime cap as for third-party CNAME cloaking. This is still an improvement over third-party cookies getting blocked entirely by Safari. But we recommend serving your website and the proxy integration using the same CloudFront distribution if possible (option A above).

* Leave **DistributionId** *empty*. The template will create and configure a new CloudFront distribution for you.
* If you want to attach an alternate domain name and custom SSL certificate to the new CloudFront distribution, fill in these parameters:
  * Set **ACMCertificateARN** to the ARN identifier of your SSL certificate in the AWS Certificate Manager.
  * Set **DomainNames** to a list of plus-separated domain names, for example: `domain1.com` or `domain1.com+domain2.com`. These will be attached to the created CloudFront distribution.
    The deployment will fail if any of the domain names is not covered by the certificate or if it is already used as an alternate name for another CloudFront distribution.

Once you have made your choice, click **Next**.

> Note: This application creates the custom IAM roles that allow us to modify CloudFront distribution to keep the Lambda\@Edge function up to date. You can review these policies in the [CloudFormation template](https://github.com/fingerprintjs/aws-cloudfront-proxy/blob/main/cloudformation/template.yml).

### Step 3.3: Configure stack options

Fingerprint integration has no specific stack options to configure at this step. You can change them depending on your internal requirements.

In the **Capabilities and transforms** section:

1. Check *I acknowledge that AWS CloudFormation might create IAM resources.*
2. Check *I acknowledge that AWS CloudFormation might create IAM resources with custom names.*
3. Check *I acknowledge that AWS CloudFormation might require the following capability: CAPABILITY\_AUTO\_EXPAND*

Click **Next**.

### Step 3.4: Review and create

Review the **Parameters** section and click **Submit**.

After deployment, you will be redirected to the CloudFormation Stacks page where you can see a list of resources created by the application.

<img alt="Review and create" />

* The **Status** indicates the current state of deployment. It starts from `REVIEW_IN_PROGRESS` to `CREATE_IN_PROGRESS`, and finally `CREATE_COMPLETE`.
* If you see a different status (`CREATE_FAILED`, `ROLLBACK_IN_PROGRESS`, `ROLLBACK_COMPLETE`, etc), please contact our [support team](mailto:support@fingerprint.com).

Once the application is fully deployed (stack has the status `CREATE_COMPLETE`), you can switch to the **Outputs** tab, and find the names of created entities.

<img alt="Review and create" />

* The *Export name* of `LambdaFunctionName` is a unique name of the created Lambda proxy function.
* The *Export name* of `FingerprintProMgmtLambda` is a unique name of the created Management function responsible for delivering updates to the main Lambda proxy function.
* The *Value* of `CloudFrontDistributionId` is an internal ID of the CloudFront distribution created by the CloudFormation template or your existing CloudFront distribution that you specified in [Step 3.2.A](#a-use-an-existing-cloudfront-distribution-recommended).
* The *Export name* of `FingerprintIntegrationSettingsSecret` is the name of the AWS Secret for the Lambda proxy function. You can save this value somewhere. You might need it in [Step 4.1](#step-4-1-create-a-new-origin).
* The *Export name* of `CachePolicyName` is a unique name of the CloudFront cache policy, which will be applied in a cache behavior for Fingerprint requests. You can save this value somewhere. You might need it in [Step 4.2](#step-4-2-create-a-cache-behavior).
* The *Value* of `MgmtLambdaFunctionUrl` is a public URL of the management Lambda function. You can save this value somewhere. You will need it later to enable automatic updates for your integration in [Step 6](#step-6-enable-automatic-updates-in-the-fingerprint-dashboard).

<Warning>
  **Do not disrupt the Management function**

  The Management Lambda function (`FingerprintProMgmtLambda`) deployed alongside the main proxy function is responsible for updating the integration. It makes sure visitor identification on your website keeps up with new browser releases and fingerprinting evasion techniques. An outdated integration can lead to lower accuracy or break visitor identification completely. Don't disable or delete the management function.
</Warning>

## Step 4: Configure the CloudFront distribution

* If you are using an existing CloudFront distribution already serving your website (you have specified `DistributionId` in [Step 3.2.A](#a-use-an-existing-cloudfront-distribution-recommended)), start from [Step 4.1](#step-4-1-create-a-new-origin) to configure your distribution for the proxy integration.
* If you decided to create a new CloudFront distribution (you have left `DistributionId` empty in [Step 3.2.B](#b-create-a-new-cloudfront-distribution)), the CloudFormation template has deployed a new CloudFront distribution already pre-configured to serve the proxy integration.
  1. Attach an alternate domain name and CNAME if you haven't specified it in [Step 3.2.B](#b-create-a-new-cloudfront-distribution).
  2. Continue to [Step 5](#step-5-configure-the-fingerprint-javascript-agent-on-your-client).

### Step 4.1: Create a new origin

1. Go to your CloudFront distribution, switch to the **Origins** tab, and click **Create origin**.
2. Fill in the required fields:
   1. Set **Origin domain** to `fpcdn.io`.
   2. Set **Protocol** to `HTTPS only`.
   3. Set **Minimum origin SSL protocol** to `TLSv1.2`.
   4. Set **Name** to `fpcdn.io`.
   5. Add a custom header:
      * Set **Header name** to `FPJS_SECRET_NAME`
      * Set **Value** to the *Export name* of `FingerprintIntegrationSettingsSecret` created in [Step 3.4](#step-3-4-review-and-create).
   6. Finally, click **Create origin**.

### Step 4.2: Create a cache behavior

In this step, you will create a cache behavior to proxy requests to the Fingerprint API.

1. Go to your CloudFront distribution.
2. Switch to the **Behaviors** tab and click **Create behavior**.
3. Fill in the required fields:
   1. Set **Path pattern** to a value that matches all routes under `FPJS_BEHAVIOR_PATH`. For example, if `FPJS_BEHAVIOR_PATH=random-path` fill in `random-path*`.
   2. Set **Origin and origin groups** to `fpcdn.io`.
   3. Set the **Viewer protocol policy** to `Redirect HTTP to HTTPS`.
   4. Set the **Allowed HTTP methods** to `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`.
   5. Set **Cache key and origin requests** to `Cache policy and origin request policy (recommended)`.
   6. Set **Cache policy** to a *Custom* policy named `FingerprintProCDNCachePolicy-{id}`. You can find the name of your cache policy in *CloudFormation* > *Stacks* > \_*>\_Outputs* as the *Export name* of `CachePolicyName`.
   7. Set **Origin request policy** to `AllViewer`.
   8. Click **Create behavior**.

<Info>
  **Multi-segment behavior paths**

  We recommend using **single** behavior path segments for simplicity, but it's possible to use more complex ones if needed.
  For example:

  ```dotenv theme={"theme":"github-dark-dimmed"}
  FPJS_BEHAVIOR_PATH="ore54guier/vbcnkxb654"
  ```

  However, this requires adjustment of an additional custom header `FPJS_INTEGRATION_PATH_DEPTH` which describes the number of path segments in the behavior path:

  1. Navigate back to your **fpcdn.io** origin.
  2. Add an additional custom header:
     * Set **Header name** to `FPJS_INTEGRATION_PATH_DEPTH`.
     * Set **Value** to the number of path segments in the behavior path, in our example it's `2`.
     ```
      Segment      Segment
         ↓            ↓
     ore54guier / vbcnkxb654 → 2 path segments
     ```
</Info>

<Warning>
  **Do not change the provided Cache Policy**

  It is intentionally configured with the minimum TTL of `0`. Misconfiguring the policy could disrupt visitor identification and increase false positives (assigning the same visitor ID to different browsers).
</Warning>

### Step 4.3: Attach the Lambda function to the cache behavior

1. Go to **CloudFormation** > **Stacks** and open your newly created stack (named *Fingerprint-Pro-Cloudfront-Integration-v2* by default).
2. Switch to the **Resources** tab, find the resource with the **Logical ID** of `FingerprintProCloudFrontLambda` and click the link in the corresponding **Physical ID** column.

<img alt="CloudFormation Lambda function" />

3. Scroll down and switch to the **Configuration** tab.
4. On the left, click **Triggers**, then click **Add trigger**.
5. Select `CloudFront` as the source and click **Deploy to Lambda\@Edge**.

<img alt="Add a trigger for the Lambda function" />

6. Select **Configure new CloudFront trigger.**
   1. Select your distribution.
   2. Select the cache behavior you created in the previous step.
   3. Set **CloudFront event** to `Origin Request`.
   4. Check **Include body**.
   5. Check **Confirm deploy to Lambda\@Edge**.
   6. Click **Deploy**.

It may take several minutes to add the trigger to the CloudFront distribution. To monitor the progress, go to your CloudFront distribution, switch to the **General** tab, and check the **Last modified** time.

## Step 5: Configure the Fingerprint JavaScript agent on your client

Use the path variables created in [Step 2](/docs/cloudfront-proxy-integration-v2#step-2-create-path-variable) to construct the `endpoints` URL.

If your website and the proxy integration are behind the same CloudFront distribution (you chose [Step 3.2.A](#a-use-an-existing-cloudfront-distribution-recommended)), the JavaScript Agent configuration will use randomized paths inside your domain, for example:

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us',
    region: 'us',
  });

  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  const url = 'https://yourwebsite.com/FPJS_BEHAVIOR_PATH/web/v4/PUBLIC_API_KEY';
  const fpPromise = import(url)
    .then(Fingerprint => Fingerprint.start({
      endpoints: 'https://yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us',
      region: 'us',
    }));
  ```
</CodeGroup>

If you set up a separate CloudFront distribution on your subdomain according to [Step 3.2.B](#b-create-a-new-cloudfront-distribution), the JavaScript Agent configuration will use that subdomain to interact with Fingerprint, for example:

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://metrics.yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us',
    region: 'us',
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  const url = 'https://metrics.yourwebsite.com/FPJS_BEHAVIOR_PATH/web/v4/PUBLIC_API_KEY';
  const fpPromise = import(url)
    .then(Fingerprint => Fingerprint.start({
      endpoints: 'https://metrics.yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us',
      region: 'us',
    }));

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

<Note>
  **Parameter URL nuances:** Pass the region to the `endpoints` parameter in the following format:
  `?region=eu`. The value needs to reflect the [region](/docs/regions) of your application.
</Note>

If everything is configured correctly, you should receive the latest Fingerprint client-side script and the identification result through your CloudFront distribution.

## Step 6: Enable automatic updates in the Fingerprint Dashboard

Keeping the integration up to date is crucial for maintaining maximum identification accuracy. To enable automatic updates, provide the following Management function settings from AWS to the Fingerprint dashboard:

* The public URL of the Management function.
* An authentication token for the Management function.

When a new version of the proxy integration is available, Fingerprint will trigger an update by sending a request to the Management function URL, authenticated with the provided token. The token has only the permissions necessary for this purpose. You can verify the granted permissions in the Management function's Execution role (Stack > Resources > `FpMgmtLambdaFunctionExecutionRole`).

<Warning>
  Note: Only users with the **Owner** or **Admin** role assigned can enable automatic updates for
  the integration in the Dashboard.
</Warning>

### Step 6.1: Find the Management function details in AWS

1. Go to **CloudFormation** > [**Stacks**](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/) and open your newly created stack (named *Fingerprint-Pro-Cloudfront-Integration-v2* by default).

2. Switch to the **Outputs** tab. The *Value* of `MgmtLambdaFunctionUrl` is a public URL of your Management Lambda function. Save it somewhere.

   <img alt="" />

3. Switch to the **Resources** tab. Click the *Physical ID* of the `MgmtSettingsSecret`.

   <img alt="" />

4. Inside the secret page, click **Retrieve secret value** and copy the token value. This is the authentication token for the Management Lambda function. Save it somewhere.

### Step 6.2: Provide the Management function details to the Fingerprint Dashboard

1. Go to **Dashboard** > [**SDKs & integrations**](https://dashboard.fingerprint.com/integrations) > **AWS CloudFront**.
2. If you have multiple environments in your workspace, select the environment scope you want to enable updates for in the top navigation bar. It should be the same environment scope that you used to [create the integration's proxy secret](/docs/cloudfront-proxy-integration-v2#step-1-issue-a-proxy-secret).
3. Click **Enable updates**.
4. Fill in the values of **CloudFront Management Lambda URL** and **Authentication Token** that you retrieved in Step 6.1.
5. Click **Save Changes**.

<img alt="" />

The integration page will show **Status: Updates enabled** and Fingerprint will automatically keep your integration up to date.

## Troubleshooting

If you run into problems, please provide our support team with the following information:

1. Open the integration CloudFormation stack.
2. Go to the **Events** tab, and copy the contents of the **Status reason** column for any failed statuses.

<img alt="" />

## What's next

To learn more about calculating AWS costs and monitoring your CloudFront integration, go back to the [general CloudFront Proxy Integration guide](/docs/cloudfront-proxy-integration-v2#monitoring-and-managing-the-integration).


# Overview
Source: https://docs.fingerprint.com/docs/install-the-javascript-agent

Learn how to install and use the JavaScript agent to identify visitors.

The Fingerprint [JavaScript agent](/reference/js-agent) is a high-performance JavaScript library that collects multiple device and browser signals and sends them to the Fingerprint Platform API for visitor identification and device intelligence analysis. If you are looking for equivalent SDKs for mobile devices, see [Android](/docs/native-android-integration) and [iOS](/docs/ios).

This guide focuses on how to install the JavaScript agent. To explore the JavaScript agent API further, see its [API reference](/reference/js-agent).

You have several options for how to install the JavaScript agent on your website:

* Import the agent directly from a CDN (fastest for a quick test).
* Install the agent loader using NPM (includes TypeScript support).
* Use a frontend SDK for your specific framework like React, Vue, Svelte, or Angular (recommended, includes built-in caching strategies and framework-specific APIs).

<Danger>
  **Sandboxed iframe not supported**

  Do not run the JavaScript agent inside a [sandboxed](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox) iframe. This setup is not supported and may prevent the agent from functioning properly.
</Danger>

Each option is described in more detail below. They all require a Fingerprint Public API key, which you can get by navigating to [**Dashboard**](https://dashboard.fingerprint.com/) > **[API keys](https://dashboard.fingerprint.com/api-keys)**.

You can also see **[SDKs & integrations](https://dashboard.fingerprint.com/integrations)** for code snippets of all the options already personalized with your public API key, [region](/docs/regions), and [proxy integration](/docs/protecting-the-javascript-agent-from-adblockers).

<img alt="" />

## Importing from a CDN

This is the easiest way to start. It's also known as ESM import.

1. Add the HTML code below to your page.
2. Use your public API key at the end of the URL, right after `/v4/`, for example: `https://fpjscdn.net/v4/PUBLIC_API_KEY`.

```ts HTML theme={"theme":"github-dark-dimmed"}
<script type="module">
    // Initialize the agent once at web application startup.
    // Alternatively initialize as early on the page as possible.

    const Fingerprint = await import('https://fpjscdn.net/v4/PUBLIC_API_KEY')
    const fp = Fingerprint.start()

    // Analyze the visitor when necessary.
    const result = await fp.get()
    console.log(result.event_id, result.visitor_id)

</script>
```

<Warning>
  **Always use the latest JavaScript agent**

  Do not copy the JavaScript agent code from `fpjscdn.net` to your codebase.

  We routinely update the JavaScript agent to keep up with the latest browser releases. Always download the latest JavaScript agent, otherwise you may miss critical updates, leading to degraded accuracy or service disruption. If you absolutely must host all JavaScript resources yourself, please reach out to our support at [support@fingerprint.com](mailto:support@fingerprint.com?subject=I%20want%20to%20keep%20JS%20Agent%20code%20on%20my%20server) for a solution.
</Warning>

## Installing the agent loader using NPM

The Fingerprint NPM package works as a **loader** for the JavaScript agent. It does not contain the JavaScript agent code itself; instead, it's responsible for downloading the agent from a CDN at runtime.

We routinely update the JavaScript agent to keep up with the latest browser releases. The NPM package ensures your website always uses the latest, most accurate version of the agent without frequently updating your NPM dependencies and redeploying your application.

* The NPM package includes TypeScript types for a better development experience.
* The package is compatible with various module bundlers such as [Webpack](https://webpack.js.org) and [Rollup](https://rollupjs.org).

To use the NPM package:

1. Install the [@fingerprint/agent](https://www.npmjs.com/package/@fingerprint/agent) NPM package using your favorite package manager.

<CodeGroup>
  ```shell NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/agent
  ```

  ```shell Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/agent
  ```

  ```shell PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/agent
  ```
</CodeGroup>

2. Import the package into your code:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from '@fingerprint/agent'

// Download the agent at application startup and initialize it
const fp = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' })

// Analyze the visitor when necessary.
fp.get()
  .then(result => console.log(result.event_id, result.visitor_id))
```

3. Pass your public API key as `apiKey` into the `start()` function.

You can use your preferred [import syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#forms_of_import_declarations). However, using a namespace import (`import * as Fingerprint from`) instead of a default import ( `import Fingerprint from`) will result in a slightly smaller bundle size due to improved [tree-shaking](https://en.wikipedia.org/wiki/Tree_shaking).

If you use a server-side rendering framework, make sure the NPM package code runs only in the browser, not on the server. For more information, see [Usage with server-side rendering frameworks](/docs/usage-with-server-side-rendering-frameworks).

## Using a framework-specific SDK

We have SDKs for the following frameworks:

* [React](https://github.com/fingerprintjs/react) (includes support for Preact, Next)
* [Vue](https://github.com/fingerprintjs/vue)
* [Angular](https://github.com/fingerprintjs/angular)
* [Svelte](https://github.com/fingerprintjs/svelte)

The SDKs wrap the agent loader NPM package described above, meaning the latest fingerprinting logic is still downloaded from a CDN at runtime. The SDKs expose the JavaScript agent functionality through framework-specific APIs (for example, a provider component and a hook in React). They also have caching and other best practices built in.

If you can, we recommend using one of the framework SDKs above. You can go to **Dashboard** > **[SDKs & integrations](https://dashboard.fingerprint.com/integrations)** to get started with personalized code snippets for the SDKs.

<img alt="React SDK" />

If your application uses a different frontend framework, use the [NPM agent loader](#installing-the-agent-loader-using-npm) directly - it includes the same built-in caching mechanism and works with any framework. The older [`fingerprintjs-pro-spa`](https://github.com/fingerprintjs/fingerprintjs-pro-spa) wrapper is [deprecated in v4](/docs/generic-js-agent-wrapper-for-spas) now that caching is built into the agent.

## Configuring the agent

No matter which installation methods you pick above, you need to initialize the agent with your API key, region, proxy endpoints, and other load options. See the [JavaScript Agent API Reference](/reference/js-agent-start-function#start-options) for a detailed description of all `start()` options. Most users will need the following three options:

* [`apiKey`](/reference/js-agent-start-function#apikey): Go to **Dashboard** > **[API keys](https://dashboard.fingerprint.com/api-keys)** to find your public API key.
* [`region`](/reference/js-agent-start-function#region): If you choose to store your data in the EU or Asia Pacific [region](/docs/regions), you need to specify it in the region `start()` option.
* [`endpoints`](/reference/js-agent-start-function#endpoints): Requests to Fingerprint CDN and API can be blocked by ad blockers. For maximum coverage, we recommend proxying Fingerprint requests through your own domain or subdomain. See [Proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers) for more information. Once you have a proxy integration in place, you will use the `endpoints` start option to specify the proxy endpoints for agent download and identification requests. For the CDN installation method, use the proxy endpoint for agent download directly in the `import` statement.

<CodeGroup>
  ```ts HTML & CDN theme={"theme":"github-dark-dimmed"}
  <script type="module">
    // Initialize the agent on page load.
    // In these snippets we are already using custom subdomain endpoints instead of connecting
    // to Fingerprint servers directly to avoid ad blockers. 
    // See "import" and "endpoints" below.

    const Fingerprint = await import('https://metrics.yourwebsite.com/web/v4/PUBLIC_API_KEY')
    const fp = Fingerprint.start({
      endpoints: 'https://metrics.yourwebsite.com',
      region: 'eu',
    })

    // Get the visitor_id when you need it.
    const result = await fp.get()
    console.log(result.visitor_id)
  </script>
  ```

  ```javascript NPM theme={"theme":"github-dark-dimmed"}
  import Fingerprint from '@fingerprint/agent';

  // Start the agent on application start.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://metrics.yourwebsite.com',
    region: 'eu',
  });

  // Get the visitor_id when you need it.
  fp.get().then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

If you go to **[SDKs & integrations](https://dashboard.fingerprint.com/integrations)** you can find a code snippet for your chosen installation method that already reflects your public key, chosen region, and active integration:

* If you used the CDN or NPM loader installation methods, you can pass the `start()` options as an object into the `Fingerprint.start()` method. Once you have the promise of the JavaScript agent instance, you can resolve it and call `get()` to send an identification requests to Fingerprint API.
* If you used a [framework-specific client SDK](#using-a-framework-specific-sdk), please refer to its documentation for the SDK-specific way of passing the `start()` options object to the JavaScript agent.

## What's next

* Continue by reading [Identify visitors](/docs/identify-visitors) to learn best practices for timing identification requests, caching visitor information, or using linked IDs to associate your own identifiers with each visitor ID.
* See [Configure Content Security policy](/docs/js-agent-csp) to make sure the JavaScript agent is not blocked by your own CSP.
* Concerned about performance and latency? Read our guide on [Optimizing JavaScript agent loading](/docs/optimize-javascript-agent#only-use-the-javascript-agent-where-you-need-it).
* Ready for a deep dive? Explore the full [JavaScript agent API Reference](/reference/js-agent).
* To learn about equivalent SDKs for mobile devices, see [Android](/docs/native-android-integration) and [iOS](/docs/ios).


# Introduction
Source: https://docs.fingerprint.com/docs/introduction

Learn how you can prevent fraud and improve user experiences with Fingerprint.

<iframe title="YouTube video player" />

## What is Fingerprint?

**Fingerprint is a software-as-a-service that identifies online devices and provides valuable information about them.** Fingerprint doesn't scan human fingerprints like biometric systems do. Instead, it creates a unique identifier for each device, called a "Visitor ID," which stays permanently tied to that device. It works on both web browsers and mobile devices, making sure the devices are accurately identified on any platform.

### How it works

Fingerprint uses browser and device fingerprinting along with advanced server techniques, like statistical ID generation and machine learning, to create a unique visitor ID such as **`xPFysGV25VxZcGQUxVIt`**. This ID stays the same over time, even if the device’s settings or software changes or if cookies are deleted or unavailable.

You can see your own device ID by visiting [our demo](https://demo.fingerprint.com/playground). While there, try revisiting in incognito mode or with your VPN on. Your visitor ID will be the same.

Our stable visitor IDs are helpful when people try to hide their identity online, like in fraud detection or protecting accounts. They also make things easier for trusted users by reducing the need for constant logins or CAPTCHA checks because trusted users can be recognized easily. Fingerprint is designed to not need any permissions, so users won’t see permission prompts in their browser or on their phone.

### Our products

Fingerprint has two main products that work together to help you identify and understand your visitors better.

* [**Identification**](https://fingerprint.com/products/identification/): Our main product creates very accurate and stable visitor IDs. These IDs help stop fraud by looking at how devices are used and can also make the user experience better.
* [**Smart Signals**](https://fingerprint.com/products/smart-signals/): Along with Identification, Smart Signals provide extra insights into visitor behavior, like spotting [bots](/docs/smart-signals-reference#browser-bot-detection), [VPN use](/docs/smart-signals-reference#vpn-detection-for-browsers), or [tampered browsers](/docs/smart-signals-reference#browser-tamper-detection). These insights help you identify and respond to suspicious activity more effectively.

## Fingerprint Identification vs. FingerprintJS

Fingerprint's [Identification](https://fingerprint.com/products/identification/) is significantly better than its open-source counterpart, **FingerprintJS**. While both the open-source and proprietary versions identify devices, the proprietary version, Fingerprint Identification, is more accurate and provides detailed, additional information about the device. Please see the FingerprintJS vs. Fingerprint Identification [comparison table](https://github.com/fingerprintjs/fingerprintjs/blob/master/docs/comparison.md) for a feature-by-feature breakdown of the differences.

### FingerprintJS

FingerprintJS has been a key tool for browser fingerprinting since it was created on [GitHub](https://github.com/fingerprintjs/fingerprintjs) in 2012. It’s still the most accurate open-source fingerprinting library, available to all users at no cost.

FingerprintJS is a JavaScript library that collects browser details to make a unique ID called a "fingerprint." It works quickly and runs on the client side, so no backend is needed. However, it has some limits:

* **Same fingerprints on similar devices**: FingerprintJS can give the same fingerprint for devices with the same setup. For example, two iPhone 15s using Safari will have the same fingerprint, which makes it hard to tell them apart.
* **Changes affect fingerprints**: The fingerprints can change when things like time zone, OS, or browser updates happen. This makes them less reliable for long-term use.

### The advantages of Fingerprint Identification

Fingerprint Identification is our main commercial product, offering big improvements over FingerprintJS. It works as a client-server system, using a client-side SDK to gather data and send it to Fingerprint for processing. This allows Fingerprint Identification to:

* **Give more accurate identification**: Unlike FingerprintJS, it can tell apart devices with the same setup (like two iPhone 15s), making sure each device gets a unique and steady visitor ID.
* **Work on more platforms**: It works not just on web browsers but also on mobile devices and connects easily with APIs, webhooks, and cloud tools.
* **Stay stable over time**: The visitor IDs it creates stay the same for months, even with changes to the device or software, making it more reliable for long-term use.

## Fingerprint design patterns

Fingerprint can be used in various ways to prevent fraud and improve user experience. Here are some common patterns to use its visitor IDs effectively:

* Comparing visitor IDs
* Counting visitor IDs linked to data
* Counting data linked to a visitor ID

### Comparing visitor IDs

This pattern generates a visitor ID before important actions, like a login. It is then compared to the previous ID for the same user. If they match, the user can continue without extra checks. If they don’t match, it could mean a different device or an unauthorized attempt, so extra verification, like a one-time code, is recommended. This helps to make sure only authorized users can perform sensitive actions.

### Counting visitor IDs linked to data

Here, each time a key action happens — like logging in, creating an account, or making a purchase — a visitor ID is added to a list for that user or account. If the list gets too big (e.g., more than five IDs), it might mean several devices are being used by the same user. This could suggest account sharing or unauthorized access. This could trigger alerts or ask for extra verification to protect the account.

### Counting data linked to a visitor ID

This pattern tracks how many internal IDs (like account IDs or transaction IDs) are connected to one visitor ID. For example, if a visitor ID is linked to many new account attempts, it could signal possible fraud, like multiple account creation. By looking at these connections, you can spot and prevent fraud, such as account farming or coupon abuse.

## Use cases

Fingerprint can be used in many ways to prevent fraud and improve user experience based on the design patterns mentioned above. Here are three common examples. You can find more on our [demo hub](https://demo.fingerprint.com/).

### Reducing login friction

The pattern used here is ***comparing visitor IDs***.

Compare the visitor IDs from past and current logins to make logging in easier without compromising security. The first time a user logs in, create and save a visitor ID. For future logins, create a new ID and compare it to the saved one. If they match, the login can go through without extra checks. This reduces friction while keeping the login process secure.

### Account sharing prevention

The pattern used here is ***counting visitor IDs linked to data***.

By counting the number of visitor IDs accessing a single account, you can effectively prevent account sharing. For example, if more than a certain number of devices (e.g., more than 3) are used to log into the same account, you can prompt the user to verify their identity or restrict further logins until they confirm ownership. This approach ensures that the account is used as intended without relying on frequent MFA or other disruptive measures.

### New account fraud

The pattern used here is ***counting data linked to a visitor ID***.

In some use cases, users shouldn’t be able to create multiple accounts. Instead of using methods like Single Sign-On or phone validation every time, which can hurt the user experience, generate a visitor ID each time a new account is created. If the number of accounts linked to that ID is small (e.g., 3 or fewer), let it continue. If the number is high (e.g., more than 3), trigger extra checks, like phone validation, to prevent fraud.

## Future-proof, reliable, and secure

Browsers like Safari, Chrome, and Brave are adding more privacy features, like Safari 17's updates, Google’s Privacy Sandbox, and Brave’s anti-fingerprinting. It’s normal to wonder what this means for the future of fingerprinting. However, Fingerprint is still a strong and reliable solution.

For over 10 years, Fingerprint has provided industry-leading accuracy. Some browsers have added tools to block fingerprinting. These tools haven’t worked well because fingerprinting uses basic browser APIs required for building web applications. Blocking it completely would break parts of the internet.

Even if future updates make fingerprinting less effective, Fingerprint Identification will still be one of the most accurate for two reasons:

1. **Universal Impact**: Any browser changes will affect all identification solutions, but Fingerprint will remain highly accurate in comparison, even if slightly less so.
2. **Hybrid Approach**: Fingerprint Identification combines server data with browser data to create stable visitor IDs. The server-side component keeps accuracy high as browsers change.

Fingerprint is also built to perform well without crashing your app. It has strong error handling and a timeout feature, making integration smooth. If generating a visitor ID takes too long (like on older devices), the process stops safely, avoiding disruptions for users.

On the security side, Fingerprint makes it very hard for attackers to fake a visitor ID. Developers can check for ID mismatches and add extra security checks when needed without annoying users. With these protections, Fingerprint stays a reliable and secure solution that can adapt to browser changes while keeping its accuracy and performance high.

## Want to get help?

If you're a developer, please join our [Discord channel](https://discord.com/invite/39EpE2neBg) for technical discussions.

If you’re a GitHub user, please use [discussions](https://github.com/fingerprintjs/fingerprintjs/discussions) and open [issues](https://github.com/fingerprintjs/fingerprintjs/issues).

If you’re a customer, our [US-based support](https://fingerprint.com/support/) is always ready to help!

***

What’s Next

* [Start your free workspace now](https://dashboard.fingerprintjs.com/signup/)
* [Quick Start Guide](/docs/quick-start-guide)
* [Install the JavaScript agent](/docs/install-the-javascript-agent)


# iOS devices
Source: https://docs.fingerprint.com/docs/ios

Fingerprint's device intelligence platform for iOS devices.

Fingerprint's device intelligence platform is also available for iOS devices. Our device intelligence platform for iOS helps you to accurately identify the devices that interact with your mobile app and provides high-quality Smart Signals that will help you identify risky transactions before they happen.

To make integrations with mobile apps easier, we offer SDKs for apps built natively as well as for apps built using multi-platform frameworks (e.g. React Native).

A Fingerprint account is required to be able to use the Fingerprint Identification SDK in your mobile apps. If you do not have an account yet, please [sign up](https://dashboard.fingerprintjs.com/signup) for one.

<Check>
  **Download our** [**demo app**](https://apps.apple.com/us/app/fingerprint-pro/id1644105278) from App Store to see Fingerprint in action!
</Check>

## Device Identifier

When Fingerprint Identification SDK is integrated into your mobile app, for every device that interacts with your app, you will be able to receive a unique device identifier (i.e. `visitorId`). The visitor ID is derived solely from Apple's [identifierForVendor](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) (IDFV) property. The SDK does not use any fingerprinting techniques to identify a device.

However, despite the visitor ID being derived from IDFV, there are a few important differences between them:

* The visitor ID will remain the same even when the app is removed and re-installed whereas the IDFV will not.
* In addition to being scoped by the vendor, the visitor ID is also scoped by the [Fingerprint Workspace](/docs/glossary#fingerprint-workspace). It means the only time the visitor ID remains the same between two apps is when the apps are from the same vendor **and** when they belong to the same Fingerprint workspace.

<Info>
  **Did you know?**

  The device identifier generated by the iOS SDK (embedded within your mobile app) will be **different** from the visitor ID generated by the Javascript agent (embedded within your website).
</Info>

The identification accuracy, when compared with browsers, is better for iOS devices because the IDFV property has higher longevity than the signals used for identifying browsers.

For your reference, we have listed various scenarios where a visitor ID will remain the same before and after and where a new visitor ID will be created.

| Scenario                                                                                                                                                                                | Will I receive the same visitor ID before and after?                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The app or device is restarted                                                                                                                                                          | **Yes.** You will receive the same visitor ID even after the app or device is restarted.                                                                                                                                       |
| The app is uninstalled and re-installed again                                                                                                                                           | **Yes.** You will receive the same visitor ID even after the app is removed and installed again                                                                                                                                |
| The [provisioning profile](https://developer.apple.com/documentation/technotes/tn3125-inside-code-signing-provisioning-profiles) and/or the signing certificate of the app are changed. | **Yes.** You will receive the same visitor ID as long as the [AppID](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/AppID.html) remains the same before and after the change. |
| The device is jailbroken                                                                                                                                                                | **Yes.** You will receive the same visitor ID as before even after the device is jailbroken.                                                                                                                                   |
| [Lockdown mode](https://support.apple.com/en-us/HT212650) is enabled on the device                                                                                                      | **Yes.** You will receive the same visitor ID as before even after lockdown mode is enabled on the device.                                                                                                                     |
| [Reset device settings to their default values](https://support.apple.com/guide/iphone/return-iphone-settings-to-their-defaults-iphea1c2fe48/ios)                                       | **Yes.** You will receive the same visitor ID as before even after one or more of the device settings are reset to their default.                                                                                              |
| [The device is factory reset](https://support.apple.com/en-us/HT201274)(i.e. all content and settings are erased).                                                                      | **No**. After the device is factory reset, a new visitor ID will be generated.                                                                                                                                                 |

## iOS Smart Signals

Smart Signals are actionable device intelligence signals that help you to make informed decisions about the device and thus prevent fraud. These signals could be used as input to your machine learning models behind your fraud detection or risk mitigation engines. For example, when you know that a request is originating from a *jailbroken* device, you will be able to take additional precautionary security steps (e.g., multi-factor authentication).

When your mobile app requests a visitor ID, the SDK, along with the IDFV, will collect several other attributes from the device. The Smart Signals are deduced by combining these attributes with additional algorithms.

For iOS, the following Smart Signals are available:

* [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection)
* [Frida Detection](/docs/smart-signals-reference#frida-detection)
* [Geolocation Spoofing Detection](/docs/smart-signals-reference#geolocation-spoofing-detection)
* [IP Geolocation Detection](/docs/smart-signals-reference#ip-geolocation)
* [IP Blocklist Detection](/docs/smart-signals-reference#ip-blocklist-matching)
* [Jailbroken Device Detection](/docs/smart-signals-reference#jailbroken-device-detection)
* [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection)
* [Tampered Request Detection](/docs/smart-signals-reference#tampered-request-detection-for-mobile-apps)
* [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices)
* [iOS Simulator Detection](/docs/smart-signals-reference#ios-simulator-detection)
* [Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection-for-mobile-devices)
* [Smart Signals common for browsers and mobile devices](/docs/smart-signals-reference#smart-signals-common-for-browsers-and-mobile-devices)

These Smart Signals are available as part of our [Pro Plus and Enterprise plans](https://fingerprint.com/pricing/). If you are interested in one or more of these signals, please [contact our support team](https://fingerprint.com/support/) to enable them. Signing up for an Enterprise plan does not automatically enable these signals.

## Fingerprint Identification SDK for iOS

<Info>
  ### Current Version: 2.17.2

  For release notes and older versions, please visit the [Changelog for iOS SDK](/docs/changelog-ios-sdk) page.
</Info>

### Supported Versions

The minimum version that the iOS SDK for Fingerprint Identification supports is [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes), [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes). Per [Apple](https://developer.apple.com/support/app-store/) and [Statista](https://www.statista.com/statistics/565270/apple-devices-ios-version-share-worldwide/), this will allow your app to be compatible with a wide variety of active iOS devices.

As of May 2023, our SDK will allow your app to be compatible with more than 94% of the devices in the world.

### Getting Started Guides

Our Getting Started guides are aimed at helping you to integrate our SDK with your apps easily.

* For native iOS apps, see [Getting Started Guides > iOS](/docs/ios-sdk) and our [iOS quickstart](/docs/ios-quickstart).
* For apps built using Flutter, see our [Flutter SDK on GitHub](https://github.com/fingerprintjs/fingerprintjs-pro-flutter) and our [Flutter quickstart](/docs/flutter-quickstart).
* For apps built using React Native, see our [React Native SDK on GitHub](https://github.com/fingerprintjs/react) and our [React Native quickstart](/docs/react-native-quickstart).

## Privacy Manifest File Requirements for App Store

During WWDC 2023, Apple [introduced a new requirement](https://developer.apple.com/news/?id=av1nevon) where app and SDK developers must create privacy manifest files to declare the data that their app/SDK collects and the reasons for collecting this data. Accordingly, starting from v2.3.2, the Fingerprint Identification SDK for iOS will include a privacy manifest file. To learn more, please see [Understanding privacy manifest files](/docs/mobile-devices-understanding-privacy-manifest-files).

## FingerprintJS-iOS: Open-source identification library for iOS

We also provide a lightweight, open-source library called [fingerprintjs-ios](https://github.com/fingerprintjs/fingerprintjs-ios) which is available to use for free by everyone. Our commercial SDK, Fingerprint Identification for iOS, is based on our well-maintained, free, open-source library.

For your better understanding, here is a complete set of differences between our open-source library (`fingerprintjs-ios`) and our commercial SDK (`fingerprint-ios`).

|                                                                                       | FingerprintJS-iOS(fingerprintjs-ios)                                                                                                                                   | Fingerprint Identification for iOS(fingerprint-ios)                                                                                                                    |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Core Features                                                                         |                                                                                                                                                                        |                                                                                                                                                                        |
| **Attributes collected from the device**                                              | Basic (*e.g. OS, Model*)                                                                                                                                               | Advanced. Lot more attributes, in addition to those collected by the open-source library.                                                                              |
| **ID Type**                                                                           | A visitor ID that is solely derived from Apple's [identifierForVendor](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) property. | A visitor ID that is solely derived from Apple's [identifierForVendor](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) property. |
| **ID Origin**                                                                         | The visitor ID is generated only from within the device. External servers are not involved.                                                                            | The visitor ID is generated from within the device and also processed in our servers.                                                                                  |
| **Is visitor ID the same across multiple apps on a single device?**                   | **No.** Unless the apps are from the same vendor.                                                                                                                      | **No.** Unless the apps are from the same vendor and belong to the same Fingerprint workspace.                                                                         |
| **ID Collisions**                                                                     | Common                                                                                                                                                                 | Very rare                                                                                                                                                              |
| Support for multi-platform frameworks                                                 |                                                                                                                                                                        |                                                                                                                                                                        |
| **Flutter**                                                                           | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| **React Native**                                                                      | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| Advanced Features                                                                     |                                                                                                                                                                        |                                                                                                                                                                        |
| **Server API and Webhooks**\*(Build flexible workflows)\*                             | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| **Mobile Smart Signals**\*(VPN Detection, Factory Reset, Geolocation Spoofing, etc)\* | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| **Geolocation**\*(Based on IP address)\*                                              | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| Operations                                                                            |                                                                                                                                                                        |                                                                                                                                                                        |
| **Data security**                                                                     | Depends on your infrastructure                                                                                                                                         | Encrypted at rest                                                                                                                                                      |
| **Storage**                                                                           | Depends on your infrastructure                                                                                                                                         | Unlimited up to 1 year                                                                                                                                                 |
| **Regions**                                                                           | Depends on your infrastructure                                                                                                                                         | Global, EU and Asia data centers                                                                                                                                       |
| **Compliance**                                                                        | Depends on your infrastructure                                                                                                                                         | Compliant\*\*\* with GDPR, US Privacy Laws including CCPA, SOC 2 Type II, and ISO 27001                                                                                |
| **SLA**                                                                               | SLA is not provided                                                                                                                                                    | 99.9% Uptime                                                                                                                                                           |
| **General Support**                                                                   | GitHub Issues/Questions. Response times varies.                                                                                                                        | Dedicated support team that responds to chat, email, and calls within 1 business day                                                                                   |
| **Support for submitting an app to App Store**                                        | Not available.                                                                                                                                                         | Dedicated support will be provided to the extent resulting from using the Fingerprint Identification SDK.                                                              |
| How to get started?                                                                   | [Get it on GitHub](https://github.com/fingerprintjs/fingerprintjs-ios)                                                                                                 | [Sign up for a free 14-day trial](https://dashboard.fingerprintjs.com/signup/)                                                                                         |

\*\*In comparison to fingerprints, VisitorIDs are more accurate and stable identifiers because they are deduplicated, are processed further on the server, and utilize fuzzy matching. On the other hand, fingerprint hashes become unstable across time intervals greater than 2 weeks because they rely on an exact match of all browser attributes.

\*\*\*The company, Fingerprint, in its role as data processor is compliant with GDPR, US Privacy Laws (including CCPA) and SOC 2 Type II. It is also ISO 27001 certified. As a data controller, it is still your responsibility to be compliant with GDPR and US Privacy Laws (including CCPA) and use the identification result for legitimate purposes


# iOS Quickstart
Source: https://docs.fingerprint.com/docs/ios-quickstart

Get started using the iOS SDK

## Overview

In this quickstart, you'll add Fingerprint to a new Xcode iOS app and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend mobile integration. You'll install the [Fingerprint iOS SDK](/docs/ios-sdk) and initialize the client agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* Sign up for an account with Fingerprint to get your API key. (see below)
* Xcode [16.0](https://developer.apple.com/documentation/xcode-release-notes/xcode-16-release-notes) or higher. See [App Store submission](https://developer.apple.com/app-store/submitting/) requirements for more information.

<Note>
  This quickstart only covers the **frontend setup**. You'll need a [backend
  server](/reference/server-sdks) to receive and process the device identification event to enable
  fraud detection. Check out one of the [backend quickstarts](/docs/server-quickstarts-overview)
  after completing this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the client agent.

## 2. Set up your project

To get started, create a new Xcode project. If you already have a project you want to use, you can skip to the next section.

1. Open Xcode and create a new project.
2. Click on iOS and select App, then click Next.
3. Enter a name (e.g., `FingerprintQuickstart`), and an organization identifier (e.g., `com.example`), and make sure to use Swift and SwiftUI.
4. Click Next, choose a save location, and create the project.

## 3. Install the client agent

To integrate Fingerprint into your iOS app, add the package to your project.

1. In Xcode, go to File > Add Package Dependencies…
2. Enter the package URL: `https://github.com/fingerprintjs/fingerprint-ios`
3. Choose the latest version and click Add Package.
4. In the Choose Package Products pop-up, make sure to check your app target (e.g., `FingerprintQuickstart`) under "Add to Target" so the SDK is properly linked.

## 4. Initialize the SDK

Open your `ContentView.swift` or app entry point and:

1. Import the SDK:

```swift ContentView.swift theme={"theme":"github-dark-dimmed"}
import Fingerprint
```

2. Initialize the SDK with your public API key and region:

```swift ContentView.swift theme={"theme":"github-dark-dimmed"}
static let region: Region = .eu
static let configuration = Configuration(
    apiKey: "PUBLIC_API_KEY",
    region: region
)
```

3. Replace `PUBLIC_API_KEY` with your actual public API key from the Fingerprint [dashboard](https://dashboard.fingerprint.com/api-keys). Use .global, .eu, or .ap based on your workspace region. See region [**guide**](/docs/regions).

## 5. Trigger visitor identification

Now that the client agent is initialized, you can identify the visitor when needed. In this case, that's when the user taps a **Create Account** button.

When making the visitor identification request, you will receive the `visitorId` as well as an `eventId`. Instead of using the `visitorId` returned directly on the frontend (which could be tampered with), you'll send the `eventId` to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

## Add a basic sign-up UI

1. Create a new SwiftUI function for the account creation screen. It will display a simple form with username and password fields, along with a **Create Account** button:

```swift ContentView.swift theme={"theme":"github-dark-dimmed"}
func AccountCreationForm(
    username: Binding<String>,
    password: Binding<String>,
    logOutput: Binding<String>,
    onSubmit: @escaping () -> Void
) -> some View {
    VStack(spacing: 20) {
        Text("Create Account")
            .font(.title)
            .foregroundColor(.orange)

        TextField("Username", text: username)
            .textFieldStyle(.roundedBorder)
            .autocapitalization(.none)

        SecureField("Password", text: password)
            .textFieldStyle(.roundedBorder)

        Button("Create Account") {
            onSubmit()
        }
        .buttonStyle(.borderedProminent)
        .tint(.orange)

        if !logOutput.wrappedValue.isEmpty {
            Text("Log: \(logOutput.wrappedValue)")
                .font(.caption)
                .foregroundColor(.gray)
                .multilineTextAlignment(.center)
                .padding(.top, 10)
        }
    }
}
```

2. In the ContentView struct; just before the `body` variable; add the `createAccount()` function that would be triggered when the **Create Account** button is clicked:

```swift ContentView.swift theme={"theme":"github-dark-dimmed"}
struct ContentView: View {
    @State private var username = ""
    @State private var password = ""
    @State private var logOutput = ""

    let fingerprintClient = FingerprintFactory.getInstance(configuration)

    func createAccount() async {
        do {
            let response = try await fingerprintClient.getVisitorIdResponse()

            let eventId = response.eventId

            print("Event ID: \(eventId)")

            // Send username, password, and eventId to your backend server for processing

        } catch {
            print("Fingerprint error: \(error)")
            logOutput = "Error: \(error.localizedDescription)"
        }
    }
    //...
}
```

3. Update the body variable of the ContentView struct with the AccountCreationForm function:

```swift ContentView.swift theme={"theme":"github-dark-dimmed"}
struct ContentView: View {
    @State private var username = ""
    @State private var password = ""
    @State private var logOutput = ""

    let fingerprintClient = FingerprintFactory.getInstance(configuration)

    func createAccount() async {
        do {
            let response = try await fingerprintClient.getVisitorIdResponse()

            let eventId = response.eventId

            print("Event ID: \(eventId)")

            // Send username, password, and eventId to your backend server for processing
        } catch {
            print("Fingerprint error: \(error)")
            logOutput = "Error: \(error.localizedDescription)"
        }
    }

    var body: some View {
        VStack(spacing: 20) {
            AccountCreationForm(
                username: $username,
                password: $password,
                logOutput: $logOutput,
                onSubmit:{
                    Task {
                        await createAccount()
                    }
                }
            )
        }
        .padding()
    }
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

This interface:

* Displays a basic form for account creation.
* Calls `getVisitorIdResponse()` to identify the visitor.
* Captures the `eventId`, which you'll forward to your server for analysis.

## 6. Run the app

1. Select an iOS simulator or real device in Xcode.
2. Build and run the app (⌘R).
3. Enter a username and password then click **Create Account**.
4. Check your Xcode console for something like:

```text Output theme={"theme":"github-dark-dimmed"}
Event ID: 1753730090897.s4bWk4
```

You're now successfully identifying the device and capturing the event ID and are ready to send it to your backend for further fraud prevention logic!

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the `eventId` to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information and make decisions.

Check out these related resources:

* [iOS SDK reference](/docs/ios-sdk)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# iOS SDK
Source: https://docs.fingerprint.com/docs/ios-sdk

A simple guide to integrate Fingerprint's device intelligence platform in your native iOS apps.

In this guide, you will learn how to:

* Include the SDK in your iOS apps.
* Get a `visitorId`.
* Read the SDK response.
* Enable location data collection (optional; to start getting additional location-based proximity data).
* Configure the SDK as per your needs.
* Specify additional metadata in your identification request.
* Handle errors.

For a complete example of how to use this SDK in your app, please visit the [GitHub repo of our demo app](https://github.com/fingerprintjs/fingerprint-device-intelligence-ios-demo/). View our [iOS quickstart](/docs/ios-quickstart) for a step-by-step guide to get started.

## Prerequisites

1. [Sign up](https://dashboard.fingerprintjs.com/signup) for an account with Fingerprint to get your API key.
2. [Xcode 16.0](https://developer.apple.com/documentation/xcode-release-notes/xcode-16-release-notes) or higher. See [App Store submission requirements](https://developer.apple.com/app-store/submitting/) for more information.

## Including the SDK in your app

Add the SDK as a dependency:

### Swift Package Manager

```Text SPM theme={"theme":"github-dark-dimmed"}
// Add the below lines to Package.swift
let package = Package(
  // ...
  dependencies: [
    .package(url: "https://github.com/fingerprintjs/fingerprint-ios", from: "4.0.0")
  ],
  // ...
)
```

### CocoaPods

```ruby Podfile theme={"theme":"github-dark-dimmed"}
# Add the below line to the Podfile
pod 'Fingerprint-iOS', '~> 4.0'
```

<Warning>
  CocoaPods is deprecated. Following the [CocoaPods project's own shutdown plans](https://blog.cocoapods.org/CocoaPods-Specs-Repo/), it will stop accepting new versions in December 2026. Existing versions will keep working, but we recommend Swift Package Manager, which is the preferred installation method.
</Warning>

## Getting a `visitorId`

To get a `visitorId`, you need the public API key that you obtained when signing up for an account with Fingerprint. You can find this API key in the **Dashboard** > [**API Keys**](https://dashboard.fingerprint.com/api-keys).

Here is an example that shows you how to get a `visitorId`:

```swift theme={"theme":"github-dark-dimmed"}
import Fingerprint

// Configure the SDK.
//
// The "region" must match the region associated with your API key.
let region: Region = .ap
//
// For custom subdomain or proxy integration, use ".custom(domain:fallback:)" region that lets
// you specify a custom endpoint.
// let region: Region = .custom(domain: "https://example.com")
//
// Additionally, you may also specify alternate, fallback endpoints to redirect failed requests
// let region: Region = .custom(
//   domain: "https://example.com",
//   fallback: [
//     "https://one.fallback.com",
//     "https://two.fallback.com",
//   ]
// )
//
let configuration = Configuration(
  apiKey: "PUBLIC_API_KEY",
  region: region
)

// Initialize the SDK with the configuration created above.
let client = FingerprintFactory.getInstance(configuration)

Task {
  do {
    // Get a "visitorId".
    let visitorId = try await client.getVisitorId()
    print(visitorId)
  } catch {
    print(error.localizedDescription)
  }
}
```

### Specifying a custom timeout

**Default timeout value:** 60 seconds

You can override the default timeout with a custom value of your choice. If the `getVisitorId()` call does not complete within the specified (or default) timeout, you will receive a `FPError.clientTimeout` error.

Here is an example that shows you how to specify a custom `timeout`:

```swift Swift theme={"theme":"github-dark-dimmed"}
Task {
  do {
    // Get a `visitorId` or, otherwise, time-out after 5 seconds.
    let visitorId = try await client.getVisitorId(timeout: 5.0)
    print(visitorId)
  } catch let error as FPError {
    print(error.description)
  } catch {
    print(error.localizedDescription)
  }
}
```

Catch `FPError` and use its `description` property for a human-readable message (for example, `The session timed out.`). The system `localizedDescription` returns an obfuscated string such as `The operation couldn't be completed. (Fingerprint... error 6.)`, which hides the actual cause.

## Reading the response

The function `FingerprintClientProviding.getVisitorIdResponse()` returns the response in a `FingerprintResponse` object.

```swift Swift theme={"theme":"github-dark-dimmed"}
Task {
  do {
    // Get a `sealedResult`.
    let response = try await client.getVisitorIdResponse()
    if let sealedResult = response.sealedResult {
      print(sealedResult)
    }
  } catch {
    print(error.localizedDescription)
  }
}
```

The FingerprintResponse object has the following fields, some of which can be empty/invalid when [Sealed Client Results](/docs/sealed-client-results) is enabled for your account.

| Field              | Sealed Client Results is disabled                                                                                                                                 | Sealed Client Results is enabled                                                                                                                                                                                                       |   |
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| **`version`**      | [String](https://developer.apple.com/documentation/swift/string). The API version.                                                                                | [String](https://developer.apple.com/documentation/swift/string). The API version.                                                                                                                                                     |   |
| **`eventId`**      | [String](https://developer.apple.com/documentation/swift/string). An identifier that uniquely identifies the event associated with the API call.                  | [String](https://developer.apple.com/documentation/swift/string). An identifier that uniquely identifies the event associated with the API call.                                                                                       |   |
| **`visitorId`**    | [String](https://developer.apple.com/documentation/swift/string). An identifier that uniquely identifies the device.                                              | N/A                                                                                                                                                                                                                                    |   |
| **`suspectScore`** | [Int?](https://developer.apple.com/documentation/swift/int). A score estimating the likelihood that a device is associated with fraudulent or malicious activity. | N/A                                                                                                                                                                                                                                    |   |
| **`sealedResult`** | `nil`                                                                                                                                                             | [String](https://developer.apple.com/documentation/swift/string)?. An encrypted, binary, Base64-encoded String that contains the same response as you would receive with an [`/events API`](/reference/server-api-get-event)  request. |   |

## Using Location Data for Proximity Detection

<Note>
  This is optional. Enable this only if you want to include the additional location-based [proximity detection](/docs/smart-signals-reference#proximity-detection) signal in your response.
</Note>

Starting the [iOS SDK v2.10.0+](/docs/changelog-ios-sdk#v2-10-0), new property [allowUseOfLocationData](/docs/ios-sdk#allowuseoflocationdata) has been added to the [Configuration](/docs/ios-sdk#configuring-the-sdk) structure. This allows the Fingerprint client to access device location data when available. By default, it is set to `false`. To start getting Proximity ID and related data, set this property to `true` in your SDK configuration.

**Important note:**  For the best location precision, we recommend initializing the Fingerprint client **as early as possible - ideally during your app startup** - and maintaining the same instance throughout the app’s lifecycle.

```swift theme={"theme":"github-dark-dimmed"}
let configuration = Configuration(
    apiKey: "PUBLIC_API_KEY",
    region: region,
    allowUseOfLocationData: true
  )
```

### Handling Location Permissions

Your app is responsible for asking for location permissions. Refer to [Apple documentation](https://developer.apple.com/documentation/bundleresources/choosing-the-location-services-authorization-to-request) or check the [Fingerprint demo app](https://apps.apple.com/us/app/fingerprint-pro/id1644105278) if you need to implement this flow. If you already have this process set up, skip to the next section. If your app doesn't currently implement a flow for requesting and managing location permissions, we've included a utility to help simplify this process.

The `LocationPermissionHelper` is designed to assist host apps with requesting, observing, and responding to user location permission changes. It leverages a `LocationPermissionDelegate` to notify the host app whenever the authorization status is updated. This simplifies the integration process without needing to build a full permission handling flow from scratch.

Here is an example that shows how to create a location permission helper:

```swift Swift theme={"theme":"github-dark-dimmed"}
// Create location permission helper.
let helper = FingerprintFactory.getLocationPermissionHelperInstance()
helper.delegate = LocationPermissionDelegateImpl()

class LocationPermissionDelegateImpl: NSObject, LocationPermissionDelegate {
var authorizationStatus: CLAuthorizationStatus = .notDetermined

// Request permission or prompt to change settings.
func locationPermissionHelper(
    _ helper: LocationPermissionHelperProviding,
    shouldShowLocationRationale rationale: LocationPermissionRationale
) {
    switch rationale {
    case .needInitialPermission:
        helper.requestPermission()
    case .upgradeToPrecise:
        helper.requestPermanentPrecisePermission()
    case .needSettingsChange:
        helper.requestPermanentPrecisePermission()
    @unknown default:
        os_log("Received unknown rationale")
    }
}

// React to permission state changes.
  func locationPermissionHelper(
      _ helper: LocationPermissionHelperProviding,
      didUpdateLocationPermission status: CLAuthorizationStatus
  ) {
      authorizationStatus = status
  }
}

/// Represents reasons for showing a location permission rationale to the user.
public enum LocationPermissionRationale {

    /// The app has not yet requested any location permissions.
    /// A rationale should be shown before requesting for the first time.
    case needInitialPermission

    /// The user has denied or restricted location access.
    /// A rationale should be shown with instructions to change settings manually.
    case needSettingsChange

    /// The app has "When In Use" permission, but only reduced (approximate) accuracy is granted.
    /// A rationale should be shown encouraging the user to enable full (precise) accuracy via settings
    /// or give it temporarily.
    case upgradeToPrecise
}
```

Make sure to declare location permissions in `Info.plist` as it is required for App Store submission:

* `NSLocationWhenInUseUsageDescription` - required; for general system request when asking for location access.
* `NSLocationTemporaryUsageDescriptionDictionary`with `ProximityID`  purpose key - optional; for general system request when asking for temporary precise location in case the user has a setting that hides accurate location.
* `NSLocationAlwaysAndWhenInUseUsageDescription` - optional, only if your app requires checking location in background mode; for general system request when asking to always have access to the user's location (including background). It will also require `UIBackgroundModes` to have `location` in `Info.plist` to access the user's location in the background.
* Request permission in your app's code
  * Call `requestPermission()` or `requestPrecisePermission()` from the SDK, depending on the level of access needed.
  * Or use your own location permission flow.
* Show rationale UI (optional)
  * You may present your own UI to explain why location is needed.

## Configuring the SDK

Using the [Configuration](/docs/ios-sdk#configuration) object, it is possible to configure the SDK as per your requirements. As of now, the following options are supported:

### `region`

**Type:** [Region](/docs/ios-sdk#region).

**Default value:** `Region.global`

Specifies the region where your data will be stored and processed. The selected region must match the one configured when registering your app with Fingerprint.\
For custom subdomain or proxy integrations, use the `Region.custom(domain:fallback:)` enumeration case. This allows you to define:

* `domain` - Your primary custom endpoint (e.g., custom subdomain or proxy URL) where requests will be sent.
* `fallback` *(optional)* - A list of alternate endpoints that will be used automatically if requests to the primary domain fail. This helps improve reliability and availability in case of connectivity or routing issues.

Use this option when you have configured a custom subdomain or implemented a proxy integration. See [region](/reference/js-agent-start-function#region) for more information.

### `allowUseOfLocationData`

**Type:** [Bool](https://developer.apple.com/documentation/swift/bool)

**Default value:** `false`

This option allows you to enable the location data collection needed to calculate the [location-based proximity detection signal](/docs/smart-signals-reference#proximity-detection).

## Specifying `linkedId` and `tag`

Like the [JavaScript agent](/reference/js-agent-get-function#linkedid), the iOS SDK also supports providing custom metadata with your identification request. To learn more about this capability, please visit [Linking and tagging information](/docs/tagging-information).

Here is an example that shows you how to associate your identification request with an account ID and additional metadata:

```swift Swift theme={"theme":"github-dark-dimmed"}
let client = FingerprintFactory.getInstance("PUBLIC_API_KEY")

// Associate an account number to this request.
var metadata = Metadata(linkedId: "accountID")
// Associate additional metadata to this request.
metadata.setTag("purchase", forKey: "actionType")
metadata.setTag(10, forKey: "purchaseCount")

Task {
  // Get a `visitorId`.
  if let visitorId = try? await client.getVisitorId(metadata) {
    print(visitorId)
  }
}
```

The metadata you want to include may not be available when making the identification request. For such scenarios, you can [update that event](/reference/server-api-update-event) later when the required metadata becomes available. A typical workflow is explained in [`Update linked_id and tags on the server`](/docs/tagging-information#updating-linked_id-and-tags-on-the-server).

## Handling errors

The SDK provides a [FPError](/docs/ios-sdk#error) enumeration that helps you identify the reasons behind an unsuccessful identification request. Here is an example that shows you how to handle errors in your app:

```swift Swift theme={"theme":"github-dark-dimmed"}
do {
  let visitorId = try await client.getVisitorId()
  print(visitorId)
} catch FPError.clientTimeout {
  print("Request timed out.")
} catch FPError.apiError(let apiError) {
  if let errorDetails = apiError.errorDetails {
    print("API error: \(errorDetails.message)")
  }
} catch {
  print("Could not obtain visitor ID due to an error: \(error.localizedDescription)")
}
```

## Data Classes

### Configuration

```swift Swift theme={"theme":"github-dark-dimmed"}
/// A type that represents a single key/value parameter with the library integration
/// information.
public typealias IntegrationInfo = (String, String)

/// A library configuration specifying various options for configuring the Fingerprint Client
/// instance.
public struct Configuration: Sendable {
  /// A public API key obtained from [Fingerprint Dashboard](https://dashboard.fingerprint.com).
  public var apiKey: String
  /// The Fingerprint Server API region.
  public var region: Fingerprint.Region
  /// An array of key/value parameters identifying a particular library integration.
  ///
  /// This property should only be used when creating an integration wrapper around the library
  /// (e.g. Flutter or React Native wrapper).
  public var integrationInfo: [Fingerprint.IntegrationInfo]
  /// A Boolean value that determines whether collection of device locations is allowed.
  public var allowUseOfLocationData: Bool

  /// Creates a library configuration object with the specified parameters.
  ///
  /// - Note: API keys are region-specific, so make sure you have selected the correct region
  ///         when calling this initializer.
  ///
  /// - Parameters:
  ///   - apiKey: A public API key obtained from
  ///             [Fingerprint Dashboard](https://dashboard.fingerprint.com).
  ///   - region: The Fingerprint Server API region. Defaults to ``Region/global``.
  ///   - integrationInfo: An array of key/value parameters identifying a particular library
  ///                      integration. Defaults to an empty array.
  ///   - allowUseOfLocationData: A Boolean value that determines whether collection of device
  ///                             locations is allowed. Defaults to `false`.
  public init(
      apiKey: String,
      region: Fingerprint.Region = .global,
      integrationInfo: [Fingerprint.IntegrationInfo] = [],
      allowUseOfLocationData: Bool = false
  )
}
```

### Error

```swift Swift theme={"theme":"github-dark-dimmed"}
/// An error type that indicates problems with the device fingerprinting.
public enum FPError: Error {
  /// An error that indicates the server URL is invalid.
  case invalidURL
  /// An error that indicates the integration info URL parameters are invalid.
  case invalidURLParams
  /// An API error returned by the Fingerprint backend.
  case apiError(APIError)
  /// A network error.
  case networkError(any Error)
  /// A JSON parsing error that indicates the HTTP payload is malformed.
  case jsonParsingError(any Error)
  /// An error that indicates the response is invalid.
  case invalidResponseType
  /// An error that indicates the client-side session timed out.
  case clientTimeout
  /// Unknown error.
  case unknownError
}

extension FPError: CustomStringConvertible {
  /// An error description.
  public var description: String { get }
}

/// A Fingerprint Server API error.
public struct APIError: Decodable, Sendable {
  /// The API version.
  public let version: String
  /// The identifier that uniquely identifies an event.
  public let eventId: String
  /// The error details.
  public let errorDetails: ErrorDetails?
}

public extension APIError {
  /// The details about a reason that the API request failed.
  struct ErrorDetails: Decodable, Sendable {
    /// A code that represents the error, as defined by ``APIError/Code`` enum.
    public let code: APIError.Code?
    /// A detailed error message.
    public let message: String
  }
}

public extension APIError {
  /// An enumeration representing known Fingerprint API error codes.
  enum Code: String, Decodable, Sendable {
    case requestCannotBeParsed = "request_cannot_be_parsed"
    case requestReadTimeout = "request_read_timeout"
    case secretApiKeyRequired = "secret_api_key_required"
    case secretApiKeyNotFound = "secret_api_key_not_found"
    case publicApiKeyRequired = "public_api_key_required"
    case publicApiKeyNotFound = "public_api_key_not_found"
    case subscriptionNotActive = "subscription_not_active"
    case wrongRegion = "wrong_region"
    case featureNotEnabled = "feature_not_enabled"
    case visitorNotFound = "visitor_not_found"
    case tooManyRequests = "too_many_requests"
    case stateNotReady = "state_not_ready"
    case failed = "failed"
    case eventNotFound = "event_not_found"
    case missingModule = "missing_module"
    case payloadTooLarge = "payload_too_large"
    case serviceUnavailable = "service_unavailable"
    case rulesetNotFound = "ruleset_not_found"
    case invalidProxyIntegrationSecret = "invalid_proxy_integration_secret"
    case proxyIntegrationSecretEnvironmentMismatch = "proxy_integration_secret_environment_mismatch"
    case invalidProxyIntegrationHeaders = "invalid_proxy_integration_headers"
    case subscriptionRestricted = "subscription_restricted"
    case environmentRestricted = "environment_restricted"
    case subscriptionNotFound = "subscription_not_found"
    case installationMethodRestricted = "installation_method_restricted"
  }
}
```

### Region

```swift Swift theme={"theme":"github-dark-dimmed"}
/// The Fingerprint Server API region.
public enum Region: Equatable, Sendable {
  /// A default Global (US) region.
  case global
  /// A European (EU) region.
  case eu
  /// An Asia-Pacific (APAC) region.
  case ap
  /// A custom endpoint with optional fallback endpoints, as defined by the `domain` and `fallback`
  /// associated values.
  case custom(domain: String, fallback: [String] = [])
}
```

### Check out these related resources:

* [iOS SDK changelog](/docs/changelog-ios-sdk)
* [iOS Quickstart](/docs/ios-quickstart)
* [Migrating the Fingerprint iOS SDK from v2 to v4](https://docs.fingerprint.com/reference/migrating-ios-sdk-from-v2-to-v4)


# Java Server Quickstart
Source: https://docs.fingerprint.com/docs/java-server-quickstart

Get started using the Java Server SDK

## Overview

In this quickstart, you'll add Fingerprint to a [Java](https://www.oracle.com/java/) server using the [Spring Boot](https://spring.io/projects/spring-boot) framework to prevent fraudulent account creation.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. You can flag and block suspicious users by identifying the device behind each sign-up attempt, login, or transaction.

In this quickstart, you'll learn how to:

* Set up a Spring Boot server with a [Fingerprint integration](https://github.com/fingerprintjs/java-sdk)
* Retrieve visitor identification data using the Server API
* Block bots and suspicious devices
* Prevent multiple signups from the same device

This guide focuses on the backend integration and must be completed after identifying a visitor and generating an event ID. **Before starting this quickstart, start with one of the [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview) quickstarts to see how to identify a visitor in your frontend.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* **A completed frontend or mobile Fingerprint implementation (See the quickstarts)**
* [Java](https://www.oracle.com/java/) (v11, v17, v21, or v25) installed
* Your favorite code editor or IDE
* Basic knowledge of Java and Spring Boot

## 1. Get your secret API key

<Note>
  Before starting this quickstart, you should already have a frontend Fingerprint implementation
  that sends the `event_id` to your server. If not, pause here and check out one of the
  [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview)
  quickstarts first.
</Note>

If you're ready:

1. Sign in and go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the Fingerprint dashboard.
2. Create a new **secret API key**.
3. Copy it somewhere safe so you can use it to retrieve full visitor identification data from the Server API.

## 2. Set up your project

To get started, you need a basic Spring Boot server. If you already have a project, skip to the next step.

1. Go to [**start.spring.io**](https://start.spring.io/)
2. Configure the project:
   * **Project:** Maven (or Gradle if you prefer)
   * **Language:** Java
   * **Spring Boot:** 4.x latest version
   * **Dependencies:**
     * Spring Web
     * Spring Data JPA
   * *Everything else can remain as default*
3. Click **Generate** to download the starter project and unzip it.
4. Open the project in your IDE and add these dependencies to your build file:

**Maven (pom.xml):**

```xml pom.xml theme={"theme":"github-dark-dimmed"}
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- SQLite JDBC -->
    <dependency>
        <groupId>org.xerial</groupId>
        <artifactId>sqlite-jdbc</artifactId>
        <version>3.44.1.0</version>
    </dependency>

    <!-- Hibernate dialects for SQLite -->
    <dependency>
        <groupId>org.hibernate.orm</groupId>
        <artifactId>hibernate-community-dialects</artifactId>
    </dependency>

    <!-- Fingerprint Java Server SDK -->
    <dependency>
        <groupId>com.github.fingerprintjs</groupId>
        <artifactId>java-sdk</artifactId>
        <version>v8.7.0</version>
    </dependency>
</dependencies>
```

**Gradle (build.gradle):**

```groovy build.gradle theme={"theme":"github-dark-dimmed"}
repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'org.xerial:sqlite-jdbc:3.44.1.0'
    implementation 'org.hibernate.orm:hibernate-community-dialects'
    implementation 'com.github.fingerprintjs:java-sdk:v8.7.0'
}
```

*Note: This quickstart is written for version 8.x of the Fingerprint Java Server SDK. Additional installation methods are detailed in the [SDK documentation](/reference/java-server-sdk).*

5. Update the file at `src/main/resources/application.properties` with the following content:

```properties application.properties theme={"theme":"github-dark-dimmed"}
spring.application.name=demo
server.port=3000
spring.datasource.url=jdbc:sqlite:database.db
spring.datasource.driver-class-name=org.sqlite.JDBC
spring.jpa.database-platform=org.hibernate.community.dialect.SQLiteDialect
spring.jpa.hibernate.ddl-auto=create-drop
```

*Note: `spring.jpa.hibernate.ddl-auto=create-drop` is for demo purposes to reset the database each time the app starts.*

You can run the project with:

* Maven:

```bash Terminal theme={"theme":"github-dark-dimmed"}
./mvnw spring-boot:run
```

* Gradle:

```bash Terminal theme={"theme":"github-dark-dimmed"}
./gradlew bootRun
```

6. Create a basic controller `src/main/java/com/example/demo/AccountController.java`:

```java AccountController.java theme={"theme":"github-dark-dimmed"}
package com.example.demo;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api")
public class AccountController {

    @PostMapping("/create-account")
    public ResponseEntity<Map<String, String>> createAccount(@RequestBody CreateAccountRequest request) {
        return ResponseEntity.ok(Map.of("status", "Account created!"));
    }
}
```

7. Create a data transfer object (DTO) class to represent the JSON payload your frontend will send when creating an account at `src/main/java/com/example/demo/CreateAccountRequest.java`:

```java CreateAccountRequest.java theme={"theme":"github-dark-dimmed"}
package com.example.demo;

public class CreateAccountRequest {
    @com.fasterxml.jackson.annotation.JsonProperty("event_id")
    private String eventId;
    private String username;
    private String password;

    public String getEventId() { return eventId; }
    public void setEventId(String eventId) { this.eventId = eventId; }

    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }

    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }
}
```

Here we are running the server at port 3000 and have created a new POST route for account creation. Note that the `/api/create-account` route should match what you have set up in your frontend implementation where you are sending the Fingerprint `event_id` to your server. Your server will receive the initial identification information from identifying a visitor on the frontend and use it to get the full visitor data on the backend.

## 3. Initialize Fingerprint and retrieve visitor data

Now you'll configure the Fingerprint Java Server SDK using your secret API key and use it to fetch detailed visitor data for each signup attempt.

When making the initial visitor identification request in the frontend, you received an `event_id`. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. Create a Fingerprint configuration class `src/main/java/com/example/demo/FingerprintConfig.java`:

```java FingerprintConfig.java theme={"theme":"github-dark-dimmed"}
package com.example.demo;

import com.fingerprint.v4.api.FingerprintApi;
import com.fingerprint.v4.sdk.ApiClient;
import com.fingerprint.v4.sdk.Configuration;
import com.fingerprint.v4.sdk.Region;
import org.springframework.context.annotation.Bean;

@org.springframework.context.annotation.Configuration
public class FingerprintConfig {

    @Bean
    public FingerprintApi fingerprintApi() {
        ApiClient client = Configuration.getDefaultApiClient(
            "SECRET_API_KEY",
            Region.GLOBAL
        );
        return new FingerprintApi(client);
    }
}
```

*For a production implementation make sure to store and reference your secret key securely.*

2. Update your `AccountController` to use the Fingerprint API and retrieve the full visitor identification details with `getEvent()`:

<Note>
  **requestId vs event\_id:** Depending on which quickstart you completed, your frontend may send
  either `requestId` (older SDKs) or `event_id` (v4 and newer). Both refer to the same
  identification event and work with the Server API in the same way. Use whichever value your
  frontend sends (`requestId` or `event_id`) as the event identifier below.
</Note>

```java AccountController.java theme={"theme":"github-dark-dimmed"}
package com.example.demo;

import com.fingerprint.v4.api.FingerprintApi; // [!code ++]
import com.fingerprint.v4.model.Event; // [!code ++]
import com.fingerprint.v4.sdk.ApiException; // [!code ++]
import org.springframework.beans.factory.annotation.Autowired; // [!code ++]
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api")
public class AccountController {

    @Autowired // [!code ++]
    private FingerprintApi fingerprintApi; // [!code ++]

    @PostMapping("/create-account")
    public ResponseEntity<Map<String, String>> createAccount(@RequestBody CreateAccountRequest request) {
        try { // [!code ++]
            Event event = fingerprintApi.getEvent(request.getEventId()); // [!code ++]

            return ResponseEntity.ok(Map.of("status", "Account created!"));
        } catch (ApiException e) { // [!code ++]
            return ResponseEntity.badRequest() // [!code ++]
                .body(Map.of("error", "Error processing request")); // [!code ++]
        } // [!code ++]
    }
}
```

Using the `event_id` the Fingerprint server client will retrieve the full data for the visitor identification request. The returned object will contain the visitor ID, IP address, device and browser details, and Smart Signals like bot detection, incognito mode detection, and detections for VPN or virtual machine use.

You can see a full example of the event structure, and test it with your own device, in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 4. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection Smart Signal which is available only on paid plans.
</Note>

A simple but powerful way to prevent fraudulent account creation is to block automated signups that come from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

1. Continuing in your `/api/create-account` route, check the bot signal returned in the `event` object:

```java AccountController.java theme={"theme":"github-dark-dimmed"}
import com.fingerprint.v4.model.BotResult; // [!code ++]

@PostMapping("/create-account")
public ResponseEntity<Map<String, String>> createAccount(@RequestBody CreateAccountRequest request) {
    try {
        Event event = fingerprintApi.getEvent(request.getEventId());

        if (event.getBot() != BotResult.NOT_DETECTED) { // [!code ++]
            return ResponseEntity.status(403) // [!code ++]
                .body(Map.of("error", "Failed to create account.")); // [!code ++]
        } // [!code ++]

        return ResponseEntity.ok(Map.of("status", "Account created!"));
    } catch (ApiException e) {
        return ResponseEntity.badRequest()
            .body(Map.of("error", "Error processing request"));
    }
}
```

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `notDetected` when no bot activity is found. You can also layer in other Smart Signals to catch more suspicious devices. For example, you can use Fingerprint's [Suspect Score](/docs/suspect-score) to determine when to add additional friction to create an account.

## 5. Prevent multiple signups from the same device

To catch repeated signups from the same device, you can use the `visitorId` from the Fingerprint identification event. By saving this ID alongside each created account, you can detect and block duplicate signups from the same device. We'll be using a simple database to demonstrate how this works with SQLite.

1. Create an Account entity `src/main/java/com/example/demo/Account.java`:

```java Account.java theme={"theme":"github-dark-dimmed"}
package com.example.demo;

import jakarta.persistence.*;

@Entity
@Table(name = "accounts")
public class Account {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String username;
    private String password;
    private String visitorId;

    public Account() {}

    public Account(String username, String password, String visitorId) {
        this.username = username;
        this.password = password;
        this.visitorId = visitorId;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }

    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }

    public String getVisitorId() { return visitorId; }
    public void setVisitorId(String visitorId) { this.visitorId = visitorId; }
}
```

2. Create a repository interface `src/main/java/com/example/demo/AccountRepository.java`:

```java AccountRepository.java theme={"theme":"github-dark-dimmed"}
package com.example.demo;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface AccountRepository extends JpaRepository<Account, Long> {
    long countByVisitorId(String visitorId);
}
```

3. Update your `AccountController` to use the database and check for existing accounts:

```java AccountController.java theme={"theme":"github-dark-dimmed"}
package com.example.demo;

import com.fingerprint.v4.api.FingerprintApi;
import com.fingerprint.v4.model.BotResult;
import com.fingerprint.v4.model.Event;
import com.fingerprint.v4.sdk.ApiException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/api")
public class AccountController {

    @Autowired
    private FingerprintApi fingerprintApi;

    @Autowired // [!code ++]
    private AccountRepository accountRepository; // [!code ++]

    @PostMapping("/create-account")
    public ResponseEntity<Map<String, String>> createAccount(@RequestBody CreateAccountRequest request) {
        try {
            Event event = fingerprintApi.getEvent(request.getEventId());

            if (event.getBot() != BotResult.NOT_DETECTED) {
                return ResponseEntity.status(403)
                    .body(Map.of("error", "Failed to create account."));
            }

            String visitorId = event.getIdentification().getVisitorId(); // [!code ++]

            long existingAccounts = accountRepository.countByVisitorId(visitorId); // [!code ++]
            if (existingAccounts > 0) { // [!code ++]
                return ResponseEntity.status(429) // [!code ++]
                    .body(Map.of("error", "Failed to create account.")); // [!code ++]
            } // [!code ++]

            Account newAccount = new Account(request.getUsername(), request.getPassword(), visitorId); // [!code ++]
            accountRepository.save(newAccount); // [!code ++]

            return ResponseEntity.ok(Map.of("status", "Account created!"));
        } catch (ApiException e) {
            return ResponseEntity.badRequest()
                .body(Map.of("error", "Error processing request"));
        }
    }
}
```

This gives you a basic system to detect and block repeat signups. You can expand on this by allowing a limited number of accounts per device, adjusting your response based on business rules, only evaluating recent signups, etc.

<Info>
  This is a minimal example to show how to use the Fingerprint Java Server SDK. In a real
  application, make sure to implement proper security practices, especially around password handling
  and storage.
</Info>

## 6. Test your implementation

Now that everything is set up, you can test the full flow using your existing frontend.

### Before you test

If your frontend is running on a different port (like localhost:5173 or localhost:3001), you may run into CORS issues for testing. To quickly fix this for local development & testing:

1. Add the `@CrossOrigin` annotation to your `AccountController`:

```java AccountController.java theme={"theme":"github-dark-dimmed"}
@RestController
@RequestMapping("/api")
@CrossOrigin(origins = "*", allowedHeaders = "*") // [!code ++]
public class AccountController {
```

### Test the implementation

1. Start your Spring Boot server:

* Maven:

```bash Terminal theme={"theme":"github-dark-dimmed"}
./mvnw spring-boot:run
```

* Gradle:

```bash Terminal theme={"theme":"github-dark-dimmed"}
./gradlew bootRun
```

2. In your frontend, trigger a sign-up request that sends the `event_id`, `username`, and `password` to your `/api/create-account` endpoint. To see the reply messages make sure to parse and display or console log the response from your server.
3. Within your frontend, input a username and password to create a user. Then try to create another user and see that the second attempt will be rejected.
4. Bonus: Try creating an account using a headless browser.

## Next steps

You now have a working backend fraud check using Fingerprint. From here, you can expand your logic with more Smart Signals, adjust thresholds based on your risk tolerance, or introduce additional checks for suspicious users.

These same techniques apply to a wide range of fraud prevention use cases, from detecting fake reviews to blocking payment abuse or preventing account takeovers.

To go further, check out the use case tutorials for step-by-step guides tailored to specific problems you can solve with Fingerprint.

Check out these related resources:

* [Java SDK Reference](https://github.com/fingerprintjs/java-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# JavaScript Agent API Reference
Source: https://docs.fingerprint.com/docs/javascript-agent





# JavaScript Quickstart
Source: https://docs.fingerprint.com/docs/javascript-quickstart

Get started using the JavaScript agent

## Overview

In this quickstart, you'll add Fingerprint to a new vanilla JavaScript project (scaffolded with Vite) and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend integration. You'll load the [JavaScript agent](/docs/install-the-javascript-agent) and initialize it to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

<Note>
  This quickstart only covers the **frontend setup**. You'll need a [backend
  server](/reference/server-sdks) to receive and process the device identification event to enable
  fraud detection. Check out one of the [backend quickstarts](/docs/server-quickstarts-overview)
  after completing this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the JavaScript agent.

## 2. Set up your project

To get started, scaffold a new vanilla JavaScript app with Vite. If you already have a project you want to use, skip to the next section.

1. Create a new Vite project with the vanilla JavaScript template:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm create vite@latest fingerprint-js-quickstart -- --template vanilla
cd fingerprint-js-quickstart
npm install
```

2. Open the `fingerprint-js-quickstart` folder in your code editor and you're ready to go! To run your project, run:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

3. In your browser, go to [http://localhost:5173](http://localhost:5173/) (Vite's default), and you should see the Vite welcome page.

## 3. Set up your account creation form

1. Before adding Fingerprint, add an account creation form to `index.html`:

```javascript index.html theme={"theme":"github-dark-dimmed"}
<body>
  <div class="wrapper">
    <h1>Create an account</h1>
    <div class="input-group">
      <label for="username">Username</label>
      <input id="username" type="text" placeholder="Username" required />
    </div>
    <div class="input-group">
      <label for="password">Password</label>
      <input id="password" type="password" placeholder="Password" required />
    </div>
    <button id="create-account-btn">Create Account</button>
  </div>
  <script type="module" src="/src/main.js"></script>
</body>
```

2. Add some simple styling by overwriting the `src/style.css` file with the following:

```css src/style.css theme={"theme":"github-dark-dimmed"}
html,
body {
  margin: 0;
  font-family: "Inter", sans-serif;
}

.wrapper {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  margin: 0 auto;
  max-width: 400px;
  min-height: 100vh;
  gap: 1rem;
  padding: 1rem;
}

input {
  width: 100%;
  padding: 0.5rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}

.input-group {
  width: 100%;
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 0.5rem;
}

button {
  background-color: #f35b22;
  color: #fff;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 4px;
  cursor: pointer;
}
```

## 4. Install and initialize the JavaScript agent

1. To integrate Fingerprint into your app, first install the JavaScript agent via npm:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/agent
```

*Note: This quickstart is written for version 4.x of the JavaScript agent*

2. Now that the JavaScript agent is installed, import and initialize it. Open `src/main.js` and replace it with:

```javascript src/main.js theme={"theme":"github-dark-dimmed"}
import "./style.css";
import Fingerprint from "@fingerprint/agent";

const fp = Fingerprint.start({
  apiKey: "PUBLIC_API_KEY",
  region: "us", // Ensure this matches your workspace region
  // For more options, see https://docs.fingerprint.com/reference/js-agent-start-function
});
```

3. Replace `PUBLIC_API_KEY` with your actual public API key from the [Fingerprint dashboard](https://dashboard.fingerprint.com/api-keys).

*Note: For production, consider using* [*Vite Env Variables*](https://vite.dev/guide/env-and-mode) *to configure the key.*

## 5. Trigger visitor identification

Now that the JavaScript agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps the “Create Account” button.

When making the visitor identification request, you will receive the `visitor_id` as well as an `event_id`. Instead of using the `visitor_id` returned directly on the frontend (which could be tampered with), you'll send the `event_id` to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. After initializing the JavaScript agent, grab the HTML elements and add an event listener for clicking on the button:

```javascript src/main.js theme={"theme":"github-dark-dimmed"}
const usernameInput = document.getElementById("username");
const passwordInput = document.getElementById("password");
const btn = document.getElementById("create-account-btn");
btn.addEventListener("click", handleClick);
```

2. Then, define the `handleClick` function as follows:

```javascript src/main.js theme={"theme":"github-dark-dimmed"}
async function handleClick() {
  // Trigger identification
  const { visitor_id, event_id } = await fp.get();
  console.log("Visitor ID:", visitor_id);
  console.log("Event ID:", event_id);

  // Send to your backend
  // await fetch("/api/create-account", {
  //   method: "POST",
  //   headers: { "Content-Type": "application/json" },
  //   body: JSON.stringify({
  //     username: usernameInput.value,
  //     password: passwordInput.value,
  //     event_id,
  //   }),
  // });
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

Inside the `handleClick` function:

* Use `fp.get()` to have Fingerprint analyze the visitor's browser and identify the visitor
* You can then send the `event_id` to your backend, along with the username and password for your fraud prevention logic.

## 6. Test the app

1. If your dev server isn't already running, start it with:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. In your browser, go to [http://localhost:5173](http://localhost:5173) (Vite's default).
3. If you have any ad blockers, turn them off for localhost. View the [documentation](/docs/protecting-the-javascript-agent-from-adblockers) to learn how to protect your Fingerprint implementation from ad blockers in production.
4. Enter a username and password, then click **Create Account**.
5. Open the developer console in your browser, and you should see the `visitor_id` and `event_id` in the output:

```Output theme={"theme":"github-dark-dimmed"}
Visitor ID: JkLmNoPqRsTuVwXyZaBc
Event ID: 1234566477745.abc1GS
```

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the `event_id` to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information data and use it to make decisions and prevent fraud.

Check out these related resources:

* [JavaScript agent reference](/reference/js-agent)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Configure Content Security Policy (CSP)
Source: https://docs.fingerprint.com/docs/js-agent-csp



If you have a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) on your website, it can block the JavaScript agent. JavaScript agent will throw a special error in this case:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
try {
  const fp = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' })
  await fp.get()
} catch (error) {
  if (error.code === 'csp_block') {
    // Your CSP blocks the JavaScript agent
    // Can be thrown by both "start" and "get"
  }
}
```

Add the following directives to your policy to unblock the JavaScript agent and the WebWorker download:

<CodeGroup>
  ```text CDN installation theme={"theme":"github-dark-dimmed"}
  script-src https://fpjscdn.net;
  connect-src https://api.fpjs.io https://*.api.fpjs.io;
  worker-src blob:;
  ```

  ```text NPM installation theme={"theme":"github-dark-dimmed"}
  script-src https://fpnpmcdn.net;
  connect-src https://api.fpjs.io https://*.api.fpjs.io;
  worker-src blob:;
  ```
</CodeGroup>

If you already have such directives in your policy, add the given addresses to the directives. An example of combining a couple of policies:

<CodeGroup>
  ```text Current policy theme={"theme":"github-dark-dimmed"}
  default-src 'self';
  connect-src 'self' example.com;
  style-src 'self' 'unsafe-inline';
  ```

  ```text JavaScript agent policy theme={"theme":"github-dark-dimmed"}
  connect-src https://api.fpjs.io https://*.api.fpjs.io;
  worker-src blob:;
  ```

  ```text Combined policy theme={"theme":"github-dark-dimmed"}
  default-src 'self';
  connect-src 'self' example.com https://api.fpjs.io https://*.api.fpjs.io;
  style-src 'self' 'unsafe-inline';
  worker-src blob:;
  ```
</CodeGroup>

An example of an HTML code with a Content Security Policy that lets JavaScript agent work:

<CodeGroup>
  ```html HTML theme={"theme":"github-dark-dimmed"}
  <!DOCTYPE html>
  <html>
    <head>
      <meta http-equiv="Content-Security-Policy" content="
        default-src 'self';
        script-src 'self' https://fpjscdn.net;
        connect-src 'self' https://api.fpjs.io https://*.api.fpjs.io;
        worker-src blob:;
      ">
    </head>
    ...
  </html>
  ```
</CodeGroup>

## Automatic updates

The default endpoints used by JavaScript agent may change with automatic updates. JavaScript agent uses fallback endpoints to evade ad blockers that block JavaScript agent. The fallback endpoints are changed when they get to ad blocker lists. So you should check this guide from time to time for up-to-date CSP recommendations to ensure your CSP doesn't block the fallback endpoints.

The primary endpoint (`https://api.fpjs.io` or `https://*.api.fpjs.io`) is never changed automatically to prevent JavaScript agent from being blocked by your CSP.

## Subdomain setup

If you've set up JavaScript agent to use [a custom endpoint](/docs/custom-subdomain-setup), add the endpoint to the policy instead of the built-in endpoint. For example, if your custom endpoint is `https://fp.yourdomain.com`, your policy is:

<CodeGroup>
  ```text Text theme={"theme":"github-dark-dimmed"}
  script-src https://fp.yourdomain.com;
  connect-src https://fp.yourdomain.com;
  worker-src blob:;
  ```
</CodeGroup>


# Loan Fraud
Source: https://docs.fingerprint.com/docs/loan-fraud-use-case-tutorial

Learn how to detect and prevent fraudulent loan applications

## Overview

This tutorial shows how to implement Fingerprint to prevent loan application fraud, where applicants try to game the system by submitting multiple applications using slightly altered personal details, fake identities, or devices that show signs of automation or tampering.

You'll begin with a starter app that includes a mock loan application page and a basic review flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to check if they've already submitted an application. Additionally, you'll see how to use Smart Signals to block or flag suspicious devices submitting applications. This way, you can flag or block repeat submissions from the same device or suspicious sources.

By the end, you'll have a sample app that detects duplicate or high-risk loan applications per visitor and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `loan-risk` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Loan application form" />

    <Tree.File name="index.js - Front-end logic to handle loan submissions" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="loans.js - Loan and risk detection logic" />

    <Tree.File name="server.js - Serves static files and loan endpoint" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock loan application page from the starter app. You can test out the basic coupon flow by changing the inputs and clicking **Request loan**. You'll notice you can apply for loans with new personal details an unlimited amount of times.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Request loan**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the loan data. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including the verified visitor ID and risk signals such as browser tampering or bot activity.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Request loan** button already has an event handler set up for submitting a loan application. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the loan to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
requestBtn.addEventListener("click", async () => {
  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  const data = {
    firstName: firstNameEl.value,
    lastName: lastNameEl.value,
    loanAmount: amountRange.value,
    monthlyIncome: incomeRange.value,
    loanTerms: termRange.value,
    eventId,
  };

  // ...
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your loan application logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file already defines API routes for the app. The `/api/loan-risk` route passes the request body to the `requestLoan` function defined in `server/loans.js`. Because the frontend now sends `eventId` in the payload, that value will be available in the body when `requestLoan` runs.

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/loan-risk", async (req, reply) => {
  const result = await requestLoan(req.body);
  return reply.send(result);
});
```

2. The `server/loans.js` file contains the logic for handling loan applications and will contain the rest of the tutorial. Start by importing and initializing the Fingerprint Node Server SDK there, loading your environment variables with `dotenv`, and importing the `crypto` package for use later:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";
import crypto from "crypto";
const MONTHLY_RATE = 0.15;

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `requestLoan` function to also extract the `eventId` from the passed request body and use it to fetch the full identification event details from Fingerprint:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
export async function requestLoan(data) {
  const { firstName, lastName, loanAmount, monthlyIncome, loanTerms, eventId } = data;

  if ((!firstName || !lastName || !loanAmount || !monthlyIncome || !loanTerms, !eventId)) {
    console.error("Missing required fields.");
    return { success: false, message: "Missing required fields." };
  }

  const event = await fpServerApiClient.getEvent(eventId);

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection and Suspect Score Smart Signals, which are only
  available on paid plans.
</Note>

A simple but powerful way to prevent fraudulent loan applications is to block automated applications that come from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found.

1. Continuing in the `requestLoan` function in `server/loans.js`, after the existing `loanData` object, check the bot signal returned in the `event` object:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
export async function requestLoan(data) {
  // ...

  const loanData = { ... };

  const botDetected = event.bot !== "not_detected";

  if (botDetected) {
    recordLoanApplication(loanData, "rejected");
    console.error("Bot detected.");
    return { success: false, error: "Loan application denied." };
  }

  // ...
}
```

Note that the code also records the loan application using the loan data passed from the request body. This data is used later when checking the applicant's data from previous loan applications.

You can also use Fingerprint's [Suspect Score](/docs/suspect-score) to flag suspicious loan applications for manual review. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload, helping to identify suspicious activity.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and flags the loan application for review if it exceeds a chosen threshold (for example, 20):

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
export async function requestLoan(data) {
  // ...

  const suspectScore = event.suspect_score || 0;

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    recordLoanApplication(loanData, "rejected");
    return { success: false, error: "Loan application denied." };
  }

  // ...
}
```

## 6. Detect inconsistent loan applications per visitor

Next, use the trusted visitor ID from the `event` object to check for past loan applications submitted from the same device. When a new application is submitted, check if a record exists for the current visitor ID. If it does, compare the stored personal details to the new ones. If they don't match, it indicates the applicant is trying to change their personal details to start a new loan, and the application is denied. This makes fraud detection enforceable at the device level, not just by account or identity details. Even if someone uses new personal information, fake identities, or alternate emails, their applications are still linked to the same device, helping you catch attempts to game the system.

Note: The starter app includes a SQLite database with the following table already created for you to store loan applications:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
loan_applications - Stores the loan applications
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  visitorId TEXT,
  firstName TEXT NOT NULL,
  lastName TEXT NOT NULL,
  monthlyIncome INTEGER NOT NULL,
  loanAmount INTEGER NOT NULL,
  loanTerms INTEGER NOT NULL,
  status TEXT NOT NULL,
  createdAt INTEGER NOT NULL
```

1. First, within the `requestLoan` function, retrieve the `visitor_id` from the `event` object and update the `loanData` variable to include it:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
export async function requestLoan(data) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id;

  const loanData = {
    firstName,
    lastName,
    monthlyIncome,
    loanAmount,
    loanTerms,
    visitorId,
  };

  // ...
}
```

2. Add some helper functions to the bottom of the `server/loans.js` file. The first one generates a hash based on personal details. This is just a simple way to quickly compare details for this demo:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
// Generate personal hash
function genPersonalHash({ firstName, lastName, monthlyIncome }) {
  const norm = [
    firstName.trim().toLowerCase().replace(/\s+/g, ""),
    lastName.trim().toLowerCase().replace(/\s+/g, ""),
    Number(monthlyIncome),
  ].join("|");
  return crypto.createHash("sha256").update(norm).digest("hex");
}
```

3. The next helper function retrieves the first application submitted by the visitor (if it exists) and compares the personal details from that application to the current one:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
// Check if the visitor details are consistent
function isConsistent({ visitorId, firstName, lastName, monthlyIncome }) {
  const personalHash = genPersonalHash({
    firstName,
    lastName,
    monthlyIncome,
  });

  const row = db
    .prepare(
      `SELECT firstName, lastName, monthlyIncome FROM loan_applications WHERE visitorId = ?
    ORDER BY createdAt ASC LIMIT 1`,
    )
    .get(visitorId);

  if (!row) return true;

  const originalHash = genPersonalHash({
    firstName: row.firstName,
    lastName: row.lastName,
    monthlyIncome: row.monthlyIncome,
  });

  return originalHash == personalHash;
}
```

4. To limit the total number of applications allowed by a visitor, regardless of the details entered, add another helper function to get the current number of applications made by the visitor:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
// Check how many loan applications have been made by the visitor
function getApplicationCount(visitorId) {
  return db.prepare(`SELECT COUNT(*) FROM loan_applications WHERE visitorId = ?`).get(visitorId);
}
```

5. Also update the existing `recordLoanApplication` helper function to include the `visitorId` when recording loan applications:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
function recordLoanApplication(data, status) {
  const { firstName, lastName, loanAmount, monthlyIncome, loanTerms, personalHash, visitorId } =
    data;

  db.prepare(
    `INSERT INTO loan_applications (visitorId, firstName, lastName, monthlyIncome, loanAmount, loanTerms, personalHash, status, createdAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
  ).run(
    visitorId,
    firstName,
    lastName,
    monthlyIncome,
    loanAmount,
    loanTerms,
    personalHash,
    status,
    Date.now(),
  );
}
```

6. Return to the `requestLoan` function and use the helper functions to enforce consistent personal details per visitor and limit the number of applications:

```javascript server/loans.js theme={"theme":"github-dark-dimmed"}
export async function requestLoan(data) {
  // ...

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    recordLoanApplication(loanData, "rejected");
    return { success: false, error: "Loan application denied." };
  }

  // Check if the visitor details are consistent
  if (!isConsistent({ visitorId, firstName, lastName, monthlyIncome })) {
    recordLoanApplication(loanData, "rejected");
    console.error("Visitor details are not consistent.");
    return { success: false, error: "Loan application denied." };
  }

  // Check if the visitor has made too many applications
  const applicationCount = getApplicationCount(visitorId);
  if (applicationCount >= 3) {
    recordLoanApplication(loanData, "rejected");
    console.error("Too many loan applications.");
    return { success: false, error: "Loan application denied." };
  }

  // ...
}
```

This gives you a system to detect and block loan application fraud. You can extend it by configuring what details are allowed to change, tailoring outcomes based your business rules, checking only recent submissions, and more.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error checking, and data handling that align with your
  production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full protected loan application flow using the loan application page.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Reset the database by clicking "Reset demo DB" at the bottom of the loan application page.
3. Keep the default values in the form and click **Request loan**. The application should be approved.
4. Change some personal details, like the name, and submit again. The second application will be rejected because the same visitor has already applied with different personal details.
5. Refresh the page and try submitting a few more applications using the default details. After several attempts, new submissions will be blocked.
6. Open the page in incognito and try to submit a new loan application, your visitor ID will remain the same and the application is still blocked.
7. Bonus: Test the flow using a headless browser or automation tool to see bot detection in action. A sample script is available in `test-bot.js`. While your app is running, run the script with `node test-bot.js` in your terminal and observe that the automated applications are denied.

## Next steps

You now have a working loan application flow secured with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your lending policies, or add additional checks for suspicious or high-risk applicants.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Fingerprint MCP server
Source: https://docs.fingerprint.com/docs/mcp-server

Connect AI assistants and agents to Fingerprint device intelligence

The Fingerprint MCP server connects AI assistants and agents to Fingerprint's device intelligence platform. Once connected, your AI tools can query identification events, detect anomalies, investigate fraud patterns, and manage your Fingerprint workspace through natural language.

The server is available in two forms:

* **Managed service**: Hosted by Fingerprint. No setup or maintenance required.
* **Open source**: Self-host anywhere for full control over deployment and configuration.

This guide covers the managed service. For self-hosting instructions, see the [GitHub repository](https://github.com/fingerprintjs/fingerprint-mcp-server).

## Prerequisites

To use the Fingerprint MCP server, you need an active Fingerprint account and permission to create API keys in your workspace. No additional setup is required before connecting. API keys and workspace access are configured automatically during the OAuth connection flow.

## Connection Details

### Server URL

```
https://mcp.fpjs.io/mcp
```

In Claude, you can connect from the connectors directory without entering this URL. It is still required for Claude Code, Cursor, VS Code, and other MCP clients.

## Authentication

The Fingerprint MCP server uses OAuth. When you connect your AI client, you will be redirected to the Fingerprint dashboard to authorize access and select the workspace to connect to. If you have only one workspace, the selection step is skipped automatically.

If your AI client does not support OAuth, you can authenticate by passing your API key directly in the client's configuration. Go to the [Fingerprint dashboard](https://dashboard.fingerprint.com/mcp) for configuration options.

## Installation

<Accordion title="Claude (Claude.ai / Claude Desktop)">
  Fingerprint is listed in the Anthropic connectors directory, so you do not need to enter the server URL. See the [Claude Connector documentation](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities) for general setup instructions.

  <Steps>
    <Step title="Open Connectors">
      Go to **Settings** > **Connectors** and click **Browse**.
    </Step>

    <Step title="Find Fingerprint">
      Search for `Fingerprint`, then click **Connect**.
    </Step>

    <Step title="Authorize">
      Complete the OAuth authorization in your browser when prompted, then select the workspace to connect.
    </Step>
  </Steps>

  **Adding Fingerprint as a custom connector**

  If the directory listing is not available to you, add the server manually instead.

  <Steps>
    <Step title="Open Connectors">
      Go to **Settings** > **Connectors** and add a custom connector.
    </Step>

    <Step title="Add the server">
      Set **Name** to `Fingerprint` and **URL** to `https://mcp.fpjs.io/mcp`, then click **Add**.
    </Step>

    <Step title="Connect">
      Find Fingerprint in the **Not connected** list and click **Connect**.
    </Step>

    <Step title="Authorize">
      Complete the OAuth authorization in your browser when prompted.
    </Step>
  </Steps>

  <Warning>
    Name the connector `Fingerprint`. Names containing dots, apostrophes, or accented characters can prevent Claude from finding the server's tools, while the connector still shows as connected.
  </Warning>
</Accordion>

<Accordion title="Claude Code">
  See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp#installing-mcp-servers) for general setup instructions.

  <Steps>
    <Step title="Add the server">
      Run the following command to add the Fingerprint MCP server:

      ```bash theme={"theme":"github-dark-dimmed"}
      claude mcp add --transport http fingerprint https://mcp.fpjs.io/mcp
      ```
    </Step>

    <Step title="Open the MCP menu">
      Start Claude Code and open the MCP menu:

      ```bash theme={"theme":"github-dark-dimmed"}
      claude
      /mcp
      ```
    </Step>

    <Step title="Authorize">
      Select Fingerprint and complete the OAuth authorization in your browser when prompted.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Cursor">
  See the [Cursor MCP documentation](https://cursor.com/docs/mcp#installing-mcp-servers) for general setup instructions.

  <Steps>
    <Step title="Open Cursor Settings">
      Go to **Cursor** > **Settings…** > **Cursor Settings**.
    </Step>

    <Step title="Add a custom MCP server">
      Navigate to **Tools & MCP** and click **Add Custom MCP**. Add this configuration to your `mcp.json`:

      ```json theme={"theme":"github-dark-dimmed"}
      {
        "mcpServers": {
          "Fingerprint": {
            "url": "https://mcp.fpjs.io/mcp"
          }
        }
      }
      ```
    </Step>

    <Step title="Connect">
      Return to **Tools & MCP** and click **Connect** to authenticate with Fingerprint in your browser.
    </Step>
  </Steps>
</Accordion>

<Accordion title="VS Code (GitHub Copilot)">
  See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for general setup instructions.

  **Quick setup:** Open the Command Palette (`Ctrl+Shift+P` / `⇧⌘P`), run **MCP: Add Server**, and follow the guided flow for remote servers.

  **Manual setup:**

  <Steps>
    <Step title="Open your MCP config">
      Create or open `.vscode/mcp.json` in your project (to share with your team), or open the Command Palette and run **MCP: Open User Configuration** to configure across all workspaces.
    </Step>

    <Step title="Configure the server">
      Add the following to your `mcp.json`:

      ```json theme={"theme":"github-dark-dimmed"}
      {
        "servers": {
          "Fingerprint": {
            "type": "http",
            "url": "https://mcp.fpjs.io/mcp"
          }
        }
      }
      ```
    </Step>

    <Step title="Connect">
      Save the file. Click **Start** above the Fingerprint server entry, then complete the OAuth authorization in your browser.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Other MCP Clients">
  Any MCP-compatible client can connect to the Fingerprint MCP server.

  <Steps>
    <Step title="Add the server">
      Follow your client's documentation for adding an MCP server.
    </Step>

    <Step title="Configure the URL">
      Set the server URL to `https://mcp.fpjs.io/mcp`.
    </Step>

    <Step title="Authorize">
      Authenticate with OAuth in your browser when prompted.
    </Step>
  </Steps>
</Accordion>

## Available Tools

Tools are divided into two groups: event tools for querying identification data, and management tools for administering your Fingerprint workspace.

* **Event tools** let you retrieve and search identification events, including Smart Signal data like bot detection, VPN, proxy, incognito mode, and more.
* **Management tools** let you create, update, and delete workspace environments and API keys.

For a full list of tools, see the tool reference in the [GitHub repository](https://github.com/fingerprintjs/fingerprint-mcp-server).

## Example Queries and Prompts

Once connected, you can ask your AI assistant questions in plain language. Some examples:

* Fetch the last 50 events for visitor ID `Abck1234CUFmcnjLwIs4A9` and summarize their activity.
* Find all events linked to order ID `3936532456` and tell me if anything looks suspicious.
* Show me recent events where a bot was detected, filtered to the last 6 hours.
* List all environments in my workspace and create a new one called "staging".

The server also includes an `onboarding` prompt, a guided walkthrough for integrating Fingerprint into a new project that covers JavaScript agent installation and verification steps. Trigger it by asking your AI assistant to walk you through Fingerprint setup.

## Security Considerations

### **Prompt injection**

Fields like `linkedId` and `tags` are customer-controlled values attached to identification events. If a malicious actor controls what gets stored in these fields, they could attempt to embed instructions that manipulate your AI assistant. Most AI clients show you each tool call before it executes, so keep manual approval enabled and review them before confirming.

### **Sensitive operations**

Management tools can create, edit, and delete API keys and environments. Avoid connecting the server in shared or untrusted AI environments. Before approving any destructive changes, particularly in production, take time to carefully review what the agent is proposing.

## Troubleshooting

### Authentication failures

* Ensure you completed the OAuth flow and selected the correct Fingerprint workspace.
* Try disconnecting and reconnecting the MCP server in your client settings.
* If workspace authorization fails, your account may have reached the maximum number of allowed API keys (typically 5). Remove an unused key from the [Fingerprint Dashboard](https://dashboard.fingerprint.com/api-keys) and try again.

### Tools not appearing

* Restart your MCP client after adding the server configuration.
* In Claude, start a new conversation. Claude caches the tool list for the lifetime of a conversation, so a conversation started before a tool was added will not show that tool. Disconnecting and reconnecting the connector does not refresh a conversation that is already open.
* If you added Fingerprint as a custom connector and no tools appear at all, check the connector name. Names containing dots, apostrophes, or accented characters can prevent Claude from finding the server's tools. Rename it to `Fingerprint`, or connect from the connectors directory instead.

### Rate limit errors

* Reduce the number of concurrent or rapid sequential tool calls.
* Use specific filters (`visitor_id`, `linked_id`, time ranges) to reduce the number of API requests needed to answer a question.


# Understanding privacy manifest files
Source: https://docs.fingerprint.com/docs/mobile-devices-understanding-privacy-manifest-files



In [WWDC 2023](https://developer.apple.com/videos/play/wwdc2023/10060/), Apple announced that starting [Spring 2024](https://developer.apple.com/news/?id=3d8a9yyh), it will require its developers to declare the reasons for using certain APIs (aka Required Reason APIs) that could be misused to collect data about users' devices within privacy manifest files.

[Privacy manifest files](https://developer.apple.com/documentation/bundleresources/privacy-manifest-files) allow developers to describe their privacy practices:

* [Data](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests) that their app or SDK collects and its purpose.
* [Required Reason APIs](https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api) that their app or SDK uses and the reason for using them.

<Check>
  Important note: the [privacy manifest
  file](/docs/mobile-devices-understanding-privacy-manifest-files#privacy-manifest-file-for-fingerprint-identification-sdk)
  and the [privacy nutrition
  labels](/docs/mobile-devices-understanding-privacy-manifest-files#app-store-nutrition-labels-guidance-for-your-app)
  are two separate things - the privacy manifest is a 'plist' file bundled with the app/SDK, while
  the Nutrition Labels are what developers fill out in App Store Connect before submission. The
  privacy manifest report generated by Xcode can help populate the labels more accurately, but
  developers still need to manually apply the correct labels in the submission interface.
</Check>

In this article, we will walk you through the privacy manifest file for Fingerprint [iOS SDK](/docs/ios) and share guidance on App Store Nutrition Labels to help you complete them in App Store Connect before submission.

## Privacy Manifest File for Fingerprint Identification SDK

Starting with v2.3.2, the Fingerprint Identification SDK for iOS includes a privacy manifest file. Apple requires that every privacy manifest file contains the following keys.

### NSPrivacyTracking

Fingerprint Identification SDK does not use the collected data for tracking, and hence, the NSPrivacyTracking key is set to `false`.

```xml XML wrap theme={"theme":"github-dark-dimmed"}
{/*  Privacy manifest file for Fingerprint Identification SDK for iOS  */}
<key>NSPrivacyTracking</key>
<false/>
```

### NSPrivacyTrackingDomains

Fingerprint Identification SDK for iOS does not connect with any Internet domains that engage in tracking users. The NSPrivacyTrackingDomains key is set to an empty array of domains.

```xml XML wrap theme={"theme":"github-dark-dimmed"}
{/*  Privacy manifest file for Fingerprint Identification SDK for iOS  */}
<key>NSPrivacyTrackingDomains</key>
<array/>
```

### NSPrivacyCollectedDataTypes

Apple has identified [a list of data types](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests#4250555) that, when collected, may help to identify/track the device. These are the data types our iOS SDK collects from the device:

* `NSPrivacyCollectedDataTypeDeviceID` - device ID; such as the device’s advertising identifier, or other device-level ID.
* `NSPrivacyCollectedDataTypePreciseLocation` - precise location; information that describes the location of a user or device with the same or greater resolution as a latitude and longitude with three or more decimal places (started collecting since [iOS SDK 2.10.0](/docs/changelog-ios-sdk#v2-10-0)).
* `NSPrivacyCollectedDataTypeCoarseLocation` - coarse location; information that describes the location of a user or device with lower resolution than a latitude and longitude with three or more decimal places, such as Approximate Location Services (started collecting since [iOS SDK v2.10.0](/docs/changelog-ios-sdk#v2-10-0)).

Apple also requires [describing data use](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests#4250556) in privacy manifests as part of this dictionary item. This data is represented in the `NSPrivacyCollectedDataTypes` key in our privacy manifest file:

```xml XML wrap theme={"theme":"github-dark-dimmed"}
{/*  Privacy manifest file for Fingerprint Identification SDK for iOS  */}
<key>NSPrivacyCollectedDataTypes</key>
<array>
  <dict>
    {/*  The value provided by Apple for 'Device ID' data type  */}
    <key>NSPrivacyCollectedDataType</key>
    <string>NSPrivacyCollectedDataTypeDeviceID</string>

    {/*  Fingerprint Identification SDK does not link the 'Device ID' with user's identity  */}
    <key>NSPrivacyCollectedDataTypeLinked</key>
    <false/>

    {/*  Fingerprint Identification SDK does not use 'Device ID' for tracking  */}
    <key>NSPrivacyCollectedDataTypeTracking</key>
    <false/>

    {/*  Fingerprint Identification SDK uses 'Device ID' for App Functionality
         (prevent fraud and implement security measures)  */}
    <key>NSPrivacyCollectedDataTypePurposes</key>
    <array>
      <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
    </array>

  <dict>
    {/*  The value provided by Apple for 'Precise Location' data type  */}
    <key>NSPrivacyCollectedDataType</key>
    <string>NSPrivacyCollectedDataTypePreciseLocation</string>

    {/*  Fingerprint Identification SDK does not link the 'Precise Location' with user's identity  */}
    <key>NSPrivacyCollectedDataTypeLinked</key>
    <false/>

    {/*  Fingerprint Identification SDK does not use 'Precise Location' for tracking  */}
    <key>NSPrivacyCollectedDataTypeTracking</key>
    <false/>

    {/*  Fingerprint Identification SDK uses 'Precise Location' for App Functionality
         (prevent fraud and implement security measures)  */}
    <key>NSPrivacyCollectedDataTypePurposes</key>
    <array>
      <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
    </array>
  </dict>

  <dict>
    {/*  The value provided by Apple for 'Coarse Location' data type  */}
    <key>NSPrivacyCollectedDataType</key>
    <string>NSPrivacyCollectedDataTypeCoarseLocation</string>

    {/*  Fingerprint Identification SDK does not link the 'Coarse Location' with user's identity  */}
    <key>NSPrivacyCollectedDataTypeLinked</key>
    <false/>

    {/*  Fingerprint Identification SDK does not use 'Coarse Location' for tracking  */}
    <key>NSPrivacyCollectedDataTypeTracking</key>
    <false/>

    {/*  Fingerprint Identification SDK uses 'Coarse Location' for App Functionality
         (prevent fraud and implement security measures)  */}
    <key>NSPrivacyCollectedDataTypePurposes</key>
    <array>
      <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
    </array>
  </dict>
</array>

```

### NSPrivacyAccessedAPITypes

Fingerprint Identification SDK for iOS uses the following Required Reason APIs which have to be included in the privacy manifest file:

1. [File timestamp APIs](https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api#4278394)
2. [System boot time APIs](https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api#4278394)

```xml XML wrap theme={"theme":"github-dark-dimmed"}
{/*  Privacy manifest file for Fingerprint Identification SDK for iOS  */}
<key>NSPrivacyAccessedAPITypes</key>
<array>
  <dict>
    {/*  The value provided by Apple for 'System boot time APIs'  */}
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategorySystemBootTime</string>

    {/*  Fingerprint Identification SDK uses 'System boot time APIs' to measure the amount of
          time that has elapsed between events that occurred within the SDK  */}
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
      <string>35F9.1</string>
    </array>
  </dict>
  <dict>
    {/*  The value provided by Apple for 'File timestamp APIs'  */}
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>

    {/*  Fingerprint Identification SDK uses 'File timestamp APIs' to manage persistent cache
         data  */}
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
      <string>C617.1</string>
    </array>
  </dict>
</array>
```

## Privacy Manifest File for your App

Below, you will find answers to some of the most frequently asked questions with respect to creating privacy manifest files for your iOS apps:

**My app uses Fingerprint Identification SDK, but the app itself does not collect any** [**sensitive data**](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests#4250555)**. It also does not use any of the Required Reason APIs. Should I still provide a privacy manifest file for my app?**

* No. According to [Apple documentation](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests), your app’s privacy manifest file doesn’t need to cover data collected by third-party SDKs that your app links to.

**My app uses Fingerprint Identification SDK. The app also collects the same data as the SDK for the same purpose specified in the SDK's privacy manifest file. Should I still provide a privacy manifest file for my app?**

* Yes. Apple will aggregate the privacy manifest files provided for your app and all the third-party SDKs your app links to. See [Create your app's privacy report](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests#4239187) for more information.

**My app uses Fingerprint Identification SDK. What kind of assistance can Fingerprint provide towards submitting my app for review?**

* This page is a good starting point for creating the privacy manifest file for your app. For a complete privacy manifest example, you can also refer to the [privacy manifest file of our demo app](https://github.com/fingerprintjs/fingerprint-device-intelligence-ios-demo/blob/main/FingerprintDemo/PrivacyInfo.xcprivacy).
* We can review the privacy manifest file for your app to ensure that the use of Fingerprint Identification SDK is represented correctly.
* During the app submission process, we will help you answer any questions Apple raises about the data collected/processed by Fingerprint Identification SDK.

## App Store Nutrition Labels Guidance for Your App

If your app includes Fingerprint iOS SDK, then you can use the following as a reference to fill out the Nutrition Labels in App Store Connect:

### Data Collection and Security

| Question                                                       | Answer |
| -------------------------------------------------------------- | ------ |
| Does your app collect or share any of the required data types? | Yes    |
| Is all collected data encrypted in transit?                    | Yes    |

### Data types

| Apple Data Category | Fingerprint iOS SDK Relevance                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Device ID           | Yes - the SDK collects device-level identifiers                                                                          |
| Precise Location    | Yes - collected since [iOS SDK v2.10.0+](/docs/changelog-ios-sdk#september-2025) (requires user consent for permissions) |
| Coarse Location     | Yes - collected since [iOS SDK v2.10.0+](/docs/changelog-ios-sdk#september-2025) (requires user consent for permissions) |
| Performance Data    | Yes - collected since [iOS SDK v2.15.0+](/docs/changelog-ios-sdk#march-2026)                                             |

### Data Usage and Handling

| Question                       | Device ID                                      | Precise Location                               | Coarse Location                                |
| ------------------------------ | ---------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
| Collected, shared, or both?    | Collected                                      | Collected                                      | Collected                                      |
| Linked to the user's identity? | No                                             | No                                             | No                                             |
| Used for tracking?             | No                                             | No                                             | No                                             |
| Primary purpose?               | App Functionality (Fraud Prevention, Security) | App Functionality (Fraud Prevention, Security) | App Functionality (Fraud Prevention, Security) |

Note: Apple clarifies that even if data is collected solely for your app functionality, it still must be declared - the purpose just needs to be accurately indicated as "App Functionality" rather than advertising or analytics, see for reference [App privacy details on the App Store](https://developer.apple.com/app-store/app-privacy-details/).

### What's Different from the Privacy Manifest

|                       | Privacy Manifest                                                 | App Privacy Nutrition Labels      |
| --------------------- | ---------------------------------------------------------------- | --------------------------------- |
| **Where?**            | Bundled inside the SDK/app binary                                | Filled out in App Store Connect   |
| **Who fills it out?** | SDK vendor (Fingerprint provides it in starting iOS SDK v2.3.2+) | App developer (you)               |
| **When required?**    | At build/distribution time                                       | At app submission time            |
| **Covers SDK data?**  | Yes, automatically aggregated by Xcode                           | Yes, but must be manually applied |

Below, you will find answers to some of the most frequently asked questions with respect to filling out Nutrition Labels for your iOS apps:

**Do I need to declare Fingerprint's data in my app's Privacy Nutrition Label even if the SDK has its own privacy manifest?**

* Yes. While the Fingerprint SDK's privacy manifest will be combined with your app's manifest by Xcode into a single report, you are still responsible for applying the correct Nutrition Labels in App Store Connect. The manifest report helps you fill this out accurately, but it does not automatically populate the labels.

**Is using Fingerprint considered 'tracking' under Apple's definition?**

* No. Apple's guidelines specify that sharing data with a data broker that uses it solely for fraud detection or prevention or security purposes is not considered tracking. Since Fingerprint is used for fraud prevention and security, neither [NSPrivacyTracking](https://developer.apple.com/documentation/bundleresources/app-privacy-configuration/nsprivacytracking) nor the App Tracking Transparency (ATT) prompt are required.

**Who is responsible for keeping the labels accurate?**

* Developers are responsible for all code included in their apps, including third-party SDKs. If you are unsure about the data collection practices of the Fingerprint SDK, this page and Fingerprint's support team are the right resources.


# Fingerprint for mobile devices
Source: https://docs.fingerprint.com/docs/mobile-identification



Fingerprint's device intelligence platform can accurately identify every mobile device that interacts with your app. It can also provide actionable [Smart Signals](/docs/smart-signals-reference#smart-signals-for-mobile-devices) that will help you identify risky mobile transactions before they happen.

You can integrate Fingerprint's device intelligence platform with your mobile app by using any of the following SDKs:

* [Android SDK](/docs/android-sdk)
* [iOS SDK](/docs/ios-sdk)
* [Flutter SDK](/docs/flutter)
* [React Native SDK](/docs/fingerprintjs-pro-react-native)

This page provides an overview of the platform for mobile devices and compares it with that for browsers, where applicable.

### Identification

* For websites, the visitor ID provided by the JavaScript agent identifies the **browser** interacting with your website. Every browser (e.g. Safari, Chrome, Firefox, etc) on the device gets a unique visitor ID even if they are on the same device.
* For mobile apps, the visitor ID provided by mobile SDKs identifies the **mobile device** interacting with your mobile app.

The visitor ID that the mobile SDKs generate for a mobile app is different from that generated by the Javascript agent for a browser on the same device.

Learn more about how Fingerprint identifies mobile devices:

* For Android devices, see [Android:Device Identifier](/docs/native-android-integration#device-identifier)
* iOS devices, see [iOS:Device Identifier](/docs/ios#device-identifier)

### Identification accuracy

In general, for mobile devices, the identification accuracy is **higher than for browsers**. This is because the native mobile SDKs can access several operating system properties that remain stable over a long time. These properties are typically not available to a Javascript agent operating from within a browser.

<Note>
  Unlike the [JavaScript agent for browsers](https://docs.fingerprint.com/docs/identify-visitors#caching-the-visitor-id), the mobile SDKs do not cache identification responses on the device.

  This is intentional. Many of the mobile Smart Signals used in fraud prevention (for example, MITM detection or active call detection) are only meaningful if they reflect the device's current state at the time of the request. Caching a response on the SDK side would mean an app could act on a signal that no longer reflects that state, which reduces its value for time-sensitive risk decisions.

  If your mobile app needs to reduce the number of identification calls it makes, we recommend implementing caching at the application layer, where you control the cache duration and can decide which signals are safe to reuse for your specific use case and for how long. A common pattern is to cache the visitor ID for the duration of a user session and request a fresh identification on new sessions or before high-risk actions (e.g. login, checkout, payment).
</Note>

### Smart Signals for mobile devices

Smart Signals are actionable device intelligence signals that help you to make informed decisions about the device and thus prevent fraud. For a quick overview of the different Smart Signals available for each platform, see

* [Android Smart Signals](/docs/native-android-integration#android-smart-signals)
* [iOS Smart Signals](/docs/ios#ios-smart-signals)
* [Smart Signals common for browsers and mobile devices](/docs/smart-signals-reference#smart-signals-common-for-browsers-and-mobile-devices)

See [Smart Signals setup and usage](/docs/smart-signals-introduction#setup-and-usage) for information on how to receive these Smart Signals.

### Evading ad blockers

If your users' mobile devices have ad-blocking mobile apps, they can block requests that your app makes to the Fingerprint domains. You can evade these ad-blocking mobile apps by proxying requests through your own domain. See [Evading ad blockers with proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers) for more information.

### Privacy and data safety

When you publish your app to the App Store or Google Play, you must disclose information about the data collected and its usage. This requirement applies to your app as well as to the third-party SDKs the app uses.

For iOS apps, Apple requires you to provide a privacy manifest file to declare the data that your app/SDK collects and the reasons for collecting the same. To learn more, see [Privacy Manifest File Requirements for App Store](/docs/ios#privacy-manifest-file-requirements-for-app-store).

For Android apps, Google requires that the app's privacy and security practices be made available to all its users. To learn more, see [Data Safety Requirements for Google Play](/docs/native-android-integration#data-safety-requirements-for-google-play).

## Additional resources

* Want to see the iOS SDK in a demo app? Download the iOS Demo app from the [App Store](https://apps.apple.com/us/app/fingerprint-pro/id1644105278).
* Want to see the Android SDK in a demo app? Download the Android Demo app from [Google Play](https://play.google.com/store/apps/details?id=com.fingerprintjs.android.fpjs_pro_demo).


# Overview
Source: https://docs.fingerprint.com/docs/mobile-sdks



In this section, you will find Getting Started Guides for integrating a Fingerprint  SDK with your

* [Android apps](/docs/android-sdk)
* [iOS apps](/docs/ios-sdk)
* [React Native apps](/docs/fingerprintjs-pro-react-native)
* [Flutter apps](/docs/flutter)


# Overview
Source: https://docs.fingerprint.com/docs/native-android-integration

Fingerprint's device intelligence platform for Android devices.

Fingerprint's device intelligence platform is also available for Android devices. Our device intelligence platform for Android helps you to accurately identify the devices that interact with your mobile app and provides high-quality Smart Signals that will help you identify risky transactions before they happen.

To make integrations with mobile apps easier, we offer SDKs for apps built natively using Android as well as for apps built using multi-platform frameworks (e.g. React Native).

A Fingerprint account is required to be able to use the Fingerprint Identification SDK in your mobile apps. If you do not have an account yet, please [sign up](https://dashboard.fingerprintjs.com/signup) for one.

<Check>
  **Download our** [**demo
  app**](https://play.google.com/store/apps/details?id=com.fingerprintjs.android.fpjs_pro_demo) from
  Google Play to see Fingerprint in action!
</Check>

## Device Identifier

When the Fingerprint Identification SDK is integrated into your mobile app, it will collect several attributes from the device. With the help of these attributes and additional algorithms, Fingerprint is able to provide a unique device identifier (i.e. `visitorId`) for every device on which your app is installed.

<Info>
  **Did you know?**

  The device identifier generated by the Android SDK (embedded within your mobile app) will be different from the visitor ID generated by the Javascript agent (embedded within your website).
</Info>

When compared with browsers, the identification accuracy is better for mobile devices because we identify mobile devices using signals that have higher longevity than those used for identifying browsers. But there are scenarios where a `visitorId` does not persist.

For your reference, we have listed various scenarios where a `visitorId` will remain the same before and after and where a new `visitorId` will be created.

| Scenario                                                                                                                                                  | Will I receive the same `visitorId` before and after?                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The app or device is restarted                                                                                                                            | **Yes.** You will receive the same `visitorId` even after the app or device is restarted.                                                                |
| The app data/cache is cleared                                                                                                                             | **Yes.** You will receive the same `visitorId` even after the app's data/cache is cleared.                                                               |
| The app is uninstalled and re-installed again                                                                                                             | **Yes.** You will receive the same `visitorId` even after the app is removed and installed again.                                                        |
| The device is factory reset                                                                                                                               | **Yes, in most of the devices.** After a factory reset, except for a few Android models, the `visitorId` remains the same.                               |
| The app is installed on [one or more profiles](https://source.android.com/docs/devices/admin/multi-user), that belong to a single user on the same device | **Yes.** You will receive the same `visitorId` even when the app is installed on multiple user profiles that belong to a single user on the same device. |
| The app is installed for [one or more user accounts, all belonging to the same device](https://source.android.com/docs/devices/admin/multi-user)          | **Yes.** You will receive the same `visitorId` even when the app is installed on multiple user accounts that belong to the same device.                  |
| The app is cloned to a different app                                                                                                                      | **Yes**. The `visitorId` does not change even when the app is cloned numerous times or when the cloned app is installed on a different profile.          |

## Android Smart Signals

Smart Signals are actionable device intelligence signals that help you to make informed decisions about the device and thus prevent fraud. These signals could be used as input to your machine learning models behind your fraud detection or risk mitigation engines. For example, when you know that a request is originating from a *rooted* device or from a recently *factory reset* device, you will be able to take additional precautionary security steps (e.g. multi-factor authentication).

For Android, the following Smart Signals are available:

* [Android Emulator Detection](/docs/smart-signals-reference#android-emulator-detection)
* [Cloned App Detection](/docs/smart-signals-reference#cloned-app-detection)
* [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection)
* [Frida Detection](/docs/smart-signals-reference#frida-detection)
* [Geolocation Spoofing Detection](/docs/smart-signals-reference#geolocation-spoofing-detection)
* [IP Geolocation Detection](/docs/smart-signals-reference#ip-geolocation)
* [IP Blocklist Detection](/docs/smart-signals-reference#ip-blocklist-matching)
* [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection)
* [Rooted Device Detection](/docs/smart-signals-reference#rooted-device-detection)
* [Tampered Request Detection](/docs/smart-signals-reference#tampered-request-detection-for-mobile-apps)
* [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices)
* [Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection-for-mobile-devices)
* [Smart Signals common for browsers and mobile devices](/docs/smart-signals-reference#smart-signals-common-for-browsers-and-mobile-devices)

These Smart Signals are available as part of our [Pro Plus and Enterprise plans](https://fingerprint.com/pricing/). If you are interested in one or more of these signals, then please [contact our support team](https://fingerprint.com/support/) to enable them for you. Signing up for an Enterprise plan does not automatically enable these signals.

## Fingerprint Identification SDK for Android

<Info>
  ### Current Version: 2.17.1

  For release notes and older versions, visit our [Changelog for Android SDK](https://docs.fingerprint.com/docs/changelog-android-sdk) page.
</Info>

### Supported Versions

The minimum version that the Fingerprint Identification SDK for Android supports is [Marshmallow](https://developer.android.com/about/versions/marshmallow), [API Level 23](https://developer.android.com/tools/releases/platforms#6.0) starting [Android SDK 2.11.0+](/docs/changelog-android-sdk#v2-11-0). Per Google, this will allow your app to be compatible with a wide variety of active Android devices.

<img alt="" />

### Required Permissions

Fingerprint Identification SDK for Android requires the following **normal** permissions, without which the SDK cannot function properly. These permissions are required to identify the device and provide additional intelligence.

* [`android.permission.INTERNET`](https://developer.android.com/reference/android/Manifest.permission#INTERNET)
* `com.google.android.providers.gsf.permission.READ_GSERVICES`

Unlike the runtime permissions (*aka* dangerous permissions), these permissions do not require consent from the user. See [Permissions on Android](https://developer.android.com/guide/topics/permissions/overview) to learn more about the different types of permissions.

### Getting Started Guides

Our Getting Started guides are aimed at helping you to easily integrate our SDK with your apps.

* For native Android apps, see [Mobile SDKs > Android](/docs/android-sdk) and our [Android quickstart](/docs/android-quickstart).
* For apps built using Flutter, see our [Flutter SDK on GitHub](https://github.com/fingerprintjs/fingerprintjs-pro-flutter) and our [Flutter quickstart](/docs/flutter-quickstart).
* For apps built using React Native, see our [React Native SDK on GitHub](https://github.com/fingerprintjs/react) and our [React Native quickstart](/docs/react-native-quickstart).

## Data Safety Requirements for Google Play

For every app that is uploaded to the Google Play Store, Google requires that the app's privacy and security practices are made available to all its users. For this reason, when an app (or a new version) is uploaded to the Play Store, Google requires app developers to fill out a data safety form. See [Provide information for Google Play's Data safety section](https://support.google.com/googleplay/android-developer/answer/10787469?hl=en) for more information.

If your app includes our Android SDK, then you can use the following as a reference to fill out the data safety questionnaire:

### Section: Data collection and security

1. *Does your app collect or share any of the required user data types?* **Yes**
2. *Is all of the user data collected by your app encrypted in transit?* **Yes**

### Section: Data types

1. *Select all of the user data types collected or shared by your app*
   1. **App info and performance -> Diagnostics**
   2. **Device or other IDs.**
   3. **Location -> Precise and Approximate Location** (collected since [Android SDK v2.10.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#september-2025); requires user consent for permissions)

### Section: Data usage and handling

| Question                                                                          | App info and performance > Diagnostics                                  | Device or other IDs                                                     | Precise and Approximate Location                              |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
| *Is this data collected, shared, or both?*                                        | Collected                                                               | Collected                                                               | Collected                                                     |
| *Is this data processed ephemerally?*                                             | No, this collected data is not processed ephemerally                    | No, this collected data is not processed ephemerally                    | No, this collected data is not processed ephemerally          |
| *Is this data required for your app, or can users choose whether it's collected?* | Data collection is required (users can't turn off this data collection) | Data collection is required (users can't turn off this data collection) | Location data collection is optional (your app controls this) |
| *Why is this user data collected?*                                                | Analytics                                                               | Fraud Prevention, Security, and Compliance                              | Fraud Prevention, Security, and Compliance                    |

Note: The Data sharing section in the [Google Play Data Safety](https://support.google.com/googleplay/android-developer/answer/10787469#zippy=%2Cdata-sharing) form can be left empty. Per Google's policy, data transferred to a service provider that processes it on the developer's behalf - in compliance with the developer's instructions, contractual terms, and privacy policies - does not need to be declared as "shared." As Fingerprint acts as a data processor under GDPR (and a service provider under Google's definition), data sent to Fingerprint does not constitute "data sharing" for the purposes of this form.

### Google Play Compatibility Notes

The Fingerprint Android SDK may not be compatible with **[Google Play's Automatic Integrity Protection](https://developer.android.com/google/play/integrity/overview)**. If your app uses Google Play's integrity protection, we recommend reviewing compatibility before enabling this feature. If both are enabled, this may result in false positives or unexpected app behavior.

## FingerprintJS-Android: Open-source identification for Android

We also provide a lightweight, open-source library called [fingerprintjs-android](https://github.com/fingerprintjs/fingerprintjs-android) which is available to use for free by everyone. Our commercial SDK, Fingerprint Identification for Android, is based on our well-maintained, free, open-source library.

Compared to the open-source library, our commercial SDK collects many more attributes from the device. It also uses advanced fingerprinting and matching algorithms to create a unique device identifier.

For your better understanding, here is a complete set of differences between our open-source library (`fingerprintjs-android`) and our commercial SDK (`fingerprint-android-pro`).

|                                                                              | FingerprintJS-Android(fingerprintjs-android)                                         | Fingerprint Identification for Android(fingerprint-android-pro)                             |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Core Features                                                                |                                                                                      |                                                                                             |
| **Attributes collected from the device**                                     | Basic (*e.g. Android ID, GSF ID, model*)                                             | Advanced. Lot more attributes, in addition to those collected by the open-source library.   |
| **ID Type**                                                                  | Device ID or a *fingerprint* that is a hash of the collected attributes              | A single *visitorId* that is computed using advanced fingerprinting and matching algorithms |
| **ID Origin**                                                                | Attributes are processed only within the library. External servers are not involved. | Attributes are processed on external servers                                                |
| **ID Lifetime**                                                              | Only up to a few weeks                                                               | Lasts several months and sometimes even years                                               |
| **ID Collisions**                                                            | Common                                                                               | Very rare                                                                                   |
| Support for multi-platform frameworks                                        |                                                                                      |                                                                                             |
| **Flutter**                                                                  | -                                                                                    | **✓**                                                                                       |
| **React Native**                                                             | -                                                                                    | **✓**                                                                                       |
| Advanced Features                                                            |                                                                                      |                                                                                             |
| **Server API and Webhooks**\*(Build flexible workflows)\*                    | -                                                                                    | **✓**                                                                                       |
| **Mobile Smart Signals**\*(VPN Detection, Factory Reset, App Cloners, etc)\* | -                                                                                    | **✓**                                                                                       |
| **Geolocation**\*(Based on IP address)\*                                     | -                                                                                    | **✓**                                                                                       |
| Operations                                                                   |                                                                                      |                                                                                             |
| **Data security**                                                            | Depends on your infrastructure                                                       | Encrypted at rest                                                                           |
| **Storage**                                                                  | Depends on your infrastructure                                                       | Unlimited up to 1 year                                                                      |
| **Regions**                                                                  | Depends on your infrastructure                                                       | Global, EU and Asia data centers                                                            |
| **Compliance**                                                               | Depends on your infrastructure                                                       | Compliant\*\*\* with GDPR, US Privacy Laws (including CCPA), SOC 2 Type II, and ISO 27001   |
| **SLA**                                                                      | SLA is not provided                                                                  | 99.9% Uptime                                                                                |
| **Support**                                                                  | GitHub Issues/Questions. Response times varies.                                      | Dedicated support team that responds to chat, email, and calls within 1 business day        |
| How to get started?                                                          | [Get it on GitHub](https://github.com/fingerprintjs/fingerprintjs-android)           | [Sign up for a free 14-day trial](https://dashboard.fingerprintjs.com/signup/)              |

\*\*In comparison to fingerprints, VisitorIDs are more accurate and stable identifiers because they are deduplicated, are processed further on the server, and utilize fuzzy matching. On the other hand, fingerprint hashes become unstable across time intervals greater than 2 weeks because they rely on an exact match of all browser attributes.

\*\*\*The company, Fingerprint, in its role as data processor is compliant with GDPR, US Privacy Laws (including CCPA) and SOC 2 Type II. It is also ISO 27001 certified. As a data controller, it is still your responsibility to be compliant with GDPR and US Privacy Laws (including CCPA) and use the identification result for legitimate purposes.

***

[Understanding privacy manifest files](/docs/mobile-devices-understanding-privacy-manifest-files)


# New Account Fraud
Source: https://docs.fingerprint.com/docs/new-account-fraud-use-case-tutorial

Learn how to detect and prevent fraudulent account creation

## Overview

This tutorial walks through implementing Fingerprint to prevent new account fraud, where bad actors create multiple fake accounts to exploit sign-up bonuses, free trials, or other incentives.

You'll begin with a starter app that includes a mock sign-up page and a basic registration flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to detect and block multiple account creations from the same device. For simplicity, the sample will block new account sign-ups from devices that have already registered one account, but in practice, you might choose to add friction, require additional verification, or set higher thresholds instead.

By the end, you'll have a sample app that limits each visitor to one legitimate account and can be adapted to fit your own fraud prevention and business logic.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `new-account-fraud` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Sign-up page" />

    <Tree.File name="index.js - Front-end logic to handle sign-up" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="server.js - Serves static files and sign-up endpoint" />

    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="accounts.js - New account fraud logic" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit `http://localhost:3000` to view the mock sign-up page from the starter app. Create a few test accounts using different usernames and clicking **Sign up**. Then open the page in a different browser or incognito window and try creating another account from the same device. By default, the app allows unlimited account creations per device.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Sign up**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the signup payload. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including the verified visitor ID and risk signals such as browser tampering or bot activity.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Sign up** button already has an event handler for submitting the credentials. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the signup to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
signupBtn.addEventListener("click", async () => {
  // ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/signup", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
	    body: JSON.stringify({ username, password, eventId }),
    });
    const data = await res.json();

    // ...
  }
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your signup logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/signup` route there to also extract `eventId` from the request body and pass it into the `attemptSignup` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/signup", async (req, reply) => {
  const { username, password, eventId } = req.body || {};
  const result = await attemptSignup({ username, password, eventId });
  return reply.send(result);
});
```

2. The `server/accounts.js` file contains the logic for handling signups. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `attemptSignup` function to accept `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptSignup({ username, password, eventId }) {
  if (!username || !password || !eventId) {
    console.error("Missing one or more inputs.");
    return { success: false, error: "Sign up failed." };
  }

  const user = findAccountByUsername(username);
  if (user) {
    console.error("Account already exists");
    return { success: false, error: "Account already exists." };
  }

  const event = await fpServerApiClient.getEvent(eventId);

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection and Suspect Score Smart Signals, which are only
  available on paid plans.
</Note>

A simple but powerful way to prevent automated abuse is to block bot signups. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found.

1. Continuing in the `attemptSignup` function in `server/accounts.js`, check the bot signal returned in the `event` object:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptSignup({ username, password, eventId }) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";

  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, error: "Signup failed." };
  }

  // ...
}
```

You can also use Fingerprint's [Suspect Score](/docs/suspect-score) to flag high-risk signups. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload, helping to identify suspicious activity.

While it's not typical to block signups based solely on a high risk score, this example shows how you might incorporate it. In a real application, a better approach would be to flag the attempt for review or add additional friction during signup.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the signup if it exceeds a chosen threshold (for example, 20):

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptSignup({ username, password, eventId }) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";

  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, error: "Signup failed." };
  }

  const suspectScore = event.suspect_score || 0;

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, error: "Signup failed." };
  }

  // ...
}
```

## 6. Prevent multiple account sign-ups per device

Next, use the trusted visitor ID from the `event` object to enforce a one-account-per-device rule. If the same device (visitor ID) tries to create another account, reject the sign-up. In production, you may choose to allow a limited number of accounts per device, require additional verification, or flag the new account for review. *(This example simplifies account creation logic for demonstration purposes.)*

Note: The starter app includes a SQLite database with a table already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
accounts - Stores account details
	username TEXT PRIMARY KEY
	password TEXT NOT NULL
	visitorId TEXT
	createdAt INTEGER NOT NULL
```

1. Add a helper function to the bottom of the `server/accounts.js` file to check if the device has already been used to create an account:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
// Check if the device has already created an account
function findAccountByVisitorId(visitorId) {
  const row = db
    .prepare(`SELECT username FROM accounts WHERE visitorId = ? LIMIT 1`)
    .get(visitorId);
  return row;
}
```

2. Update `attemptSignup` to retrieve the `visitorId` and use it to enforce the one device per account rule and record successful signups:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptSignup({ username, password, eventId }) {
  // ...

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, error: "Signup failed." };
  }

  const visitorId = event.identification.visitor_id;
  const account = findAccountByVisitorId(visitorId);
  if (account) {
    console.error("Account already exists for this device.");
    return { success: false, error: "Signup failed." };
  }

  // ...
}
```

3. Update the SQL statement to store the `visitorId` along with the account details so it can be used later for device verification checks:

```javascript server/accounts.js theme={"theme":"github-dark-dimmed"}
export async function attemptSignup({ username, password, eventId }) {
  // ...

  const visitorId = event.identification.visitor_id;
  const account = findAccountByVisitorId(visitorId);
  if (account) {
    console.error("Account already exists for this device.");
    return { success: false, error: "Signup failed." };
  }

  db.prepare(
    `INSERT INTO accounts (username, password, visitorId, createdAt) VALUES (?, ?, ?, ?)`,
  ).run(username, password, visitorId, Date.now());

  return { success: true };
}
```

This gives you a basic system to detect and block new account fraud. You can extend it by allowing a limited number of accounts per device, adding verification steps for suspicious sign-ups, setting time-based limits, or flagging high-risk activity for review.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to use proper security practices, input validation, password handling, and account management
  logic that align with your production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full protected signup flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Reset the database by clicking on **Reset demo DB** at the bottom of the page.
3. Create a new account in your browser, you should see a success response. Then try to create another account and you'll see that the attempt fails.
4. Open an incognito/private window and try creating another account. The attempt will still be rejected because the device has already registered one account.
5. Bonus: Test the flow using a headless browser or automation tool to see bot detection in action. A sample script is available in `test-bot.js`. While your app is running, run the script with `node test-bot.js` in your terminal and observe that the automated signups are blocked.

## Next steps

You now have a working signup flow secured with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your business policies, or layer in additional checks for suspicious visitors.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Preventing account sharing](/docs/account-sharing-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Next.js Quickstart
Source: https://docs.fingerprint.com/docs/nextjs-quickstart

Get started using the Fingerprint React SDK with Next.js

## Overview

In this quickstart, you'll add Fingerprint to a new [Next.js](https://nextjs.org/) project and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend integration. You'll install the [Fingerprint React SDK](/docs/react) and initialize the JavaScript agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of [Next.js](https://nextjs.org/) and React

<Note>
  This quickstart only covers the **frontend setup**. You'll need a [backend
  server](/reference/server-sdks) to receive and process the device identification event to enable
  fraud detection. Check out one of our [backend quickstarts](/docs/server-quickstarts-overview)
  after completing this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the JavaScript agent.

## 2. Set up your project

To get started, scaffold a new Next.js app. If you already have a project you want to use, you can skip to the next section.

1. Create a new Next.js project:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npx create-next-app@latest fingerprint-nextjs-quickstart
cd fingerprint-nextjs-quickstart
```

2. When prompted, select the default options (TypeScript, ESLint, Tailwind CSS, App Router).

3. Open the `fingerprint-nextjs-quickstart` folder in your code editor. To run your project:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

4. In your browser, go to [http://localhost:3000](http://localhost:3000/), and you should see the Next.js welcome page.

## 3. Set up your account creation form

1. Before adding Fingerprint, create a new client component at `app/components/CreateAccountForm.tsx` with the following:

```tsx app/components/CreateAccountForm.tsx theme={"theme":"github-dark-dimmed"}
"use client";

import { useState } from "react";

interface CreateAccountFormProps {
  isLoading?: boolean;
  handleSubmit?: () => void;
}

export default function CreateAccountForm(props: CreateAccountFormProps) {
  const [username, setUsername] = useState("");
  const [password, setPassword] = useState("");
  return (
    <div className="wrapper">
      <h1>Create an account</h1>
      <div className="input-group">
        <label htmlFor="username">Username</label>
        <input
          id="username"
          value={username}
          onChange={(e) => setUsername(e.target.value)}
          type="text"
          placeholder="Username"
          required
        />
      </div>
      <div className="input-group">
        <label htmlFor="password">Password</label>
        <input
          id="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          type="password"
          placeholder="Password"
          required
        />
      </div>
      <button disabled={props.isLoading} onClick={props.handleSubmit}>
        {props.isLoading ? "Loading…" : "Create Account"}
      </button>
    </div>
  );
}
```

2. Open `app/globals.css` and add these classes to the end of the file:

```css app/globals.css theme={"theme":"github-dark-dimmed"}
.wrapper {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  min-height: 100vh;
  gap: 1rem;
  padding: 2rem 3rem;
  width: 100%;
  max-width: 800px;
  margin: 0 auto;
  box-sizing: border-box;
}

@layer base {
  h1 {
    font-size: 2rem;
    font-weight: 600;
    text-align: center;
    margin: 0;
  }
}

input {
  width: 100%;
  padding: 0.5rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}

.input-group {
  width: 100%;
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 0.5rem;
}

button {
  background-color: #f35b22;
  color: #fff;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 4px;
  cursor: pointer;
}

button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
```

3. Create a client component for the home page at `app/components/HomePage.tsx`:

```tsx app/components/HomePage.tsx theme={"theme":"github-dark-dimmed"}
"use client";

import CreateAccountForm from "./CreateAccountForm";

export default function HomePage() {
  return (
    <main>
      <CreateAccountForm />
    </main>
  );
}
```

4. Update `app/page.tsx` to use the new component:

```tsx app/page.tsx theme={"theme":"github-dark-dimmed"}
import HomePage from "./components/HomePage";

export default function Home() {
  return <HomePage />;
}
```

## 4. Install and initialize the JavaScript agent

1. To integrate Fingerprint into your Next.js app, add the Fingerprint React SDK via npm:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/react
```

*Note: This quickstart is written for version 3.x of the Fingerprint React SDK*

2. Import and initialize the Fingerprint provider in `app/layout.tsx`:

```tsx app/layout.tsx theme={"theme":"github-dark-dimmed"}
import { FingerprintProvider } from "@fingerprint/react";
```

3. Wrap your app with the Fingerprint provider in `app/layout.tsx`:

```tsx app/layout.tsx theme={"theme":"github-dark-dimmed"}
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <FingerprintProvider // [!code ++:5]
          apiKey="PUBLIC_API_KEY"
          region="us" // Ensure this matches your workspace region
          // For more information, see https://docs.fingerprint.com/docs/regions
        >
          {children}
          {/* [!code ++] */}
        </FingerprintProvider>
      </body>
    </html>
  );
}
```

4. Set `PUBLIC_API_KEY` to the public API key from the [Fingerprint dashboard](https://dashboard.fingerprint.com/api-keys).

*Note: For production, consider using* *[Next.js environment variables](https://nextjs.org/docs/app/building-your-application/configuring/environment-variables)* *to configure the key.*

## 5. Trigger visitor identification

Now that the JavaScript agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps the **Create Account** button.

When making the visitor identification request, you will receive the visitor ID as well as an event ID. Instead of using the visitor ID returned directly on the frontend (which could be tampered with), you'll send the event ID to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. In `app/components/HomePage.tsx`, import Fingerprint's `useVisitorData` hook and add the identification logic:

```tsx app/components/HomePage.tsx theme={"theme":"github-dark-dimmed"}
"use client";

import CreateAccountForm from "./CreateAccountForm";
import { useVisitorData } from "@fingerprint/react"; // [!code ++]

export default function HomePage() {
  const { getData, isLoading } = useVisitorData({ immediate: false }); // [!code ++]

  // [!code ++:5]
  async function handleSubmit() {
    const { visitor_id, event_id } = await getData();

    console.log("Visitor ID:", visitor_id);
    console.log("Event ID:", event_id);

    // Example of how you could send the event_id and form data to your server:
    // await fetch("http://localhost:3000/api/create-account", {
    //   method: "POST",
    //   headers: { "Content-Type": "application/json" },
    //   body: JSON.stringify({
    //     username: username.value,
    //     password: password.value,
    //     event_id,
    //   }),
    // });
  } // [!code ++]

  return (
    <main>
      {/* [!code ++] */}
      <CreateAccountForm isLoading={isLoading} handleSubmit={handleSubmit} />
    </main>
  );
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

This gives you:

* `getData()`: A function to trigger visitor identification on demand.
* `isLoading`: A flag to monitor visitor identification progress.

By setting immediate to false you're triggering device identification only when needed with the `getData()` method.

*Check our* *[GitHub repo](https://github.com/fingerprintjs/react)* *for available useVisitorData options.*

## 6. Test the app

1. If your dev server isn't already running, start it with:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. In your browser, go to [http://localhost:3000](http://localhost:3000/).
3. If you have any ad blockers, turn them off for localhost. View the [documentation](/docs/protecting-the-javascript-agent-from-adblockers) to learn how to protect your Fingerprint implementation from ad blockers in production.
4. Enter a username and password, then click **Create Account**.
5. Open the developer console in your browser and you should see the visitor ID and event ID in the output:

```text Output theme={"theme":"github-dark-dimmed"}
Visitor ID: JkLmNoPqRsTuVwXyZaBc
Event ID: 1234566477745.abc1GS
```

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the `event_id` to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information data and use it to make decisions and prevent fraud.

Check out these related resources:

* [React SDK reference](https://github.com/fingerprintjs/react)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Node.js Server Quickstart
Source: https://docs.fingerprint.com/docs/node-server-quickstart

Get started using the Node.js Server SDK

## Overview

In this quickstart, you'll add Fingerprint to a [Node](https://nodejs.org/) server using the web framework [Fastify](https://fastify.dev/) to prevent fraudulent account creation.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. You can flag and block suspicious users by identifying the device behind each sign-up attempt, login, or transaction.

In this quickstart, you'll learn how to:

* Set up a Fastify server with a Fingerprint integration
* Retrieve visitor identification data using the Server API
* Block bots and suspicious devices
* Prevent multiple signups from the same device

This guide focuses on the backend integration and must be completed after identifying a visitor and generating an event ID. **Before starting this quickstart, start with one of the [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview) quickstarts to see how to identify a visitor in your frontend.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* **A completed frontend or mobile Fingerprint implementation (See the quickstarts)**
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Get your secret API key

<Note>
  Before starting this quickstart, you should already have a frontend Fingerprint implementation
  that sends the `event_id` to your server. If not, pause here and check out one of our
  [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview)
  quickstarts first.
</Note>

If you're ready:

1. Sign in and go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the Fingerprint dashboard.
2. Create a new **secret API key**.
3. Copy it somewhere safe so you can use it to retrieve full visitor identification data from the Server API.

## 2. Set up your project

To get started, set up a basic server. If you already have a project you want to use, you can skip to the next section.

1. Create a new Node project and install Fastify and the Fingerprint Node Server SDK:

```bash Terminal theme={"theme":"github-dark-dimmed"}
mkdir fingerprint-node-quickstart && cd fingerprint-node-quickstart
npm init -y
npm install fastify @fingerprint/node-sdk
```

*Note: This quickstart is written for version 7.x of the Fingerprint Node Server SDK*

2. Enable ES modules by updating the type in your package.json to be `module`:

```json package.json theme={"theme":"github-dark-dimmed"}
{
  "type": "module"
}
```

3. Create a new file called `server.js` and add a basic Fastify server setup:

```javascript server.js theme={"theme":"github-dark-dimmed"}
import Fastify from "fastify";

const app = Fastify();

app.post("/api/create-account", async (request, reply) => {
  // We'll add Fingerprint logic here
  return reply.send({ status: "Account created!" });
});

app.listen({ port: 3000 }, (err) => {
  if (err) throw err;
  console.log("Server running on http://localhost:3000");
});
```

Here we are running the server at port 3000 and have created a new POST route for account creation. Note that the `/api/create-account` route should match what you have set up in your frontend implementation where you are sending the Fingerprint `event_id` to your server. Your server will receive the initial identification information from identifying a visitor on the frontend and use it to get the full visitor data on the backend.

## 3. Initialize Fingerprint and retrieve visitor data

Now you'll configure the Fingerprint Node Server SDK using your secret API key and use it to fetch detailed visitor data for each signup attempt.

When making the initial visitor identification request in the frontend, you received an `event_id`. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. At the top of your `server.js` file, import and initialize the SDK with your secret API key:

```javascript server.js theme={"theme":"github-dark-dimmed"}
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

const client = new FingerprintServerApiClient({
  apiKey: "SECRET_API_KEY", // Replace with your actual secret key
  region: Region.Global, // Change to your Fingerprint workspace region
});
```

*For a production implementation make sure to store and reference your secret key securely.*

2. In your `/api/create-account` route, retrieve the `event_id` you are sending from the frontend and fetch the full visitor identification details with `getEvent()`:

<Note>
  **requestId vs event\_id:** Depending on which quickstart you completed, your frontend may send
  either `requestId` (older SDKs) or `event_id` (v4 and newer). Both refer to the same
  identification event and work with the Server API in the same way. Use whichever value your
  frontend sends (`requestId` or `event_id`) as the event identifier below.
</Note>

```javascript server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/create-account", async (request, reply) => {
  const { event_id, username, password } = request.body;
  const event = await client.getEvent(event_id);

  //...
```

Using the `event_id` the Fingerprint server client will retrieve the full data for the visitor identification request. The returned object will contain the visitor ID, IP address, device and browser details, and Smart Signals like bot detection, incognito mode detection, and detections for VPN or virtual machine use.

You can see a full example of the event structure, and test it with your own device, in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 4. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection Smart Signal which is available only on paid plans.
</Note>

A simple but powerful way to prevent fraudulent account creation is to block automated signups that come from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

1. Continuing in your `/api/create-account` route, check the bot signal returned in the `event` object:

```javascript server.js theme={"theme":"github-dark-dimmed"}
const botDetected = event.bot !== "not_detected";

if (botDetected) {
  return reply.code(403).send({ error: "Failed to create account." });
}
```

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found. You can also layer in other Smart Signals to catch more suspicious devices. For example, you can use Fingerprint's [Suspect Score](/docs/suspect-score) to determine when to add additional friction to create an account.

## 5. Prevent multiple signups from the same device

To catch repeated signups from the same device, you can use the `visitorId` from the Fingerprint identification event. By saving this ID alongside each created account, you can detect and block duplicate signups from the same device. We'll be using a simple database to demonstrate how this works with SQLite.

1. Install the SQLite package:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install sqlite3
```

2. At the top of your `server.js` file, import and initialize the database:

```javascript server.js theme={"theme":"github-dark-dimmed"}
import sqlite3 from "sqlite3";

const db = new sqlite3.Database("database.db");

db.run(`
  CREATE TABLE IF NOT EXISTS accounts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT,
    password TEXT,
    visitorId TEXT
  )
`);
```

3. In your `/api/create-account` route handler, after getting the event, extract the `visitorId`:

```javascript server.js theme={"theme":"github-dark-dimmed"}
const visitorId = event.identification.visitor_id;
```

4. Check if this device has already created an account; if yes, block the account creation:

```javascript server.js theme={"theme":"github-dark-dimmed"}
// Check if the visitorId already exists in the database
const existingRow = await new Promise((resolve, reject) => {
  db.get("SELECT COUNT(*) as count FROM accounts WHERE visitorId = ?", [visitorId], (err, row) => {
    if (err) reject(err);
    resolve(row);
  });
});

if (existingRow.count > 0) {
  return reply.code(429).send({ error: "Failed to create account." });
}

// Otherwise, insert the new account
await new Promise((resolve, reject) => {
  db.run(
    "INSERT INTO accounts (username, password, visitorId) VALUES (?, ?, ?)",
    [username, password, visitorId],
    (err) => {
      if (err) reject(err);
      resolve();
    },
  );
});
```

This gives you a basic system to detect and block repeat signups. You can expand on this by allowing a limited number of accounts per device, adjusting your response based on business rules, only evaluating recent signups, etc.

<Info>
  This is a minimal example to show how to use the Fingerprint Node Server SDK. In a real
  application, make sure to implement proper security practices, especially around password handling
  and storage.
</Info>

## 6. Test your implementation

Now that everything is set up, you can test the full flow using your existing frontend.

### Before you test

If your frontend is running on a different port (like localhost:5173 or localhost:3001), you may run into CORS issues for testing. To quickly fix this for local development & testing:

1. Install the Fastify CORS plugin:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fastify/cors
```

2. Import it in `server.js`, then register it right after creating your Fastify app:

```javascript server.js theme={"theme":"github-dark-dimmed"}
import cors from "@fastify/cors"; // New
const app = Fastify();
await app.register(cors); // New
```

### Test the implementation

1. Start your Fastify server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
node server.js
```

2. In your frontend, trigger a sign-up request that sends the `event_id`, `username`, and `password` to your `/api/create-account` endpoint. To see the reply messages make sure to parse and display or console log the response from your server.
3. Within your frontend, input a username and password to create a user. Then try to create another user and see that the second attempt will be rejected.
4. Bonus: Try creating an account using a headless browser.

## Next steps

You now have a working backend fraud check using Fingerprint. From here, you can expand your logic with more Smart Signals, adjust thresholds based on your risk tolerance, or introduce additional checks for suspicious users.

These same techniques apply to a wide range of fraud prevention use cases, from detecting fake reviews to blocking payment abuse or preventing account takeovers.

To go further, check out the use case tutorials for step-by-step guides tailored to specific problems you can solve with Fingerprint.

Check out these related resources:

* [Node SDK Reference](https://github.com/fingerprintjs/node-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Nuxt Quickstart
Source: https://docs.fingerprint.com/docs/nuxt-quickstart

Get started using the Fingerprint Vue SDK with Nuxt

## Overview

In this quickstart, you'll add Fingerprint to a new [Nuxt](https://nuxt.com/) project and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend integration. You'll install the [Fingerprint Vue SDK](/docs/vuejs) and initialize the JavaScript agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of [Nuxt](https://nuxt.com/) and [Vue 3](https://vuejs.org/)

<Note>
  This quickstart only covers the **frontend setup**. You'll need a [backend
  server](/reference/server-sdks) to receive and process the device identification event to enable
  fraud detection. Check out one of the [backend quickstarts](/docs/server-quickstarts-overview)
  after completing this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the JavaScript agent.

## 2. Set up your project

To get started, scaffold a new Nuxt app. If you already have a project you want to use, you can skip to the next section.

1. Create a new Nuxt project:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm create nuxt@latest fingerprint-nuxt-quickstart
cd fingerprint-nuxt-quickstart
npm install
```

2. When prompted, choose the minimal configuration and default options.

3. Open the `fingerprint-nuxt-quickstart` folder in your code editor and you're ready to go! To run your project, run:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

4. In your browser, go to [http://localhost:3000](http://localhost:3000/), and you should see the Nuxt welcome page.

## 3. Set up your account creation form

1. Before adding Fingerprint, create a new component at `app/components/CreateAccountForm.vue` with the following:

```vue app/components/CreateAccountForm.vue theme={"theme":"github-dark-dimmed"}
<script setup lang="ts">
import { ref } from 'vue';

const username = ref('');
const password = ref('');

async function handleSubmit() {
  // Logic will be added in further steps
}
</script>

<template>
  <div class="wrapper">
    <h1>Create an account</h1>
    <div class="input-group">
      <label for="username">Username</label>
      <input id="username" v-model="username" type="text" placeholder="Username" required />
    </div>
    <div class="input-group">
      <label for="password">Password</label>
      <input id="password" v-model="password" type="password" placeholder="Password" required />
    </div>
    <button @click="handleSubmit">Create Account</button>
  </div>
</template>

<style scoped>
.wrapper {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  min-height: 100vh;
  gap: 1rem;
  padding: 2rem 3rem;
  width: 100%;
  max-width: 800px;
  margin: 0 auto;
  box-sizing: border-box;
  font-family: 'Inter', 'Segoe UI', Arial, sans-serif;
}

input {
  width: 100%;
  padding: 0.5rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}

.input-group {
  width: 100%;
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 0.5rem;
}

button {
  background-color: #f35b22;
  color: #fff;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 4px;
  cursor: pointer;
}

button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
</style>
```

## 4. Install and initialize the Fingerprint Vue SDK

1. To integrate Fingerprint into your Nuxt app, add the Fingerprint Vue SDK via npm:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/vue
```

*Note: This quickstart is written for version 2.x of the Fingerprint Vue SDK*

2. Create a client-side plugin so Fingerprint only runs in the browser. Create `app/plugins/fingerprint.client.ts`:

```ts app/plugins/fingerprint.client.ts theme={"theme":"github-dark-dimmed"}
import { FingerprintPlugin } from '@fingerprint/vue';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(FingerprintPlugin, {
    apiKey: 'PUBLIC_API_KEY',
    region: 'us', // Ensure this matches your workspace region
    // For more information, see https://docs.fingerprint.com/docs/regions
  });
});
```

The `.client` suffix ensures the plugin runs only on the client, which is required because fingerprinting relies on browser APIs.

3. Replace `PUBLIC_API_KEY` with your public API key from the [Fingerprint dashboard](https://dashboard.fingerprint.com/api-keys).

*Note: For production, consider using* *[Nuxt runtime config](https://nuxt.com/docs/4.x/guide/going-further/runtime-config)* *to configure the key.*

## 5. Trigger visitor identification

Now that the JavaScript agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps the **Create Account** button.

When making the visitor identification request, you will receive a visitor ID as well as an event ID. Instead of using the visitor ID returned directly on the frontend (which could be tampered with), you'll send the event ID to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. In `app/components/CreateAccountForm.vue`, import the Fingerprint `useVisitorData` hook and replace the placeholder logic:

```vue app/components/CreateAccountForm.vue theme={"theme":"github-dark-dimmed"}
<script setup lang="ts">
import { ref } from 'vue';
// [!code ++]
import { useVisitorData } from '@fingerprint/vue';

const username = ref('');
const password = ref('');
// [!code ++]
const { isLoading, getData } = useVisitorData({ immediate: false });

async function handleSubmit() {
  // [!code ++:6]
  const { visitor_id, event_id } = await getData();

  console.log('Visitor ID:', visitor_id);
  console.log('Event ID:', event_id);

  // Send the event_id to your server
  // await fetch("/api/create-account", {
  //   method: "POST",
  //   headers: { "Content-Type": "application/json" },
  //   body: JSON.stringify({
  //     username: username.value,
  //     password: password.value,
  //     event_id,
  //   }),
  // });
}
</script>
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

This gives you:

* `getData()`: A function to trigger visitor identification on demand.
* `isLoading`: A flag to monitor visitor identification progress.

By setting `immediate` to `false` you're triggering device identification only when needed with the `getData()` method.

*Check the* [*Vue SDK reference*](https://fingerprintjs.github.io/vue/) *for available useVisitorData options.*

2. Update the button to use `isLoading`:

```vue app/components/CreateAccountForm.vue theme={"theme":"github-dark-dimmed"}
<template>
  <div class="wrapper">
    <!-- ... -->
    <!-- [!code ++:3] -->
    <button :disabled="isLoading" @click="handleSubmit">
      {{ isLoading ? 'Loading…' : 'Create Account' }}
    </button>
  </div>
</template>
```

3. Update `app/app.vue` to display the form. Wrap it in `<ClientOnly>` so it only renders in the browser (Nuxt uses server-side rendering by default):

```vue app/app.vue theme={"theme":"github-dark-dimmed"}
<template>
  <div>
    <!-- [!code ++:3] -->
    <ClientOnly>
      <CreateAccountForm />
    </ClientOnly>
  </div>
</template>
```

## 6. Test the app

1. If your dev server isn't already running, start it with:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. In your browser, go to [http://localhost:3000](http://localhost:3000/).
3. If you have any ad blockers, turn them off for localhost. View the [documentation](/docs/protecting-the-javascript-agent-from-adblockers) to learn how to protect your Fingerprint implementation from ad blockers in production.
4. Enter a username and password, then click **Create Account**.
5. Open the developer console in your browser and you should see the `visitor_id` and `event_id` in the output:

```text Output theme={"theme":"github-dark-dimmed"}
Visitor ID: JkLmNoPqRsTuVwXyZaBc
Event ID: 1234566477745.abc1GS
```

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the `event_id` to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information data and use it to make decisions and prevent fraud.

Check out these related resources:

* [Vue SDK reference](https://github.com/fingerprintjs/vue)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Optimize JavaScript agent usage
Source: https://docs.fingerprint.com/docs/optimize-javascript-agent

A collection of techniques to optimize your usage of the JavaScript agent. With a few adjustments, you can reduce latency and decrease the number of API calls required for your use case.

The [JavaScript agent](/reference/js-agent) is a client-side JavaScript agent that collects browser attributes and sends them to Fingerprint servers for processing and identification.

Using the JavaScript agent requires at least two HTTP requests:

* `start()` — the agent-download request that retrieves the latest fingerprinting logic from our CDN and collects the necessary browser attributes. This request is **not billed**. It must happen before sending the identification request.
* `get()` — the identification request that sends the collected browser attributes to Fingerprint API and receives a `visitor_id` in return. This request **is billed** and counts towards your monthly quota. It can happen only after `start()` (immediately or later).

By optimizing these requests and timing them right, you can make visitor identification both faster and more cost-effective.

## Only use the JavaScript agent where you need it

Depending on your use case, the placement of the JavaScript agent can range from all pages of your app to specific pages and events. We recommend calling `get()` only when the `visitor_id` will be used by your application. You can also choose to call `get()` only after the visitor [gives consent to using cookies on your website](/docs/privacy-and-compliance#do-i-need-to-have-a-gdpr-consent-management-banner-if-using-fingerprint).

The table below lists common use cases and recommended integration of the JavaScript agent.

| Use Case                                                                                                | JavaScript agent Placement        | Identification request (`get()`)                                         | Estimated Volume (per month)             |
| :------------------------------------------------------------------------------------------------------ | :-------------------------------- | :----------------------------------------------------------------------- | :--------------------------------------- |
| **Anonymous Visitor Identification** - bulk information collection of anonymous visitors                | Landing page, checkout page, etc. | Page load or the start of the session (depending on your implementation) | 1:1 number of page loads/sessions        |
| **Account Takeover Prevention** - prevent account theft using malicious login attempts                  | Login page                        | "Login" button click                                                     | 1:1 number of attempted logins           |
| **Securing Login & Reducing Friction** - reduce login friction with conditional security checks         | Login page                        | "Login" button click                                                     | 1:1 number of attempted logins           |
| **Account Sharing Prevention** - prevent users from sharing accounts                                    | Login page                        | "Login" button click                                                     | 1:1 number of attempted logins           |
| **Multi-account Prevention** - prevent users from creating multiple accounts                            | Registration page                 | "Register" button click                                                  | 1:1 number of attempted sign-ups         |
| **Form & Survey Abuse** - protect forms from duplicate entries                                          | Form page                         | “Submit Form” button click                                               | 1:1 number of attempted form submissions |
| **Coupon & Promo Abuse** - protect profits from duplicate promotion abuse                               | Checkout page                     | “Apply coupon” button click                                              | 1:1 number "apply coupon" button clicks  |
| **Credit Card Fraud** - block users who repeatedly use faulty credit cards                              | Checkout page                     | “Checkout” button click                                                  | 1:1 number of checkout attempts          |
| **E-commerce Tracking** - track orders made by anonymous or guest visitors                              | Checkout page                     | “Checkout” button click                                                  | 1:1 number of checkout attempts          |
| **Paywall Circumvention** - detect Incognito mode and prevent unlimited views of your paywalled content | Paywalled pages                   | Page load                                                                | 1:1 number of paywalled page loads       |

## Pre-connect to Fingerprint URLs

API [pre-connect](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect) is recommended for improved request timings. To enable it, place the `preconnect` directive as early as possible in your head tag:

<CodeGroup>
  ```html CDN installation theme={"theme":"github-dark-dimmed"}
  <html>
  <head>
    <link rel="preconnect" href="https://fpcdn.io">
    <link rel="preconnect" href="https://api.fpjs.io">
    ... styles, js etc
  ```

  ```html NPM installation theme={"theme":"github-dark-dimmed"}
  <html>
  <head>
    <link rel="preconnect" href="https://fpnpmcdn.net">
    <link rel="preconnect" href="https://api.fpjs.io">
    ... styles, js etc
  ```
</CodeGroup>

Pay attention to the URLs you need to pre-connect to:

* If you are using the default (US/Global) region, pre-connect to this URL: `https://api.fpjs.io`
* If you're using the EU region, pre-connect to this URL instead:  `https://eu.api.fpjs.io`.
* If you're using the Mumbai API, pre-connect to this URL instead: `https://ap.api.fpjs.io`
* If you're using the [Custom subdomain](/docs/custom-subdomain-setup) or another [Proxy integration](/docs/protecting-the-javascript-agent-from-adblockers) on a subdomain, use the subdomain as the pre-connect URL, for example:

```html HTML theme={"theme":"github-dark-dimmed"}
<html>
<head>
  <link rel="preconnect" href="https://metrics.yourwebsite.com">
```

## Preload the JavaScript agent

Generally, we recommend initializing the JavaScript agent (by calling `Fingerprint.start(...)`) as early as possible, and requesting the visitor identifier (by calling `get()`) only when you need it. A good moment to `start()` the JavaScript agent is when your application starts.

An example of a browser application improvement:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// An instance is created when the page starts
class MyApp {
  constructor() {
    this.fp = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' }) // [!code ++]

    const button = document.querySelector('#button')
    button.addEventListener('click', this.handleClick)
  }

  handleClick = async () => {
    const fp = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' }) // [!code --]
    const result = await this.fp.get()
    alert(`Your id: ${result.visitor_id}`)
  }
}
```

This decreases the time of getting the `visitor_id` because the JavaScript agent is already loaded and the browser signals are collected before the user clicks the button.

<Tip>
  **Starting the JavaScript agent is free**

  Don't worry, the agent `start()` call [is not billed](/docs/billing#identification-api-request-as-a-billing-unit), only the identification `get` request counts towards your monthly plan.
</Tip>

## Pre-request the visitor ID

You can decrease the time to get the visitor ID even more. You can call `fp.get()` a small time before you need the identifier. For example, when the visitor fills all the form fields or moves the cursor above the submit button. Getting the visitor ID will be in progress or complete when you need it. For example:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
class MyApp {
  constructor() {
    this.fp = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' }) 

    const button = document.querySelector('#button')
    button.addEventListener('mouseover', this.handleAboutToClick, { once: true }) // [!code ++]
    button.addEventListener('click', this.handleClick)
  }

  handleAboutToClick = () => { // [!code ++:4]
    // In production add memoization to prevent calling "get" multiple times
    this.fpResultPromise = this.fp.get()
  }

  handleClick = async () => {
    const result = await this.fp.get() // [!code --] 
    const result = await this.fpResultPromise // [!code ++]
    alert(`Your id: ${result.visitor_id}`)
  }
}
```

## Cache the visitor ID

Depending on your use case, your implementation might benefit from caching the visitor ID in the browser for anything between 1 to 12 hours and only calling `get()` when the cache expires. See [Caching visitor information](/docs/identify-visitors#caching-the-visitor-id) for more information on caching best practices.


# Paywall Enforcement
Source: https://docs.fingerprint.com/docs/paywall-use-case-tutorial

Learn how to implement paywall protection and prevent content bypass

## Overview

This tutorial walks through implementing Fingerprint to enforce paywalls, ensuring that visitors cannot bypass limits or access premium content by clearing cookies, changing IP addresses, or using incognito mode.

You'll begin with a starter app that includes a mock news site with sample articles and a basic paywall flow that limits the number of articles you can read for free. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to track article views and block further access once the limit is reached.

By the end, you'll have a sample app that reliably enforces paywall limits per visitor and can be customized to fit your workspace or content access model.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `paywall` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="article.html - Article page" />

    <Tree.File name="article.js - Front-end logic to display articles" />

    <Tree.File name="index.html - News homepage" />

    <Tree.File name="index.js - Front-end logic to display article summaries" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="articlesApi.js - Paywall and article logic" />

    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="server.js - Serves static files and article endpoints" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock news homepage. Click three different articles to read them. Notice that you cannot read any new articles after that.
7. The demo stores articles read data in localStorage to enforce the paywall. To reset the demo, either click **Reset demo** at the bottom of the page or manually clear the browser storage (e.g., open DevTools → Application → Local Storage → delete the site entry, or run `localStorage.clear()` in the console), then reload and read more articles. You'll see the paywall is easily bypassed when client-side storage is cleared.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user goes to read an article. The JavaScript agent returns both a `visitor_id` and an `event_id`. The visitor ID can be used to identify a browser or device uniquely and to enforce the paywall. Instead of relying on the `visitor_id` returned on the client side directly, you'll send the `event_id` to your server along with the request for the article content. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including the visitor ID, bot detection, and other signals.

1. Before adding any new code, let's delete all the client-side paywall logic and localStorage tracking. Specifically, open the `public/article.js` file and remove the `FREE_ARTICLES_LIMIT` constant and these functions: `getArticlesRead()`, `updateFreeCount()`, and `updateArticlesRead()`.
2. In `getArticle()`, delete the block that checks the number of articles read and toggles the paywall. Keep only the line that gets the `articleId` and everything after the `fetch` call.

```javascript public/article.js theme={"theme":"github-dark-dimmed"}
async function getArticle() {
  const articleId = window.location.pathname.split("/").pop();

  try {
    const response = await fetch(`/api/article/${articleId}`);

    const data = await response.json();
    const article = data.article;

  // ...
}
```

3. At the bottom of the file, remove the calls to `updateArticlesRead()` and `updateFreeCount()`, leaving only the `getArticle()` call.
4. At the top of `public/article.js`, load the JavaScript agent:

```javascript public/article.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

5. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
6. Inside the `getArticle()` function, request visitor identification from Fingerprint using the `get()` method. Then, update the `fetch` call to use a `POST` request and include the returned `event_id` in the body when sending the article to the server. (A matching `POST` endpoint is already set up for this tutorial.)

```javascript public/article.js theme={"theme":"github-dark-dimmed"}
async function getArticle() {
  const articleId = window.location.pathname.split("/").pop();

  try {
    const fp = await fpPromise;
    const { event_id: eventId } = await fp.get();

    const response = await fetch(`/api/article/${articleId}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ eventId }),
    });
    const data = await response.json();

    // ...
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

1. Update the "free articles remaining" message using the value returned from the server. (This won't work yet — it will be connected in the next steps.)

```javascript public/article.js theme={"theme":"github-dark-dimmed"}
async function getArticle() {
  // ...

    const data = await response.json();

    const articlesRemaining = data.articlesRemaining;
    let text = `${articlesRemaining} free articles remaining`;
    if (articlesRemaining == 0)
      text = "You have reached your free article limit";
    freeCountEl.textContent = text;

    if (!data.success) { ... }

  // ...
}
```

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your backend logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file already defines API routes for the app. Update the `/api/article/:id` `POST` route to also extract `eventId` from the request body and pass it into the `getArticle` function. (You can delete the `/api/article/:id` GET route.)

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/article/:id", async (req, reply) => {
  const article = await getArticle(req.params.id, req.body.eventId);
  return reply.send(article);
});
```

2. The `server/articlesApi.js` file contains the logic for fetching articles. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/articlesApi.js theme={"theme":"github-dark-dimmed"}
import fs from "fs";
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `getArticle` function to also accept `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/articlesApi.js theme={"theme":"github-dark-dimmed"}
export async function getArticle(articleId, eventId) {
  const event = await fpServerApiClient.getEvent(eventId);

  // Simple article retrieval for demo
  const articles = JSON.parse(fs.readFileSync("./server/data/articles.json", "utf-8"));

  const article = articles.find((a) => a.id === Number(articleId));

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Enforce paywall limits by visitor ID

Next, use the trusted visitor ID to see how many free articles a visitor has read and enforce paywall limits. This ensures that even if someone clears cookies, uses incognito mode, or switches networks, their access is still tied to the same browser or device.

Note: The starter app includes a SQLite database with the following table already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
articles_read - Stores which articles each visitor has accessed
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  visitorId TEXT NOT NULL,
  articleId TEXT NOT NULL,
  createdAt INTEGER NOT NULL
```

1. Add some helper functions to the bottom of the `server/articlesApi.js` file to record and check articles read by the visitor:

```javascript server/articlesApi.js theme={"theme":"github-dark-dimmed"}
// Record an article view (only if it hasn't been read before)
function recordArticleRead(visitorId, articleId) {
  const exists = db
    .prepare(`SELECT 1 FROM articles_read WHERE visitorId = ? AND articleId = ? LIMIT 1`)
    .get(visitorId, articleId);

  if (!exists) {
    db.prepare(`INSERT INTO articles_read (visitorId, articleId, createdAt) VALUES (?, ?, ?)`).run(
      visitorId,
      articleId,
      Date.now(),
    );
  }
}

// Get all unique articles read by a visitor
function getArticlesRead(visitorId) {
  const rows = db
    .prepare(
      `SELECT DISTINCT articleId 
       FROM articles_read 
       WHERE visitorId = ? 
       ORDER BY createdAt ASC`,
    )
    .all(visitorId);
  return rows.map((r) => r.articleId);
}
```

2. Update `getArticle` to retrieve the `visitor_id`, from the `event` object and use it to determine how many articles the visitor has read using `getArticlesRead`. Make sure to include `articlesRemaining` in the responses as well:

```javascript server/articlesApi.js theme={"theme":"github-dark-dimmed"}
export async function getArticle(articleId, eventId) {
  const FREE_ARTICLES_LIMIT = 3;

  const event = await fpServerApiClient.getEvent(eventId);
  const visitorId = event.identification.visitor_id || "";

  const articlesRead = getArticlesRead(visitorId);
  const articlesRemaining = Math.max(0, FREE_ARTICLES_LIMIT - articlesRead.length);

  // Simple article retrieval for demo
  const articles = JSON.parse(fs.readFileSync("./server/data/articles.json", "utf-8"));
  const article = articles.find((a) => a.id === Number(articleId));
  if (!article) {
    console.error("Article not found");
    return {
      success: false,
      message: "Article not found",
      articlesRemaining,
    };
  }

  // ...
}
```

3. Then add new paywall logic to check if the visitor can read the article. If so, log the article as being read and return its contents, otherwise block the article request:

```javascript server/articlesApi.js theme={"theme":"github-dark-dimmed"}
export async function getArticle(articleId, eventId) {
  // ...

  if (!article) {
    console.error("Article not found");
    return {
      success: false,
      message: "Article not found",
      articlesRemaining,
    };
  }

  // Paywall check
  if (articlesRemaining <= 0 && !articlesRead.includes(articleId)) {
    console.error("No more free articles.");
    return {
      success: false,
      message: "You have reached the maximum number of free articles. Subscribe today!",
      articlesRemaining,
    };
  }

  // Record read and return updated remaining count
  recordArticleRead(visitorId, articleId);
  return {
    success: true,
    article,
    articlesRemaining: Math.max(0, articlesRemaining - 1),
  };
}
```

## 6. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection and Suspect Score Smart Signals, which are only
  available on paid plans.
</Note>

A simple but effective way to protect your paywalled content is to block automated scraping attempts. The `event` object also includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/), which identifies automated activity so you can prevent bots from accessing your articles.

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of scraping, and `not_detected` when no bot activity is found.

1. Continuing in the `getArticle` function in `server/articlesApi.js`, check the bot signal in the `event` object and block requests from bots:

```javascript server/articlesApi.js theme={"theme":"github-dark-dimmed"}
export async function getArticle(articleId, eventId) {
  // ...

  if (!article) { ... }

  // Check for bot activity
  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return {
      success: false,
      message: "Article not found.",
      articlesRemaining,
    };
  }

  // ...
}
```

You can also add [Suspect Score](/docs/suspect-score) as an additional layer. The Suspect Score is a weighted representation of all Smart Signals in the identification payload, helping to identify suspicious activity. While you wouldn't normally block article views based only on a high score, you could use it to flag suspicious visitors, limit access, or trigger additional verification.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the article request if it exceeds a chosen threshold (for example, 20):

```javascript server/articlesApi.js theme={"theme":"github-dark-dimmed"}
export async function getArticle(articleId, eventId) {
  // ...

  // Check for bot activity
  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return {
      success: false,
      message: "Article not found.",
      articlesRemaining,
    };
  }

  // Check for a high suspect score
  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return {
      success: false,
      message: "Article not found.",
      articlesRemaining,
    };
  }

  // ...
}
```

Together with the visitor ID and bot detection Smart Signal, Fingerprint allows you to protect your content and enforce paywalls that can't be bypassed with cookies or incognito mode. You can extend this by analyzing additional signals, adjusting access limits, or customizing how you handle suspicious visitors.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to apply proper security practices, error handling, and paywall logic that align with your
  production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full protected paywall flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Read three different articles and on your fourth unique article you should hit the paywall.
3. Open a private browser window, visit the site, and try to read another new article beyond the limit. You will still be paywalled.
4. Bonus: Test the flow using a headless browser or automation tool to see bot detection in action. A sample script is available in `test-bot.js`. While your app is running, run the script with `node test-bot.js` in your terminal and observe that the automated article requests are denied.

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

## Next steps

You now have a working paywall flow that enforces article limits and blocks scraping bots with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune access rules based on your content strategy, or add extra defenses like rate limiting or dynamic content gating.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Personalization
Source: https://docs.fingerprint.com/docs/personalization-use-case-tutorial

Learn how to personalize experiences for anonymous visitors

## Overview

This tutorial walks through implementing Fingerprint to personalize the experience for anonymous visitors, without requiring them to create an account or log in.

You'll begin with a starter app that includes a mock vacation rental site with a list of properties and basic filtering. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to show rentals closest to the visitor's location on their first visit, and restore their viewing history and saved filters when they return.

By the end, you'll have a sample app that delivers a tailored experience to every visitor from the moment they land, and remembers their preferences across sessions.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<Note>
  Using Fingerprint for personalization may require visitor consent depending on your local
  regulations, similar to the requirements around cookies. The incognito mode behavior demonstrated
  in this tutorial is intended to make it easy to simulate a returning visitor during development.
  We do not recommend using Fingerprint to persist personalization specifically in incognito mode in
  production because it conflicts with the users' expectations and may lead to a bad experience.
</Note>

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor:

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
cd use-case-tutorials/personalization
```

2. This tutorial will be using the `personalization` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Vacation rental browsing page" />

    <Tree.File name="index.js - Frontend logic for rental listings and filters" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="server.js - Serves static files and rental listing endpoint" />

    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="rentals.js - Rental listing and personalization logic" />

    <Tree.Folder name="data">
      <Tree.File name="rentals.json - Mock rental listing data with coordinates" />
    </Tree.Folder>
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=PUBLIC_API_KEY
FP_SECRET_API_KEY=SECRET_API_KEY
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock vacation rental site from the starter app. You'll see a "Hot Rentals" section showing three randomly selected properties, followed by the full listing grid with filters for property type, guests, bedrooms, amenities, and price. Click any card to open a detail view with the full description and amenity list. Try adjusting the filters, then open the page in a new tab and you'll see that your selections are gone. By default, the hot rentals are random and the app has no memory of previous visits.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when fetching rental listings. The JavaScript agent returns both a `visitor_id` and an `event_id`. You'll send the `event_id` to your server along with the request for rentals. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including geolocation data.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: 'us' }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).

3. In `public/index.js`, the page already calls `init()` on startup to fetch and render listings. Add `visitorId` to the state variables at the top of the file so it can be reused for saving preferences later:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
let visitorId = null;
```

4. Inside `init()`, request visitor identification from Fingerprint using the `get()` method. Store the visitor ID for later use and include the event ID when fetching rentals so the server can find rentals closest to the visitor's location:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
async function init() {
  const fp = await fpPromise;
  const result = await fp.get();
  visitorId = result.visitor_id;

  try {
    const response = await fetch("/api/rentals", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ eventId: result.event_id }),
    });

    const data = await response.json();

    // ...
  }
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details, including geolocation data.

<Note>
  This personalization use case demo is using the `visitor_id` from `fp.get()` directly. For fraud
  or security-sensitive use cases, never trust the `visitor_id` from the client, always retrieve it
  server-side using `getEvent()` so it can't be tampered with.
</Note>

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Sort rentals by proximity

Next, pass the `eventId` through to your rental listing logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event. You'll use the visitor's geolocation data to sort listings so that before they've interacted with anything, the listings are already arranged to be nearest to them.

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/rentals` route to accept a POST request, extract `eventId` from the request body, and pass it into the `getRentals` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post('/api/rentals', async (req, reply) => {
  const { eventId } = req.body;
  const result = await getRentals(eventId);
  return reply.send(result);
});
```

2. The `server/rentals.js` file contains the logic for fetching and personalizing rental listings. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`:

```javascript server/rentals.js theme={"theme":"github-dark-dimmed"}
import fs from 'fs';
import { db } from './db.js';
import { config } from 'dotenv';
import { FingerprintServerApiClient, Region } from '@fingerprint/node-sdk';

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).

4. Update the `getRentals` function to call `getEvent()`, extract the visitor's coordinates, and sort the listings by distance. Every rental in `rentals.json` includes a `lat` and `lng` for its city and you can sort by squared Euclidean distance:

```javascript server/rentals.js theme={"theme":"github-dark-dimmed"}
export async function getRentals(eventId) {
  const event = await fpServerApiClient.getEvent(eventId);
  const { latitude, longitude } = event.ip_info.v4.geolocation || {};

  const rentals = JSON.parse(fs.readFileSync('./server/data/rentals.json', 'utf-8'));

  const hotRentals = rentals.slice(0, 3);
  if (latitude && longitude) {
    rentals.sort((a, b) => {
      const da = (a.lat - latitude) ** 2 + (a.lng - longitude) ** 2;
      const db = (b.lat - latitude) ** 2 + (b.lng - longitude) ** 2;
      return da - db;
    });
  }

  return { success: true, rentals, hotRentals };
}
```

Using the `eventId`, the `getEvent` method retrieves the full data for the visitor identification event, including geolocation, device and browser details, and Smart Signals like bot detection, VPN detection, and more. You can see a full example of the event structure in the [demo playground](https://demo.fingerprint.com/playground).

Now every visitor sees listings sorted with the closest cities at the top. Visitors in London will see London and European properties first; visitors in San Francisco will see West Coast rentals at the top.

For checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Persist visitor filters across sessions

Next, use the `visitorId` from `fp.get()` to remember each visitor's filter choices. When they return their filters will be restored automatically.

Unlike fraud prevention use cases where every request should be verified server-side via `getEvent()`, personalization carries much lower risk. Since you already receive the visitor ID in the frontend, you can send it directly with preference saves rather than making a new `getEvent()` call each time. This keeps things simple and avoids unnecessary API calls.

The starter app includes a SQLite database with the following table already created for you:

```text SQLite database table theme={"theme":"github-dark-dimmed"}
visitor_preferences - Stores preferences for each visitor
  visitorId       TEXT PRIMARY KEY
  filters         TEXT NOT NULL DEFAULT '{}' (JSON string)
  recentlyViewed  TEXT NOT NULL DEFAULT '[]' (JSON array of rental IDs)
  updatedAt       INTEGER NOT NULL DEFAULT 0
```

1. Add helper functions to `server/rentals.js` to read and write filter preferences:

```javascript server/rentals.js theme={"theme":"github-dark-dimmed"}
function getFiltersFor(visitorId) {
  const row = db
    .prepare(`SELECT filters FROM visitor_preferences WHERE visitorId = ?`)
    .get(visitorId);
  return row ? JSON.parse(row.filters) : null;
}

function saveFiltersFor(visitorId, filters) {
  db.prepare(
    `
    INSERT INTO visitor_preferences (visitorId, filters, updatedAt)
    VALUES (?, ?, ?)
    ON CONFLICT(visitorId) DO UPDATE SET filters = excluded.filters, updatedAt = excluded.updatedAt
  `,
  ).run(visitorId, JSON.stringify(filters), Date.now());
}
```

2. Update `getRentals` to return saved filters alongside the listings:

```javascript server/rentals.js theme={"theme":"github-dark-dimmed"}
export async function getRentals(eventId) {
  // ...existing code...

  const visitorId = event.identification.visitor_id;
  const savedFilters = getFiltersFor(visitorId);

  return { success: true, rentals, hotRentals, savedFilters };
}
```

3. Add a `saveFilters` export to handle filter updates from the frontend:

```javascript server/rentals.js theme={"theme":"github-dark-dimmed"}
export function saveFilters(visitorId, filters) {
  if (!visitorId || !filters) {
    return { success: false, error: 'Request failed.' };
  }
  saveFiltersFor(visitorId, filters);
  return { success: true };
}
```

4. Add the corresponding route to `server/server.js`:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post('/api/preferences', (req, reply) => {
  const { visitorId, filters } = req.body;
  return reply.send(saveFilters(visitorId, filters));
});
```

5. Back in `public/index.js`, add an `applyFilters` function that restores saved filter state and syncs the UI, a `saveFilters` function that posts the current state, and a `debouncedSave` wrapper so rapid filter changes are batched into a single request. Add `saveTimer` to the state variables at the top of the file:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
let saveTimer = null;
```

Then add the functions:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
function applyFilters(saved) {
  saved.activeTypes?.forEach((t) => activeTypes.add(t));
  saved.activeAmenities?.forEach((a) => activeAmenities.add(a));
  minGuests = saved.minGuests ?? null;
  minBedrooms = saved.minBedrooms ?? null;
  maxPrice = saved.maxPrice ?? MAX_PRICE_CEILING;

  document.querySelectorAll('.filter-pill').forEach((btn) => {
    const { filter, value } = btn.dataset;
    let isActive = false;
    switch (filter) {
      case 'type':
        isActive = activeTypes.has(value);
        break;
      case 'amenity':
        isActive = activeAmenities.has(value);
        break;
      case 'guests':
        isActive = Number(value) === minGuests;
        break;
      case 'bedrooms':
        isActive = Number(value) === minBedrooms;
        break;
    }
    btn.toggleAttribute('data-active', isActive);
  });

  document.getElementById('priceSlider').value = maxPrice;
  document.getElementById('priceLabel').textContent =
    maxPrice >= MAX_PRICE_CEILING ? 'Any price' : `$${maxPrice}/night`;
}

function debouncedSave() {
  clearTimeout(saveTimer);
  saveTimer = setTimeout(saveFilters, 1000);
}

async function saveFilters() {
  if (!visitorId) return;

  await fetch('/api/preferences', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      visitorId,
      filters: {
        activeTypes: [...activeTypes],
        activeAmenities: [...activeAmenities],
        minGuests,
        minBedrooms,
        maxPrice,
      },
    }),
  });
}
```

6. In `init()`, call `applyFilters` if saved filters are returned:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
async function init() {
  // ...existing code...

  if (data.savedFilters) applyFilters(data.savedFilters);

  render();
}
```

7. Call `debouncedSave()` after `render()` in the filter pill click handler and the price slider handler:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
// In the filter pill click handler:
render();
debouncedSave();

// In the price slider handler:
render();
debouncedSave();
```

## 6. Show recently viewed rentals

When a visitor clicks to view a rental's details, save the rental ID. On their next visit, the "Hot Rentals" section will show those properties instead of a random selection.

1. Add a `getRecentlyViewedFor` helper and an `addRecentlyViewed` export to `server/rentals.js`:

```javascript server/rentals.js theme={"theme":"github-dark-dimmed"}
function getRecentlyViewedFor(visitorId) {
  const row = db
    .prepare(`SELECT recentlyViewed FROM visitor_preferences WHERE visitorId = ?`)
    .get(visitorId);
  return row ? JSON.parse(row.recentlyViewed) : null;
}

export function addRecentlyViewed(visitorId, rentalId) {
  if (!visitorId || !rentalId) {
    return { success: false, error: 'Request failed.' };
  }
  const current = getRecentlyViewedFor(visitorId) ?? [];
  const updated = [rentalId, ...current.filter((id) => id !== rentalId)].slice(0, 10);
  db.prepare(
    `
    INSERT INTO visitor_preferences (visitorId, recentlyViewed, updatedAt)
    VALUES (?, ?, ?)
    ON CONFLICT(visitorId) DO UPDATE SET recentlyViewed = excluded.recentlyViewed, updatedAt = excluded.updatedAt
  `,
  ).run(visitorId, JSON.stringify(updated), Date.now());
  return { success: true };
}
```

2. Update `getRentals` to use recently viewed IDs for the `hotRentals` response, falling back to the 3 random rentals if the visitor hasn't viewed anything yet:

```javascript server/rentals.js theme={"theme":"github-dark-dimmed"}
export async function getRentals(eventId) {
  // ...existing code...

  const viewedIds = getRecentlyViewedFor(visitorId) ?? [];
  const hotRentals =
    viewedIds.length > 0
      ? viewedIds.map((id) => rentals.find((r) => r.id === id)).filter(Boolean)
      : rentals.slice(0, 3);

  return { success: true, rentals, hotRentals, savedFilters };
}
```

3. Add the `/api/viewed` route to `server/server.js`:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post('/api/viewed', (req, reply) => {
  const { visitorId, rentalId } = req.body || {};
  return reply.send(addRecentlyViewed(visitorId, rentalId));
});
```

4. In `public/index.js`, add a `saveViewed` function and call it from `openModal`:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
async function saveViewed(rentalId) {
  await fetch('/api/viewed', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ visitorId, rentalId }),
  });
}
```

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
function openModal(rental) {
  // ...existing code...

  document.getElementById('rentalModal').classList.remove('hidden');
  saveViewed(rental.id);
}
```

On return visits, the Hot Rentals section will now show the properties the visitor previously clicked on instead of a random selection.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error checking, and data handling that align with your
  production standards and local regulations.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full personalized experience.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Notice that the listings are already sorted with cities closest to your location at the top with no interaction required.
3. Apply some filters and click a few rental cards to view their details.
4. Open the page in a private or incognito browser window. Your filters will be restored, the listings will again be sorted by proximity, and the Hot Rentals section will show the properties you just viewed.

## Next steps

You now have a working vacation rental site that sorts listings by proximity, remembers visitor filters, and surfaces recently viewed properties, all without requiring a login. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), add additional preference types, or use the visitor ID to power other personalization features like personalized recommendations.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](https://github.com/fingerprintjs/node-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# PHP Server Quickstart
Source: https://docs.fingerprint.com/docs/php-server-quickstart

Get started using the PHP Server SDK

## Overview

In this quickstart, you'll add Fingerprint to a [PHP](https://www.php.net/) server to prevent fraudulent account creation.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. You can flag and block suspicious users by identifying the device behind each sign-up attempt, login, or transaction.

In this quickstart, you'll learn how to:

* Set up a PHP server with a Fingerprint integration
* Retrieve visitor identification data using the Server API
* Block bots and suspicious devices
* Prevent multiple signups from the same device

This guide focuses on the backend integration and must be completed after identifying a visitor and generating an event ID. **Before starting this quickstart, start with one of the [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview) quickstarts to see how to identify a visitor in your frontend.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [PHP](https://www.php.net/downloads.php) 8.0 or later
* [Composer](https://getcomposer.org/download/) (PHP package manager) installed
* SQLite3 installed
* **A completed frontend or mobile Fingerprint implementation (See the quickstarts)**

## 1. Get your secret API key

<Note>
  Before starting this quickstart, you should already have a frontend Fingerprint implementation
  that sends the `event_id` to your server. If not, pause here and check out one of the
  [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview)
  quickstarts first.
</Note>

If you're ready:

1. Sign in and go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the Fingerprint dashboard.
2. Create a new **secret API key**.
3. Copy it somewhere safe so you can use it to retrieve full visitor identification data from the Server API.

## 2. Set up your project

We'll start by creating a PHP server that exposes a POST endpoint for account creation. If you already have a project you want to use, skip to the next section.

1. Create a project folder, move into it, and set up Composer with the required packages:

```bash Terminal theme={"theme":"github-dark-dimmed"}
mkdir fingerprint-php-quickstart && cd fingerprint-php-quickstart
composer init -n --name="demo/fp-php" --type=project
composer require fingerprint/server-sdk vlucas/phpdotenv
```

Note: This quickstart is written for version 7.x of the Fingerprint PHP SDK.

2. Create a `.env` file to store your Fingerprint secret API key (replace with your actual key):

```bash Terminal theme={"theme":"github-dark-dimmed"}
FINGERPRINT_SECRET_API_KEY=your_secret_key_here
```

3. Create a new file called `index.php` and load your dependencies:

```php index.php theme={"theme":"github-dark-dimmed"}
<?php

require __DIR__ . '/vendor/autoload.php';

use Dotenv\Dotenv;

$dotenv = Dotenv::createImmutable(__DIR__);
$dotenv->load();
```

4. Then create a POST route for `/api/create-account`. For now, this will just return a placeholder message so you can confirm the server is running:

```php index.php theme={"theme":"github-dark-dimmed"}
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

if ($_SERVER['REQUEST_METHOD'] === 'POST' && $path === '/api/create-account') {
    header('Content-Type: application/json');
    echo json_encode(['status' => 'Account created!']);
    exit;
}

http_response_code(404);
header('Content-Type: application/json');
echo json_encode(['error' => 'Not found']);
```

## 3. Initialize Fingerprint and retrieve visitor data

Now you'll configure the Fingerprint PHP Server SDK using your secret API key and use it to fetch detailed visitor data for each signup attempt.

When making the initial visitor identification request in the frontend, you received an event ID. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. Import the Fingerprint PHP Server SDK classes at the top of `index.php` (after your other use statements):

```php index.php theme={"theme":"github-dark-dimmed"}
use Fingerprint\ServerSdk\Api\FingerprintApi;
use Fingerprint\ServerSdk\Configuration;
use Fingerprint\ServerSdk\Model\BotResult;
```

2. Initialize the Fingerprint PHP Server SDK using your secret API key and your [specific workspace region](https://github.com/fingerprintjs/php-sdk/?tab=readme-ov-file#getting-started). (After loading your .env variables):

```php index.php theme={"theme":"github-dark-dimmed"}
$config = new Configuration($_ENV['FINGERPRINT_SECRET_API_KEY'], Configuration::REGION_GLOBAL);
$fp = new FingerprintApi($config);
```

3. In your `/api/create-account route`, retrieve the inputs sent from your frontend and fetch the full visitor identification details with `getEvent()`:

<Note>
  **requestId vs event\_id:** Depending on which quickstart you completed, your frontend may send
  either `requestId` (older SDKs) or `event_id` (v4 and newer). Both refer to the same
  identification event and work with the Server API in the same way. Use whichever value your
  frontend sends (`requestId` or `event_id`) as the event identifier below.
</Note>

```php index.php theme={"theme":"github-dark-dimmed"}
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

if ($_SERVER['REQUEST_METHOD'] === 'POST' && $path === '/api/create-account') {
    header('Content-Type: application/json');

    $input = json_decode(file_get_contents('php://input'), true) ?? [];
    $username  = $input['username']  ?? null;
    $password  = $input['password']  ?? null;
    $eventId = $input['event_id'] ?? null;

    if (!$username || !$password || !$eventId) {
        http_response_code(400);
        echo json_encode(['error' => 'Missing required fields.']);
        exit;
    }

    try {
        // Retrieve full identification details for this request
        $event = $fp->getEvent($eventId);
    } catch (Throwable $e) {
        http_response_code(500);
        error_log("Error retrieving event: " . $e->getMessage());
        echo json_encode(['error' => 'Failed to create account.']);
        exit;
    }

    echo json_encode(['status' => 'Account created!']);
    exit;
}
```

Using the event ID (`event_id`), the Fingerprint server client will retrieve the full data for the visitor identification request. The returned object will contain the visitor ID, IP address, device and browser details, and Smart Signals like bot detection, incognito mode detection, and detections for VPN or virtual machine use.

You can see a full example of the event structure, and test it with your own device, in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 4. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection Smart Signal which is available only on paid plans.
</Note>

A simple but powerful way to prevent fraudulent account creation is to block automated signups that come from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

1. Continuing in your `/api/create-account` route, after the `try/catch` where you fetch the event, extract the bot detection signal and decide whether to allow the signup:

```php index.php theme={"theme":"github-dark-dimmed"}
$botResult = $event->getBot();

// Block automated signups
if ($botResult !== BotResult::NOT_DETECTED) {
    error_log("Account creation blocked: bot detection result = {$botResult}");
    http_response_code(403);
    echo json_encode(['error' => 'Failed to create account.']);
    exit;
}
```

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found. You can also layer in other Smart Signals to catch more suspicious devices. For example, you can use Fingerprint's [Suspect Score](/docs/suspect-score) to determine when to add additional friction to create an account.

## 5. Prevent multiple signups from the same device

To catch repeated signups from the same device, you can use the visitor ID from the Fingerprint identification event. By saving this ID alongside each created account, you can detect and block duplicate signups from the same device. This quickstart uses SQLite because it's a simple database with little setup.

1. Create a file called `setup.php` with the following code to initialize a simple SQLite table:

```php setup.php theme={"theme":"github-dark-dimmed"}
<?php
$db = new PDO('sqlite:database.sqlite');
$db->exec("
CREATE TABLE IF NOT EXISTS accounts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT NOT NULL,
    password TEXT NOT NULL,
    visitorId TEXT NOT NULL
)");
echo "Database ready.";
```

2. Run the script once to create the database file and table:

```bash Terminal theme={"theme":"github-dark-dimmed"}
php setup.php
```

3. In `index.php`, open a SQLite connection after loading your environment variables:

```php index.php theme={"theme":"github-dark-dimmed"}
$db = new PDO('sqlite:database.sqlite');
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
```

4. In your `/api/create-account` route, after the bot check, extract the trusted visitor ID from the event:

```php index.php theme={"theme":"github-dark-dimmed"}
$visitorId = $event->getIdentification()->getVisitorId();
```

5. Check if this device has already created an account:

```php index.php theme={"theme":"github-dark-dimmed"}
$check = $db->prepare("SELECT COUNT(*) FROM accounts WHERE visitorId = ?");
$check->execute([$visitorId]);
$alreadyExists = $check->fetchColumn() > 0;

if ($alreadyExists) {
    http_response_code(429);
    error_log("Account already exists: visitorId = {$visitorId}");
    echo json_encode(['error' => 'Failed to create account.']);
    exit;
}
```

6. Insert the new account with the visitor ID and return success:

```php index.php theme={"theme":"github-dark-dimmed"}
$insert = $db->prepare("INSERT INTO accounts (username, password, visitorId) VALUES (?, ?, ?)");
$insert->execute([$username, $password, $visitorId]);

echo json_encode(['status' => 'Account created!']); // Was already there
exit; // Was already there
```

This gives you a basic system to detect and block repeat signups. You can expand on this by allowing a limited number of accounts per device, adjusting your response based on business rules, only evaluating recent signups, etc.

<Info>
  This is a minimal example to show how to use the Fingerprint PHP Server SDK. In a real
  application, make sure to implement proper security practices, especially around password handling
  and storage.
</Info>

## 6. Test your implementation

Now that everything is set up, you can test the full flow using your existing frontend.

### Before you test

If your frontend is running on a different port (like localhost:5173 or localhost:3000), you may run into CORS issues for testing. To quickly fix this for local development & testing:

1. Add the following at the top of `index.php`, right after your require and use statements:

```php theme={"theme":"github-dark-dimmed"}
header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Methods: POST, OPTIONS");
header("Access-Control-Allow-Headers: Content-Type");

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(204);
    exit;
}
```

### Test the implementation

1. Start your PHP server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
php -S localhost:8000
```

2. In your frontend, trigger a sign-up request that sends the `event_id`, `username`, and `password` to your server's `/api/create-account` endpoint. To see the reply messages make sure to parse and display or console log the response from your server.
3. Within your frontend, input a username and password to create a user. Then try to create another user and see that the second attempt will be rejected.
4. Bonus: Try creating an account using a headless browser.

## Next steps

You now have a working backend fraud check using Fingerprint. From here, you can expand your logic with more Smart Signals, adjust thresholds based on your risk tolerance, or introduce additional checks for suspicious users.

These same techniques apply to a wide range of fraud prevention use cases, from detecting fake reviews to blocking payment abuse or preventing account takeovers.

To go further, check out the use case tutorials for step-by-step guides tailored to specific problems you can solve with Fingerprint.

Check out these related resources:

* [PHP SDK Reference](https://github.com/fingerprintjs/php-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Planning your implementation
Source: https://docs.fingerprint.com/docs/planning-implementation

Key considerations to think through before implementing Fingerprint

Before adding Fingerprint to your platform, it's important to plan how you'll use device intelligence to meet your needs. Fingerprint gives you the data, but you decide how to use it. It's flexible and easy to integrate, but you'll need to figure out where to apply it and what actions to take based on the insights. This guide covers the key steps to consider for a smooth implementation.

## Assess key device intelligence touchpoints

To make the most of Fingerprint, it's important to know where it will be most useful on your platform. Are you focusing on stopping fraud or improving user experiences? Begin by finding the pages or actions on your site that need visitor identification. These are usually places where sensitive actions happen or where it's important to understand user behavior. Common areas include:

* **Entry pages**: Recognize anonymous visitors before they identify themselves, which supports personalization and gives you earlier context on who is using your site or app.
* **Login pages**: Protect against account takeover and credential stuffing by recognizing known visitors without friction while reserving step-up authentication for unfamiliar or suspicious ones.
* **Signup pages**: Catch repeat sign-ups from the same device or automated signups from bots, and block registrations from devices you have already banned.
* **Transactions and checkouts**: Catch payment fraud and card testing at high-value moments, and keep the device record as chargeback evidence.
* **Account updates**: Re-check the device when someone changes a password, email, or payout details.

Decide how you want to treat AI traffic at each of these touchpoints. Fingerprint can [detect AI agents and assistants](/docs/ai-agents) and expose their identity verification status, so you can allow verified agents while applying custom logic to unverified or spoofed traffic.

You will also need to decide when and how often to make identification requests. The general best practice is to [identify on demand](/docs/identify-visitors#timing-identification-requests), when the visitor takes the action you care about, rather than on every page load. For sensitive actions like logins, sign-ups, and payments, always identify visitors in real time, but for lower-risk activities, [caching the visitor ID](/docs/identify-visitors#caching-the-visitor-id) can help to avoid unnecessary API calls. However, frequent identification is important for maintaining accuracy, as it allows small changes in browsers and devices to be noticed over time.

Additionally, consider [common patterns](/docs/introduction#fingerprint-design-patterns) that apply to most sites and might also apply to your environment. These include comparing current and past visitor IDs to check if users are returning. You can also count visitor IDs linked to a single user to detect account sharing or unauthorized access. Another option is to check how many data points, such as account or transaction IDs, the visitor ID links to. Use these patterns to understand where visitor identification fits your platform's needs. An easy way to support these patterns is to link Fingerprint's visitor IDs to identifiers you already have. You can do that within your own data stores or by passing a [linked ID and tags](/docs/tagging-information) with every identification request.

## Establish baselines for visitor behavior

Next, you should analyze your visitor traffic to understand what normal behavior looks like for your platform. You can do this by analyzing your current general analytics data, or by adding Fingerprint to a few key pages and identifying visitors without acting on the results, so you start collecting identification data right away.

For example, is it normal for many devices to access a single account? If so, how many devices is typical? Do most users log in from the same device every time? Knowing these baselines helps you understand what's normal and know when to raise red flags.

The Fingerprint [dashboard](https://dashboard.fingerprint.com/overview) is a quick way to get oriented: the Overview page shows usage and unique visitors, while the [Smart Signals page](https://dashboard.fingerprint.com/smart-signals) shows how often each Smart Signal fires. You can also [export identification events](https://dashboard.fingerprint.com/events) to CSV or use the [Server API](/reference/server-api-search-events) to analyze them in your own tools. For deeper analysis, store identification events in your own systems, alongside the outcomes you already monitor, so you can join them together and look for real patterns.

Consider what device characteristics are more unusual for your users. For instance, if most of your users don't use [VPNs](/docs/smart-signals-reference#vpn-detection-for-browsers) or [incognito mode](/docs/smart-signals-reference#browser-incognito-detection), you may consider those behaviors as risky. Other [signals](/docs/smart-signals-reference) worth checking your traffic against include residential proxies, anti-detect browsers, rare device configurations, and, on mobile, rooted or jailbroken devices and emulators.

One way to evaluate these signals is to use [Suspect Score](/docs/suspect-score), which rolls them into a single risk value. Once you have collected identification data, you can label past identifications with your own fraud outcomes, upload that to the Fingerprint dashboard, and get scoring weights tuned to your traffic, showing which signals actually predict fraud for you.

## Define responses for flagged activity

After you understand what normal and suspicious behavior looks like on your platform, the next step is to decide how to respond. Having a range of responses based on the level of risk helps balance security with user experience.

Based on the data you get from Fingerprint, here are some options:

* **Allow the action**: For visitors with no signs of suspicious behavior, allow the action to proceed without adding extra steps, like MFA. This keeps the experience smooth for legitimate users.
* **Add extra friction**: If something seems off, you can add steps to verify the action. For example, if a user tries to make a purchase from an unfamiliar device, you could send a one-time passcode before completing the transaction.
* **Block the action**: Stop the action completely for high-risk behavior, like a malicious bot trying to change account settings. This helps prevent unauthorized access or fraud.
* **Manual review**: In some use cases, it may make sense to flag the activity for manual review. This allows your team to look into the situation before making a final decision.

## Prepare for data storage and system integrations

When implementing Fingerprint, plan how to store, manage, and integrate the IDs and device signals it provides. Fingerprint only retains visitor history for a limited time, ranging from 30 days to 90 days or longer, depending on your plan. In the dashboard, identification events are available for 3 months, and aggregate statistics are available for 12 months. Decide if this works for you or if you need to store the data longer in your own data storage.

<Note>
  **Staying compliant with data privacy laws**

  When storing identification data, make sure to consider your business needs as well as data regulations like GDPR, CCPA, and other applicable laws. Your workspace region is chosen when you create your workspace and cannot be changed later, so confirm which region you need before you set one up.

  Beyond storage, consider user consent requirements. Consent isn't always required for [legitimate interests](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/legal-grounds-processing-data_en#legitimate-interests-of-the-controller:~:text=A%20company/organisation%20may,of%20its%20IT%20systems.), such as fraud prevention, but it may be required for use cases like personalization. To [stay compliant](/docs/privacy-and-compliance), be sure to follow user consent and [data residency](/docs/regions) rules.
</Note>

Decide up front how you will measure whether Fingerprint is working, so you can tell what to adjust later. Set clear metrics, like the number of account takeovers prevented or fraudulent purchases stopped. Tie those to business impact where you can, such as the revenue recovered from fewer false positives or the support hours saved. Review these metrics often to adjust your logic and rules. For more guidance on ways to analyze Fingerprint data and outcomes, see Test 3 from [How to evaluate fingerprinting accuracy in the real world](https://fingerprint.com/blog/evaluate-fingerprinting-accuracy/).

Consider how Fingerprint data will fit into other systems. This might mean [sending device signals to your Web Application Firewalls (WAFs)](https://fingerprint.com/blog/bot-detection-powered-application-firewall/) or fraud detection models. Look for areas where Fingerprint can improve security or enhance the user experience. If your team investigates fraud by hand, the [MCP server](/docs/mcp-server) connects your identification data to AI assistants, enabling them to query event data and investigate suspicious activity in natural language.

## Map out installation and API usage

A quick way to get started is the [Fingerprint CLI](https://github.com/fingerprintjs/fingerprint-cli). Run `npx fingerprint` from your project root, and it will sign you in, detect your frontend and backend frameworks, provision your API keys, and write the integration into your code one step at a time.

To integrate manually, add the [JavaScript agent](/reference/js-agent) to your website's frontend code, either through the CDN or an [SDK for your framework](/docs/web-quickstarts-overview). For mobile apps, there are [SDKs](/docs/mobile-sdks) covering both native apps and multi-platform frameworks. From there, choose how to safely get Fingerprint results to your server: the [Server API](/reference/server-api), [Sealed Client Results](/docs/sealed-client-results), or [Webhooks](/docs/webhooks).

The Server API can be accessed directly or through one of the [backend SDKs](/docs/server-quickstarts-overview). Requests should be made from a backend server that can securely store and access secret keys.

With Sealed Client Results, you get a fully encrypted response payload from the JavaScript agent or mobile SDKs. This payload contains the same data available through the Server API, so you can skip the extra API call and decrypt it on your backend to reduce latency.

Fingerprint can also send you identification data using webhooks. If you choose this option, you'll need to create an endpoint on your server to receive and handle these webhook events. Webhooks provide a great way to store the full historical record of your event data.

You should also decide where your response logic lives. You can choose to write it directly in your application code, or you can use the [Rules Engine](/docs/rules-engine). The Rules Engine lets you define rules in the dashboard and returns a rule action for each identification event, so your fraud team can adjust them as needed without waiting for a code change. The Rules Engine decides the outcome, but your application applies it.

If your site runs on Cloudflare, [Flow](/docs/flow-deployments) goes a step further by deploying a worker that handles the identification setup described above, with little to no changes to your application code. You can pair it with a ruleset to enforce your rules at the edge, or run it on its own to collect identification data without taking any action.

### Choose an ad blocker evasion strategy

To ensure you can properly identify all visitors to your site, it's important to [prevent ad blockers from blocking identification requests](/docs/protecting-the-javascript-agent-from-adblockers). You can set up a custom subdomain pointing to Fingerprint's infrastructure to reduce request blocking. You can also use one of the available cloud proxy integrations for [Cloudflare](/docs/cloudflare-integration), [Akamai](/docs/akamai-proxy-integration), [CloudFront](/docs/cloudfront-proxy-integration-v2), and [other cloud providers](/docs/protecting-the-javascript-agent-from-adblockers#cloud-proxy-integrations). Both methods protect identification requests from getting blocked by proxying them through your own domain.

## Getting started

Ready to get started now that you've planned out your implementation? Fingerprint support is [here to help you](https://fingerprint.com/support/) take the next step. Get started with identifying [browsers](/docs/install-the-javascript-agent) and [mobile devices](/docs/mobile-identification), or explore the [demos](https://demo.fingerprint.com/) to see Fingerprint in action. You can also review the [use case tutorials](/docs/use-case-tutorials-overview) for step-by-step implementations of common fraud scenarios. Here are a few to help you hit the ground running:

* [Account takeover](/docs/account-takeover-use-case-tutorial)
* [Chargeback dispute](/docs/chargeback-dispute-use-case-tutorial)
* [Web scraping](/docs/web-scraping-use-case-tutorial)


# Playground
Source: https://docs.fingerprint.com/docs/playground





# Preact
Source: https://docs.fingerprint.com/docs/preact



The [Fingerprint React SDK](https://github.com/fingerprintjs/react) is an easy way to integrate Fingerprint into your Preact application. It supports all capabilities of the JavaScript agent and provides a built-in caching mechanism. You can view our [React quickstart](/docs/react-quickstart) for a step-by-step guide to get started.

### How to install

Add `@fingerprint/react` as a dependency to your application via npm or yarn.

<CodeGroup>
  ```shell NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/react
  ```

  ```shell Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/react
  ```

  ```shell PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/react
  ```
</CodeGroup>

Wrap your application (or component) in `FingerprintProvider`. You need to specify your public API key and other configuration options based on your chosen region and active integration.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// src/components/app.js
import { FingerprintProvider } from '@fingerprint/react';
import Home from '../routes/home';

export default function Wrapper() {
  return (
    <FingerprintProvider apiKey="PUBLIC_API_KEY" endpoints="https://metrics.yourwebsite.com">
      <Home />
    </FingerprintProvider>
  );
}
```

Use the `useVisitorData` hook in your components to identify visitors.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// src/routes/home/index.js
import { useVisitorData } from '@fingerprint/react';

export default function Home() {
  const { isLoading, error, data, getData } = useVisitorData({ immediate: true });

  return (
    <div id="preact_root">
      <button onClick={() => getData()}>Reload data</button>
      <p>Visitor ID: {isLoading ? 'Loading...' : data?.visitor_id}</p>
      <p>Full visitor data:</p>
      <pre>{error ? error.message : JSON.stringify(data, null, 2)}</pre>
    </div>
  );
}
```

> Note: The Fingerprint React SDK is available as an NPM package. If you are using Preact without a build tool, you can [use the JavaScript agent directly](/reference/js-agent) by importing it from our CDN.

### Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/react). The repository also contains [an example app](https://github.com/fingerprintjs/react/tree/main/examples/preact) demonstrating usage of the library.

### Migration guide for React SDK v3.0.0

You can find the migration guide on the [React SDK page](/docs/react).


# Preact Quickstart
Source: https://docs.fingerprint.com/docs/preact-quickstart

Get started using the Fingerprint React SDK with Preact

## Overview

In this quickstart, you'll add Fingerprint to a new [Preact](https://preactjs.com/) project and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend integration. You'll install the [Fingerprint React SDK](/docs/react) (which works with Preact) and initialize the JavaScript agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of [Preact](https://preactjs.com/) and JavaScript

<Note>
  This quickstart only covers the **frontend setup**. You'll need a [backend
  server](/reference/server-sdks) to receive and process the device identification event to enable
  fraud detection. Check out one of the [backend quickstarts](/docs/server-quickstarts-overview)
  after completing this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the JavaScript agent.

## 2. Set up your project

To get started, scaffold a new Preact app. If you already have a project you want to use, you can skip to the next section.

1. Create a new Vite project with the Preact template:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm create vite@latest fingerprint-preact-quickstart -- --template preact
cd fingerprint-preact-quickstart
npm install
```

2. Open the `fingerprint-preact-quickstart` folder in your code editor and you're ready to go! To run your project, run:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

3. In your browser, go to [http://localhost:5173](http://localhost:5173/) (Vite's default), and you should see the Vite welcome page.

## 3. Set up your account creation form

1. Before adding Fingerprint, create a new component at `src/components/CreateAccountForm.jsx` with the following:

```jsx src/components/CreateAccountForm.jsx theme={"theme":"github-dark-dimmed"}
import { useState } from "preact/hooks";

export default function CreateAccountForm(props) {
  const [username, setUsername] = useState("");
  const [password, setPassword] = useState("");
  return (
    <div className="wrapper">
      <h1>Create an account</h1>
      <div className="input-group">
        <label htmlFor="username">Username</label>
        <input
          id="username"
          value={username}
          onChange={(e) => setUsername(e.target.value)}
          type="text"
          placeholder="Username"
          required
        />
      </div>
      <div className="input-group">
        <label htmlFor="password">Password</label>
        <input
          id="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          type="password"
          placeholder="Password"
          required
        />
      </div>
      <button disabled={props.isLoading} onClick={props.handleSubmit}>
        {props.isLoading ? "Loading…" : "Create Account"}
      </button>
    </div>
  );
}
```

2. Open `src/app.css` and add these classes to the end of the file:

```css src/app.css theme={"theme":"github-dark-dimmed"}
.wrapper {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  min-height: 100vh;
  gap: 1rem;
  padding: 1rem;
}

input {
  width: 100%;
  padding: 0.5rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}

.input-group {
  width: 100%;
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 0.5rem;
}

button {
  background-color: #f35b22;
  color: #fff;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 4px;
  cursor: pointer;
}

button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
```

3. Import and add the component to your App component in `src/app.jsx`. The entire file can be replaced with this:

```jsx src/app.jsx theme={"theme":"github-dark-dimmed"}
import "./app.css";
import CreateAccountForm from "./components/CreateAccountForm";

export function App() {
  return (
    <>
      <CreateAccountForm />
    </>
  );
}
```

## 4. Install and initialize the JavaScript agent

1. To integrate Fingerprint into your Preact app, add the Fingerprint React SDK via npm. The React SDK is compatible with Preact:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/react
```

*Note: This quickstart is written for version 3.x of the Fingerprint React SDK*

2. Now that the React SDK is installed, import and initialize the Fingerprint provider in your app's entry point. Open `src/main.jsx` and add:

```jsx src/main.jsx theme={"theme":"github-dark-dimmed"}
import { FingerprintProvider } from "@fingerprint/react";
```

3. Wrap `<App />` with the FingerprintProvider component:

```jsx src/main.jsx theme={"theme":"github-dark-dimmed"}
render(
  // [!code ++:5]
  <FingerprintProvider
    apiKey="PUBLIC_API_KEY"
    region="us" // Ensure this matches your workspace region
    // For more information, see https://docs.fingerprint.com/docs/regions
  >
    <App />
  </FingerprintProvider>, // [!code ++]
  document.getElementById("app"),
);
```

4. Replace `PUBLIC_API_KEY` with your public API key from the [Fingerprint dashboard](https://dashboard.fingerprint.com/api-keys).

*Note: For production, consider using* *[Vite Env Variables](https://vite.dev/guide/env-and-mode)* *to configure the key.*

## 5. Trigger visitor identification

Now that the JavaScript agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps the **Create Account** button.

When making the visitor identification request, you will receive the `visitor_id` as well as an `event_id`. Instead of using the `visitor_id` returned directly on the frontend (which could be tampered with), you'll send the `event_id` to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. In `app.jsx`, import Fingerprint's `useVisitorData` hook:

```jsx src/app.jsx theme={"theme":"github-dark-dimmed"}
import "./app.css";
import CreateAccountForm from "./components/CreateAccountForm";
import { useVisitorData } from "@fingerprint/react"; // [!code ++]
```

2. Inside the `App` component, use Fingerprint's `useVisitorData` hook to obtain visitor data. The hook is configured here to defer identification until you call it, and it returns the state you'll need:

```jsx src/app.jsx theme={"theme":"github-dark-dimmed"}
function App() {
  const { getData, isLoading } = useVisitorData({ immediate: false }); // [!code ++]

  return (
    <>
      <CreateAccountForm />
    </>
  );
}
```

This gives you:

* `getData()`: A function to trigger visitor identification on demand.
* `isLoading`: A flag to monitor visitor identification progress.

By setting immediate to false you're triggering device identification only when needed with the `getData()` method.

*Check our* *[GitHub repo](https://github.com/fingerprintjs/react)* *for available useVisitorData options.*

3. Straight after the hook, define the submit handler to trigger identification when the user clicks **Create Account**:

```jsx src/app.jsx theme={"theme":"github-dark-dimmed"}
function App() {
  const { getData, isLoading } = useVisitorData({ immediate: false });

  // [!code ++:5]
  async function handleSubmit() {
    const { visitor_id, event_id } = await getData();

    console.log("Visitor ID:", visitor_id);
    console.log("Event ID:", event_id);

    // Example of how you could send the event_id and form data to your server:
    // await fetch("http://localhost:3000/api/create-account", {
    //   method: "POST",
    //   headers: { "Content-Type": "application/json" },
    //   body: JSON.stringify({
    //     username: username.value,
    //     password: password.value,
    //     event_id,
    //   }),
    // });
  } // [!code ++]

  return (
    <>
      <CreateAccountForm />
    </>
  );
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

In this function, `getData()` is being called and Fingerprint is analyzing the visitor's browser. The result of the identification will include an `event_id`, which you can then send to your backend along with the username and password for your fraud detection logic.

4. Pass the `isLoading` and `handleSubmit` props to `CreateAccountForm`:

```jsx src/app.jsx theme={"theme":"github-dark-dimmed"}
<CreateAccountForm isLoading={isLoading} handleSubmit={handleSubmit} />
```

## 6. Test the app

1. If your dev server isn't already running, start it with:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. In your browser, go to [http://localhost:5173](http://localhost:5173/) (Vite's default).
3. If you have any ad blockers, turn them off for localhost. View the [documentation](/docs/protecting-the-javascript-agent-from-adblockers) to learn how to protect your Fingerprint implementation from ad blockers in production.
4. Enter a username and password, then click **Create Account**.
5. Open the developer console in your browser and you should see the visitor ID and event ID in the output:

```text Output theme={"theme":"github-dark-dimmed"}
Visitor ID: JkLmNoPqRsTuVwXyZaBc
Event ID: 1234566477745.abc1GS
```

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the `event_id` to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information data and use it to make decisions and prevent fraud.

Check out these related resources:

* [React SDK reference](https://github.com/fingerprintjs/react) (includes Preact support)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Privacy and compliance
Source: https://docs.fingerprint.com/docs/privacy-and-compliance

Overview of Fingerprint's regulatory compliance and how we ensure secure and responsible visitor identification.

## Is Fingerprint GDPR compliant?

[FingerprintJS](https://github.com/fingerprintjs/fingerprintjs/), our open-source library, is GDPR compliant because it is stateless and doesn't store any data. It's a JavaScript function that generates a hash from only publicly available browser information. However, depending on how you use FingerprintJS data, you may need user consent, which is outside the scope of this guide.

[Fingerprint Identification](https://fingerprint.com/products/fingerprint-pro/) (our commercial product) is also GDPR compliant, but it’s important to understand the details behind it.

### Data controller vs data processor

Fingerprint Identification is a SaaS product offered as a client-server API system. Under GDPR, there are two roles: “data controllers” and “data processors.” A data controller is a website or app that decides to collect and store user data. A data processor is a third-party service that receives, stores, and processes data from the controller.

Examples of data controllers are sites like eBay, Wikipedia, and YouTube. Data processors include services like DigitalOcean, AWS, and Google Cloud.

Fingerprint Identification is a data processor, while a website using its API is a data controller. For example, Dropbox uses Fingerprint Identification to prevent account abuse and improve security. Dropbox is the data controller, and Fingerprint is the data processor.

As a data controller, Dropbox must follow GDPR rules and collect and use the data correctly according to GDPR guidelines.

As a data processor, Fingerprints must also follow GDPR and handle the data it **gets from data controllers** correctly, according to GDPR guidelines.

### What obligations does Fingerprint have as a data processor?

Fingerprint must delete personal information it receives from a data controller when requested. See [Data Deletion](/docs/regions#data-deletion) for more information.

### Do I need to have a GDPR consent management banner if using Fingerprint?

It depends on your use case and how you are using Fingerprint:

* **Attribution and personalization:** If you use Fingerprint for things like attribution or personalization, you’ll likely need to get user consent, similar to how you handle cookies.
* **Fraud prevention and security:** If you use Fingerprint for fraud prevention, this usually falls under “Legitimate interest” according to GDPR, so explicit user consent isn’t needed. You can check the [European Commission’s definition of legitimate interest](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/legal-grounds-processing-data_en#legitimate-interests-of-the-controller:~:text=A%20company/organisation%20may,of%20its%20IT%20systems.) for more details.

### If I do need user consent before identifying visitors, how do I implement it?

Instead of identifying visitors automatically on page load, you can choose to explicitly trigger the Fingerprint identification request only in specific circumstances. For example, only after the visitor grants consent by clicking "Accept" on a cookie consent banner.

The Fingerprint JavaScript agent only stores cookies and other metadata in the browser during the identification request. See [Timing identification requests](/docs/identify-visitors#timing-identification-requests) for more information.

### What about US Privacy Law (including CCPA) compliance?

When using Fingerprint, you are responsible for US Privacy Law compliance as the business, and Fingerprint acts as a Service Provider, processing Personal Information only as needed to provide the service. We do not sell or share data outside the scope of our agreement. You must inform consumers about data processing and handle consumer rights requests. Fingerprint supports compliance by helping with data deletion and protection. For more details, see our [US SPL Data Processing Addendum](https://docs.fingerprint.com/docs/dpa-usspl).

## Can you use Fingerprint to track visitors across the internet?

No, Fingerprint is primarily designed for fraud prevention in the same-site context. The visitor ID is scoped to each Fingerprint workspace, not the internet at large. If two Fingerprint customers identify the same browser or device, they will receive different visitor IDs. This intentionally makes Fingerprint unsuitable for creating a global visitor activity graph across *unrelated* sites as you might do with third-party cookies.

## Can you use Fingerprint for marketing attribution?

Yes, you can use Fingerprint for marketing attribution and personalization *in the context of your business*. It works well for identifying visitors on the same website, or multiple websites you control, even across domains.

For example, you can use Fingerprint to link a purchase to an email campaign or observe user interactions across your landing page and web application.

## Can you identify visitors across multiple domains you own?

Yes, you can generate the same visitor ID for the same browser or device on multiple domains you control. To do so, configure the JavaScript agent on each website with a public API key from the *same* Fingerprint workspace.

If you need to query the Fingerprint Server API by domain name, you can use [linked IDs](/reference/js-agent-get-function#linkedid) to associate a domain with each identification event. To ensure maximum accuracy when using [proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers), each website needs to proxy requests through its own domain or subdomain.


# Overview
Source: https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers



The [Fingerprint JavaScript agent](/reference/js-agent) and mobile SDKs collect device attributes and identify visitors by making HTTP network requests to Fingerprint servers. In the browser, ad blockers and privacy-focused browsers can block JavaScript agent requests, and VPN or DNS-level blocking can affect requests from both the browser and mobile SDKs, preventing you from identifying all of your visitors.

In this article, we will explain how to protect Fingerprint requests from being blocked by proxying them through your own domain.

## Which requests are blocked and how?

<img alt="Blocked requests" />

Client agents — the JavaScript agent on your website and mobile SDKs in your apps — make various requests to Fingerprint servers:

* The JavaScript agent downloads the most recent device intelligence algorithm from our CDN (even if you installed it using an NPM library).
* Client agents send the collected device attributes to our Identification API and receive the visitor ID in return.
* Client agents can make additional requests to improve the accuracy of identification.

Ad blockers like *Adblock* or *uBlock Origin* and privacy-focused browsers like *Brave* block JavaScript agent requests in the browser. They keep track of Fingerprint domains hosting our APIs (for example, `fpjscdn.net`, `api.fpjs.io`, `fptls.com`) and block all requests matching those domains. Some VPN providers can also block our domains on a DNS level, affecting both browser and mobile traffic.

You can examine blocked JavaScript agent requests from your browser's developer tools (in the *Console* or *Network* tab). The error will usually show up as `net::ERR_BLOCKED_BY_CLIENT` or `Failed to load the JS script of the agent`.

<img alt="Blocked requests" />

## Proxying requests through your domain

The best way to protect Fingerprint requests from getting blocked is to proxy them through your own domain. Instead of calling Fingerprint APIs directly, the JavaScript agent or the mobile SDK calls a proxy function hosted on your own domain or subdomain — for example, `metrics.yourwebsite.com` — which then passes the request to the Fingerprint API.

<img alt="Proxying requests through your domain" />

The requests are now happening within the same site which means:

* The requests are not blocked by ad blockers.
* Cookies created by the request are considered "first-party". They can be saved in the visitor's browser in situations where third-party cookies are blocked (for example, Safari blocks all third-party cookies). They can also live longer (in some browsers) than cookies not routed through your domain.
* Your usage of Fingerprint is harder to detect for fraudsters and bad actors.

This increases both the effectiveness and accuracy of visitor identification.

There are two options for proxying requests:

* *Custom subdomain setup*: The proxy function runs on Fingerprint infrastructure and you just point your subdomain to it.
* *Cloud proxy integrations*: The proxy function runs in your cloud infrastructure.

## Custom subdomain setup

Using [Custom subdomain setup](/docs/custom-subdomain-setup) is required to avoid ad blockers and maximize identification coverage of your visitors. It is available and highly recommended to all Fingerprint customers.

The setup is largely automated. It consists of:

1. Registering your subdomain inside the Fingerprint dashboard.
2. Adjusting your DNS records to point your subdomain to a proxy function running inside Fingerprint infrastructure.
3. Adjusting your Fingerprint client configuration (JavaScript agent or mobile SDK) to use your subdomain.

One limitation of proxying requests through a subdomain instead of the main domain is that cookie lifetimes in Safari 16.4 or higher are [reduced to 7 days](#preserving-first-party-context). To achieve the maximum possible accuracy, consider using one of our cloud proxy integrations.

## Cloud proxy integrations

Setting up a cloud proxy integration typically involves deploying a Fingerprint-provided proxy function in your cloud infrastructure. Cloud proxy integrations have all the accuracy and coverage benefits of a Custom subdomain setup. Additional benefits include:

* Cookie lifetime of up to one year ([instead of 7 days](#preserving-first-party-context)) even in Safari 16.4 and higher, leading to maximum possible accuracy in all browsers.
* Insight and control over the identification requests in your own infrastructure. You can extend the provided proxy functionality with other services offered by your cloud provider, such as WAF, logging, and analytics.
* Cookie security: Both custom subdomain setup and cloud proxy integrations drop all the cookies sent from the origin website. With cloud proxy integrations, the proxy function code is open-source so this behavior can be transparently verified and audited.
* IPv6 support: Fingerprint Identification API only supports IPv4, but proxy integrations also support IPv6. Using a proxy integration, the JavaScript agent can use IPv6 to send identification requests.
* You can manage unlimited subdomains and paths and provide Fingerprint services to all your customers at any scale while benefiting from all the 1st-party integration improvements.
* Easy to meet compliance and auditing requirements.

At present, we provide and support the following cloud proxy integrations:

| Integration                                                                | Required plan | Setup                                             |
| :------------------------------------------------------------------------- | :------------ | :------------------------------------------------ |
| [Cloudflare Proxy Integration](/docs/cloudflare-integration)               | Any Plan      | Dashboard installation wizard — largely automated |
| [AWS CloudFront Proxy Integration](/docs/cloudfront-proxy-integration-v2)  | Enterprise    | Integration guide — manual steps required         |
| [Azure FrontDoor Proxy Integration](/docs/azure-proxy-integration)         | Enterprise    | Integration guide — manual steps required         |
| [Akamai Proxy Integration](/docs/akamai-proxy-integration)                 | Enterprise    | Integration guide — manual steps required         |
| [Fastly VCL Proxy Integration](/docs/fastly-vcl-proxy-integration)         | Enterprise    | Integration guide — manual steps required         |
| [Fastly Compute Proxy Integration](/docs/fastly-compute-proxy-integration) | Enterprise    | Integration guide — manual steps required         |

If you have questions about setting up a custom subdomain or using one of our proxy integrations, please do not hesitate to [contact our support team](https://fingerprint.com/support/).

### Preserving first-party context

Cookies and other deterministic identification methods [work better](https://developer.mozilla.org/en-US/blog/goodbye-third-party-cookies/) when used within the same website (first-party context) than when used across different websites (third-party context). To achieve maximum accuracy, use your cloud proxy integration in a first-party context.

#### Host the proxy integration on the same domain as your website

If you want to identify visitors on `dogs.com`, your proxy integration should be available on the same [registrable domain](https://developer.mozilla.org/en-US/docs/Glossary/eTLD) or its subdomain, for example `dogs.com/metrics` or `metrics.dogs.com`.

Proxying identification requests from `dogs.com` through a proxy integration hosted on `metrics.cats.com` will result in shorter cookie lifetimes and reduced accuracy.

#### Host the proxy integration on the same IP range as your website

While not technically required, we recommend hosting your proxy integration on the same cloud provider as your website to achieve the maximum possible identification accuracy in Safari.

* Safari 16.4 and higher checks the IP addresses behind your website and proxy integration.
* If they are too different, [it limits cookie lifetimes to 7 days](https://github.com/WebKit/WebKit/pull/5347).

Hosting your website and proxy integration on the same cloud provider (for example, the same Cloudflare site or the same CloudFront distribution) ensures they are in the same IP range and considered first-party by Safari.

## Additional resources

* If you have a Content Security Policy (CSP) enabled on your website, then the CSP can also block requests from the JavaScript agent. See [Content Security Policy (CSP)](/docs/js-agent-csp).
* Safari browsers implement several measures to protect users from being tracked and these measures negatively impact identification accuracy. The negative impact can largely be reduced by setting up a proxy integration. For more information, please see [Safari's Intelligent Tracking Prevention](/docs/browser-and-device-support).
* Blog: [How can ad blockers be used for browser fingerprinting?](https://fingerprint.com/blog/ad-blocker-fingerprinting/)


# Python Server Quickstart
Source: https://docs.fingerprint.com/docs/python-server-quickstart

Get started using the Python Server SDK

## Overview

In this quickstart, you'll add Fingerprint to a [Python](https://www.python.org/) backend using the web framework [FastAPI](https://fastapi.tiangolo.com/) to prevent fraudulent account creation.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. You can flag and block suspicious users by identifying the device behind each sign-up attempt, login, or transaction.

In this quickstart, you'll learn how to:

* Set up a FastAPI server with a Fingerprint integration
* Retrieve visitor identification data using the Server API
* Block bots and suspicious devices
* Prevent multiple signups from the same device

This guide focuses on the backend integration and must be completed after identifying a visitor and generating an event ID. **Before starting this quickstart, start with one of the [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview) quickstarts to see how to identify a visitor in your frontend.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* A completed frontend or mobile Fingerprint implementation **(See the quickstarts)**
* [Python](https://www.python.org/) (3.8 or later) installed
* Your favorite code editor
* Basic knowledge of Python

## 1. Get your secret API key

<Note>
  Before starting this quickstart, you should already have a frontend Fingerprint implementation
  that sends the `event_id` to your server. If not, pause here and check out one of the
  [frontend](/docs/web-quickstarts-overview) or [mobile](/docs/mobile-quickstarts-overview)
  quickstarts first.
</Note>

If you're ready:

1. Sign in and go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the Fingerprint dashboard.
2. Create a new **secret API key**.
3. Copy it somewhere safe so you can use it to retrieve full visitor identification data from the Server API.

## 2. Set up your project

To get started, set up a basic server. If you already have a project you want to use, you can skip to the next section.

1. Create a new Python project and set up the virtual environment:

```bash Terminal theme={"theme":"github-dark-dimmed"}
mkdir fingerprint-python-starter && cd fingerprint-python-starter
python -m venv venv
source venv/bin/activate  # On Windows: venv\\Scripts\\activate
```

2. Create a `requirements.txt` file with the dependencies:

```txt requirements.txt theme={"theme":"github-dark-dimmed"}
fastapi==0.115.6
uvicorn[standard]==0.32.1
python-multipart==0.0.20
pydantic==2.10.4
python-dotenv==1.0.1
fingerprint-server-sdk==9.7.1
```

3. Install dependencies from the requirements.txt file:

```bash Terminal theme={"theme":"github-dark-dimmed"}
pip install -r requirements.txt
```

*Note: This quickstart is written for version 9.x of the Fingerprint Python Server SDK*

4. Create a new file called `server.py` and add a basic FastAPI server setup:

```python server.py theme={"theme":"github-dark-dimmed"}
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Add CORS middleware for local development
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # In production, specify your frontend domain
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.post("/api/create-account")
async def create_account():
    # We'll add Fingerprint logic here
    return {"status": "ok"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=3000)
```

Here we are running the server at port 3000 and have created a new POST route for account creation. Note that the `/api/create-account` route should match what you have set up in your frontend implementation where you are sending the Fingerprint `event_id` to your server. Your server will receive the initial identification information from identifying a visitor on the frontend and use it to get the full visitor data on the backend.

## 3. Initialize Fingerprint and retrieve visitor data

Now you'll configure the [Fingerprint Python Server SDK](/reference/python-server-sdk) using your secret API key and use it to fetch detailed visitor data for each signup attempt.

When making the initial visitor identification request in the frontend, you received an `event_id`. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) and retrieve the complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. Create a `.env` file in your project root and add your secret API key:

```env .env theme={"theme":"github-dark-dimmed"}
FINGERPRINT_API_KEY=your-secret-api-key-here
```

2. At the top of your `server.py` file, import and initialize the Fingerprint Python Server SDK:

```python server.py theme={"theme":"github-dark-dimmed"}
import os
from dotenv import load_dotenv
import fingerprint_server_sdk
from fingerprint_server_sdk.configuration import Region

# Load environment variables from .env file
load_dotenv()

# Get API key from environment variable
api_key = os.getenv("FINGERPRINT_API_KEY")
if not api_key:
    raise ValueError("FINGERPRINT_API_KEY environment variable is required")

# Initialize Fingerprint client with your Fingerprint workspace region
# Available regions: Region.US (default), Region.EU, Region.AP
configuration = fingerprint_server_sdk.Configuration(api_key=api_key, region=Region.EU)
client = fingerprint_server_sdk.FingerprintApi(configuration)
```

3. In your `/api/create-account` route, use the `event_id` you are sending from the frontend to fetch the full visitor identification details:

<Note>
  **requestId vs event\_id:** Depending on which quickstart you completed, your frontend may send
  either `requestId` (older SDKs) or `event_id` (v4 and newer). Both refer to the same
  identification event and work with the Server API in the same way. Use whichever value your
  frontend sends (`requestId` or `event_id`) as the event identifier below.
</Note>

```python server.py theme={"theme":"github-dark-dimmed"}
@app.post("/api/create-account")
async def create_account(request: dict):
    # Get the full visitor identification details using the event_id
    event = client.get_event(request["event_id"])

    # ...
```

Using the `event_id` the Fingerprint server client will retrieve the full data for the visitor identification request. The returned object will contain the visitor ID, IP address, device and browser details, and Smart Signals like bot detection, incognito mode detection, and detections for VPN or virtual machine use.

You can see a full example of the event structure, and test it with your own device, in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 4. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection Smart Signal which is available only on paid plans.
</Note>

A simple but powerful way to prevent fraudulent account creation is to block automated signups that come from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

1. Continuing in your `/api/create-account` route, check the bot signal returned in the `event` object:

```python server.py theme={"theme":"github-dark-dimmed"}
    # Check for bot activity
    from fingerprint_server_sdk import BotResult
    bot = event.bot
    if bot != BotResult.NOT_DETECTED:
        print(f"BOT DETECTED: Bot result '{bot}'")
        raise HTTPException(status_code=403, detail="Request blocked")
```

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found. You can also layer in other Smart Signals to catch more suspicious devices. For example, you can use Fingerprint's [Suspect Score](/docs/suspect-score) to determine when to add additional friction to create an account.

## 5. Prevent multiple signups from the same device

To catch repeated signups from the same device, you can use the visitor ID from the Fingerprint identification event. By saving this ID alongside each created account, you can detect and block duplicate signups. We'll be using a simple database to demonstrate how this works with SQLite.

1. At the top of your `server.py` file, import and initialize the database:

```python server.py theme={"theme":"github-dark-dimmed"}
import sqlite3

# Initialize SQLite database
def init_database():
    conn = sqlite3.connect("database.db")
    cursor = conn.cursor()
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS accounts (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            username TEXT,
            password TEXT,
            visitorId TEXT
        )
    """)
    conn.commit()
    conn.close()

# Initialize database on startup
init_database()
```

2. In your `/api/create-account` route handler, after getting the event, extract the `visitorId`:

```python server.py theme={"theme":"github-dark-dimmed"}
    # Extract visitor ID
    visitor_id = None
    if event.identification:
        visitor_id = event.identification.visitor_id
```

3. Check if this device has already created an account; if yes, block the account creation:

```python server.py theme={"theme":"github-dark-dimmed"}
    # Check if this device has already created an account
    conn = sqlite3.connect("database.db")
    cursor = conn.cursor()

    cursor.execute(
        "SELECT COUNT(*) as count FROM accounts WHERE visitorId = ?",
        (visitor_id,)
    )
    row = cursor.fetchone()

    if row[0] > 0:
        conn.close()
        print(f"DUPLICATE ACCOUNT: Visitor {visitor_id} already has an account")
        raise HTTPException(status_code=403, detail="Request blocked")

    # Otherwise, insert the new account
    cursor.execute(
        "INSERT INTO accounts (username, password, visitorId) VALUES (?, ?, ?)",
        (request["username"], request["password"], visitor_id)
    )
    conn.commit()
    conn.close()
```

This gives you a basic system to detect and block repeat signups. You can expand on this by allowing a limited number of accounts per device, adjusting your response based on business rules, only evaluating recent signups, etc.

<Info>
  This is a minimal example to show how to use the Fingerprint Python Server SDK. In a real
  application, make sure to implement proper security practices, especially around password handling
  and storage.
</Info>

## 6. Test your implementation

Now that everything is set up, you can test the full flow using your existing frontend.

### Test the implementation

1. Start your FastAPI server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
python server.py
```

2. In your frontend, trigger a sign-up request that sends the `event_id`, `username`, and `password` to your `/api/create-account` endpoint. To see the reply messages make sure to parse and display or console log the response from your server.
3. Within your frontend, input a username and password to create a user. Then try to create another user and see that the second attempt will be rejected.
4. Bonus: Try creating an account using a headless browser.

## Next steps

You now have a working backend fraud check using Fingerprint. From here, you can expand your logic with more Smart Signals, adjust thresholds based on your risk tolerance, or introduce additional checks for suspicious users.

These same techniques apply to a wide range of fraud prevention use cases, from detecting fake reviews to blocking payment abuse or preventing account takeovers.

To go further, check out the use case tutorials for step-by-step guides tailored to specific problems you can solve with Fingerprint.

Check out these related resources:

* [Python SDK Reference](https://github.com/fingerprintjs/python-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Quick Start Guide
Source: https://docs.fingerprint.com/docs/quick-start-guide

How to quickly add Fingerprint device intelligence to your website or mobile app.

## Install Fingerprint

<Steps>
  <Step title="Create an account">
    [Sign up for a free trial](https://dashboard.fingerprint.com/signup?utm_source=/docs/quick-start-guide) to get your API key, no credit card is required.

    <Accordion title="Having trouble accessing the Dashboard?">
      Please make sure the following domains are allowed in your firewall:

      * `https://fingerprint.com`
      * `https://*.fingerprint.com`
      * `https://api.fpjs.pro`
    </Accordion>
  </Step>

  <Step title="Get your API Key">
    In the Dashboard, go to [API keys > Public](https://dashboard.fingerprint.com/api-keys) from the sidebar and copy your public API key to run the examples below.
  </Step>

  <Step title="Add the client-side agent">
    You can [add the JavaScript agent](/docs/install-the-javascript-agent) to your website or add a native SDK to your [iOS](/docs/ios) or [Android](/docs/native-android-integration) app. The agent collects browser or device attributes, sends them to the Fingerprint backend, and receives a `visitor_id` for that browser or mobile device.

    Let's start with JavaScript. You can install the agent using a package manager or our CDN.

    <CodeGroup>
      ```shell NPM theme={"theme":"github-dark-dimmed"}
      npm install @fingerprint/agent
      ```

      ```shell yarn theme={"theme":"github-dark-dimmed"}
      yarn add @fingerprint/agent
      ```

      ```shell PNPM theme={"theme":"github-dark-dimmed"}
      pnpm add @fingerprint/agent
      ```
    </CodeGroup>

    <CodeGroup>
      ```ts HTML theme={"theme":"github-dark-dimmed"}
      <script>
        // Initialize the agent at application startup.
        // Some ad blockers or browsers will block Fingerprint CDN URL.
        // To fix this, use a custom subdomain or a proxy integration.
        // (see info box below)
        const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY')
          .then(Fingerprint => Fingerprint.start({ region: "us" }));

        // Get the visitor identifier when you need it.
        fpPromise
          .then(fp => fp.get())
          .then(result => console.log(result.event_id, result.visitor_id));
      </script>
      ```

      ```javascript NPM theme={"theme":"github-dark-dimmed"}
      import Fingerprint from '@fingerprint/agent'

      // Initialize an agent at application startup.
      const fp = Fingerprint.start({
        apiKey: 'PUBLIC_API_KEY',
        region: 'us',
      })

      // Get the visitor identifier when you need it.
      fp.get()
        .then(result => console.log(result.event_id, result.visitor_id))
      ```
    </CodeGroup>

    > Note: Each workspace exists in a specific region. If you have chosen Europe or Asia as your [data region](/docs/regions), you must specify the [`region`](/reference/js-agent-start-function#region) option as `eu` or `ap` in your agent configuration to match your workspace.

    <Warning>
      **Working with ad blockers and privacy-focused browsers**

      Requests to Fingerprint APIs are often blocked by ad-blockers or privacy-focused browsers like Brave. Make sure to disable your ad blocker when trying out the examples above.

      To identify 100% of visitors with maximum possible accuracy, use one of our cloud proxy integrations. See [protecting the JavaScript agent from ad blockers](/docs/protecting-the-javascript-agent-from-adblockers) for more details.
    </Warning>
  </Step>

  <Step title="Send request">
    Open the page or app where you installed Fingerprint and wait a second. The script automatically runs on page load.
  </Step>

  <Step title="View events">
    Now ensure the script is working as expected by visiting the [Events](https://dashboard.fingerprint.com/events) page. You should see a new event with the `event_id` field.

    <Frame>
      <img alt="A screenshot of the Events page in the Fingerprint Dashboard. It shows the events table with a single identification event, including event_id, date, visitor_id, and browser columns." />
    </Frame>

    <br />

    <Accordion title="Can't run Fingerprint right now? Try in browser sandbox">
      If you cannot set up Fingerprint right now, you can view the code and response in our browser sandbox environment.

      [Open Stackblitz](https://stackblitz.com/edit/fpjs-pro-3-cdn?devtoolsheight=1000\&embed=1\&file=index.html\&hideExplorer=1\&hideNavigation=1\&theme=light)
    </Accordion>
  </Step>
</Steps>

## Access detailed insights about a visitor

[Smart Signals](/docs/smart-signals-introduction) are actionable device intelligence insights about your visitors. These include *Bot detection*, *VPN detection*, *Browser tampering detection*, and many more.

For security reasons, Smart Signals are unavailable in the [response](/reference/js-agent-get-function#get-response) returned to the client agent. You can securely access them in a server-side environment using [Server API](/reference/server-api), [Webhooks](/docs/webhooks), or [Sealed Client Results](/docs/sealed-client-results).

For example, to use the Server API:

<Steps>
  <Step title="Send your first event">
    You may skip this step if you already generated an identification event using the steps above.

    Ensure your site or app has sent its first identification event, and then copy its `event_id`. You can find this field in the [Events](https://dashboard.fingerprint.com/events) page table.
  </Step>

  <Step title="Generate your secret API key">
    Go to [API keys > Server API](https://dashboard.fingerprint.com/api-keys?type=api) from the sidebar and click **New secret key** to generate your key.
  </Step>

  <Step title="Get an event by event ID">
    Visit the [API reference](/reference/server-api-get-event) and paste your secret key as the Authorization header and `event_id` into the API explorer. This will return all information for that identification event, including Smart Signals.

    You should see a response similar to the following:

    <CodeGroup>
      ```json Response expandable theme={"theme":"github-dark-dimmed"}
      {
        "event_id": "1708102555327.NLOjmg",
        "linked_id": "somelinkedId",
        "tags": {},
        "timestamp": 1708102555327,
        "url": "https://www.example.com/login",
        "ip_address": "61.127.217.15",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ....",
        "client_referrer": "https://example.com/blog/my-article",
        "browser_details": {
          "browser_name": "Chrome",
          "browser_major_version": "74",
          "browser_full_version": "74.0.3729",
          "os": "Windows",
          "os_version": "7",
          "device": "Other"
        },
        "identification": {
          "visitor_id": "Ibk1527CUFmcnjLwIs4A9",
          "confidence": {
            "score": 0.97,
            "version": "1.1"
          },
          "visitor_found": false,
          "first_seen_at": 1708102555327,
          "last_seen_at": 1708102555327
        },
        "supplementary_id_high_recall": {
          "visitor_id": "3HNey93AkBW6CRbxV6xP",
          "visitor_found": true,
          "confidence": {
            "score": 0.97,
            "version": "1.1"
          },
          "first_seen_at": 1708102555327,
          "last_seen_at": 1708102555327
        },
        "proximity": {
          "id": "w1aTfd4MCvl",
          "precision_radius": 10,
          "confidence": 0.95
        },
        "bot": "not_detected",
        "root_apps": false,
        "emulator": false,
        "ip_info": {
          "v4": {
            "address": "94.142.239.124",
            "geolocation": {
              "accuracy_radius": 20,
              "latitude": 50.05,
              "longitude": 14.4,
              "postal_code": "150 00",
              "timezone": "Europe/Prague",
              "city_name": "Prague",
              "country_code": "CZ",
              "country_name": "Czechia",
              "continent_code": "EU",
              "continent_name": "Europe",
              "subdivisions": [
                {
                  "iso_code": "10",
                  "name": "Hlavni mesto Praha"
                }
              ]
            },
            "asn": "7922",
            "asn_name": "COMCAST-7922",
            "asn_network": "73.136.0.0/13",
            "asn_type": "isp",
            "datacenter_result": true,
            "datacenter_name": "DediPath"
          },
          "v6": {
            "address": "2001:db8:3333:4444:5555:6666:7777:8888",
            "geolocation": {
              "accuracy_radius": 5,
              "latitude": 49.982,
              "longitude": 36.2566,
              "postal_code": "10112",
              "timezone": "Europe/Berlin",
              "city_name": "Berlin",
              "country_code": "DE",
              "country_name": "Germany",
              "continent_code": "EU",
              "continent_name": "Europe",
              "subdivisions": [
                {
                  "iso_code": "BE",
                  "name": "Land Berlin"
                }
              ]
            },
            "asn": "6805",
            "asn_name": "Telefonica Germany",
            "asn_network": "2a02:3100::/24",
            "asn_type": "isp",
            "datacenter_result": false,
            "datacenter_name": ""
          }
        },
        "ip_blocklist": {
          "email_spam": false,
          "attack_source": false,
          "tor_node": false
        },
        "proxy": true,
        "proxy_confidence": "low",
        "proxy_details": {
          "proxy_type": "residential",
          "last_seen_at": 1708102555327
        },
        "vpn": false,
        "vpn_confidence": "high",
        "vpn_origin_timezone": "Europe/Berlin",
        "vpn_origin_country": "unknown",
        "vpn_methods": {
            "timezone_mismatch": false,
            "public_vpn": false,
            "auxiliary_mobile": false,
            "os_mismatch": false,
            "relay": false
        },
        "incognito": false,
        "tampering": false,
        "tampering_details" : {
          "anomaly_score": 0.1955,
          "anti_detect_browser": false
        },
        "cloned_app": false,
        "factory_reset_timestamp": 0,
        "jailbroken": false,
        "frida": false,
        "privacy_settings": false,
        "virtual_machine": false,
        "location_spoofing": false,
        "velocity": {
          "distinct_ip": {
            "5_minutes": 1,
            "1_hour": 1,
            "24_hours": 1
          },
          "distinct_country": {
            "5_minutes": 1,
            "1_hour": 2,
            "24_hours": 2
          },
          "events": {
            "5_minutes": 1,
            "1_hour": 5,
            "24_hours": 5
          },
          "ip_events": {
            "5_minutes": 1,
            "1_hour": 5,
            "24_hours": 5
          },
          "distinct_ip_by_linked_id": {
            "5_minutes": 1,
            "1_hour": 5,
            "24_hours": 5
          },
          "distinct_visitor_id_by_linked_id": {
            "5_minutes": 1,
            "1_hour": 5,
            "24_hours": 5
          }
        },
        "developer_tools": false,
        "mitm_attack": false,
        "sdk": {
          "platform": "js",
          "version": "3.11.10",
          "integrations": [
            {
              "name": "fingerprint-pro-react",
              "version": "3.11.10",
              "subintegration": {
                "name": "preact",
                "version": "10.21.0"
              }
            }
          ]
        },
        "replayed": false,
        "high_activity_device": false
      }
      ```

      ```shell cURL theme={"theme":"github-dark-dimmed"}
      curl --request GET \
          --url https://api.fpjs.io/v4/events/<event_id> \
          --header 'Authorization: Bearer SECRET_API_KEY' \
          --header 'accept: application/json'
      ```
    </CodeGroup>

    <Info>
      If you have chosen Europe or Asia as your [data region](/docs/regions), use `eu.api.fpjs.io` or `ap.api.fpjs.io` respectively.
    </Info>
  </Step>

  <Step title="Use Server API in your backend">
    We support several backend libraries to make it easier to work with the Fingerprint Server API and other resources. You can view available libraries from the [Integrations](https://dashboard.fingerprint.com/integrations) page in the Dashboard or below.

    <Columns>
      <Card title="Node.js" icon="node" href="/docs/node-server-quickstart" />

      <Card title="PHP" icon="php" href="/docs/php-server-quickstart" />

      <Card title="Python" icon="python" href="/docs/python-server-quickstart" />

      <Card title="Go" icon="golang" href="/docs/go-server-quickstart" />

      <Card title="Java" icon="java" href="/docs/java-server-quickstart" />

      <Card title="View all" icon="arrow-right" href="/docs/server-quickstarts-overview" />
    </Columns>
  </Step>
</Steps>

## Next steps

<Columns>
  <Card title="Protect against ad blockers" icon="globe" href="/docs/protecting-the-javascript-agent-from-adblockers">
    Maximize accuracy and protect your JavaScript snippet against ad blockers.
  </Card>

  <Card title="Tag an event with your data" icon="braces" href="/docs/tagging-information">
    Join Fingerprint data with relevant details like user IDs for real-world use cases.
  </Card>

  <Card title="Protect your API key" icon="shield" href="/docs/request-filtering">
    Prevent unauthorized key usage by configuring allow and block lists.
  </Card>
</Columns>


# React
Source: https://docs.fingerprint.com/docs/react



The [Fingerprint React SDK](https://github.com/fingerprintjs/react) integrates Fingerprint into React applications. It supports all capabilities of the JavaScript agent including a built-in [caching mechanism](/reference/js-agent-start-function#cache). See the [React quickstart](/docs/react-quickstart) for a step-by-step guide to get started.

### How to install

Add `@fingerprint/react` as a dependency to your application via npm or yarn.

<CodeGroup>
  ```shell NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/react
  ```

  ```shell Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/react
  ```

  ```shell PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/react
  ```
</CodeGroup>

Wrap your application (or component) in `FingerprintProvider`. You need to specify your public API key and other configuration options based on your chosen region and active integration.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// src/index.jsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { FingerprintProvider } from '@fingerprint/react';

createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <FingerprintProvider
      apiKey="PUBLIC_API_KEY"
      endpoints="https://metrics.yourwebsite.com"
      region="us"
    >
      <App />
    </FingerprintProvider>
  </React.StrictMode>,
);
```

Use the `useVisitorData` hook in your components to identify visitors.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
// src/App.jsx
import { useVisitorData } from '@fingerprint/react';

export default function Home() {
  const { isLoading, error, data, getData } = useVisitorData({ immediate: true });

  return (
    <div>
      <button onClick={() => getData()}>Reload data</button>
      <p>Visitor ID: {isLoading ? 'Loading...' : data?.visitor_id}</p>
      <p>Full visitor data:</p>
      <pre>{error ? error.message : JSON.stringify(data, null, 2)}</pre>
    </div>
  );
}
```

### Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/react). The repository also contains [an example app](https://github.com/fingerprintjs/react/tree/main/examples/create-react-app) demonstrating the usage of the library.

### Migration guide for React SDK v3.0.0

Version 3.0.0 of the React SDK switches from JavaScript agent v3 to [JavaScript agent v4](/reference/migrating-from-v3-to-v4).

1. Install a new version of the package:

<CodeGroup>
  ```bash NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/react
  ```

  ```bash Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/react
  ```

  ```bash PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/react
  ```
</CodeGroup>

2. Update your Fingerprint provider:

The default caching strategy has changed from `sessionStorage` caching to **no caching by default**, aligned with the underlying [JavaScript agent v4 default](/reference/js-agent-start-function#cache). To preserve the previous behavior, explicitly configure caching in the provider (see example below).

```javascript Change provider imports and usage theme={"theme":"github-dark-dimmed"}
// [!code --]
import { FpjsProvider, FingerprintJSPro, CacheLocation } from '@fingerprintjs/fingerprintjs-pro-react'
import { FingerprintProvider } from '@fingerprint/react' // [!code ++]

<FpjsProvider // [!code --:15]
  cacheLocation={CacheLocation.LocalStorage}
  cacheTimeInSeconds={60}
  loadOptions={{
    apiKey: "PUBLIC_API_KEY",
    endpoint: [
      // "https://metrics.yourwebsite.com",
      FingerprintJSPro.defaultEndpoint
    ],
    scriptUrlPattern: [
      // "https://metrics.yourwebsite.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js",
      FingerprintJSPro.defaultScriptUrlPattern
    ],
  }}
>
// [!code ++:8]
<FingerprintProvider
  cache={{
    storage: "sessionStorage",
    duration: 3600
  }}
  apiKey="PUBLIC_API_KEY"
  endpoints="https://metrics.yourwebsite.com"
/>
```

3. Update `useVisitorData` calls:

```javascript Update parameters theme={"theme":"github-dark-dimmed"}
// [!code --]
import { useVisitorData } from '@fingerprintjs/fingerprintjs-pro-react';
// [!code ++]
import { useVisitorData } from '@fingerprint/react';

// [!code --:4]
const { data, getData } = useVisitorData(
  { timeout: 1000, ignoreCache: true },
  { immediate: false },
);

// [!code ++:3]
// `immediate` can now be configured in a first parameter
// `ignoreCache` parameter is no longer available, cache can be configured on the provider level instead
const { data, getData } = useVisitorData({ timeout: 1000, immediate: false });
```


# React Native Quickstart
Source: https://docs.fingerprint.com/docs/react-native-quickstart



<Warning>
  ### JavaScript agent v4 support coming soon

  This client SDK currently supports JavaScript agent v3. For the current v3 quickstart, see [React Native Quickstart (v3)](/docs/v3/react-native-quickstart). You can also check the current [integration compatibility table](/reference/migrating-from-v3-to-v4#client-sdk-compatibility-for-javascript-agent-v4).
</Warning>


# React Quickstart
Source: https://docs.fingerprint.com/docs/react-quickstart

Get started using the Fingerprint React SDK

## Overview

In this quickstart, you'll add Fingerprint to a new [React](https://react.dev/) project and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend integration. You'll install the [Fingerprint React SDK](/docs/react) and initialize the JavaScript agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of [React](https://react.dev/) and JavaScript

<Note>
  This quickstart only covers the **frontend setup**. You'll need a [backend
  server](/reference/server-sdks) to receive and process the device identification event to enable
  fraud detection. Check out one of the [backend quickstarts](/docs/server-quickstarts-overview)
  after completing this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the JavaScript agent.

## 2. Set up your project

To get started, scaffold a new React app. If you already have a project you want to use, you can skip to the next section.

1. Create a new Vite project with the React template:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm create vite@latest fingerprint-react-quickstart -- --template react
cd fingerprint-react-quickstart
npm install
```

2. Open the `fingerprint-react-quickstart` folder in your code editor and you're ready to go! To run your project, run:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

3. In your browser, go to [http://localhost:5173](http://localhost:5173/) (Vite's default), and you should see the Vite welcome page.

## 3. Set up your account creation form

1. Before adding Fingerprint, create a new component at `src/components/CreateAccountForm.jsx` with the following:

```jsx src/components/CreateAccountForm.jsx theme={"theme":"github-dark-dimmed"}
import { useState } from "react";

export default function CreateAccountForm(props) {
  const [username, setUsername] = useState("");
  const [password, setPassword] = useState("");
  return (
    <div className="wrapper">
      <h1>Create an account</h1>
      <div className="input-group">
        <label htmlFor="username">Username</label>
        <input
          id="username"
          value={username}
          onChange={(e) => setUsername(e.target.value)}
          type="text"
          placeholder="Username"
          required
        />
      </div>
      <div className="input-group">
        <label htmlFor="password">Password</label>
        <input
          id="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          type="password"
          placeholder="Password"
          required
        />
      </div>
      <button disabled={props.isLoading} onClick={props.handleSubmit}>
        {props.isLoading ? "Loading…" : "Create Account"}
      </button>
    </div>
  );
}
```

2. Open `src/App.css` and add these classes to the end of the file:

```css src/App.css theme={"theme":"github-dark-dimmed"}
.wrapper {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  min-height: 100vh;
  gap: 1rem;
  padding: 1rem;
}

input {
  width: 100%;
  padding: 0.5rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}

.input-group {
  width: 100%;
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 0.5rem;
}

button {
  background-color: #f35b22;
  color: #fff;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 4px;
  cursor: pointer;
}

button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
```

3. Import and add the component to your App component in `src/App.jsx`. The entire file can be replaced with this:

```jsx src/App.jsx theme={"theme":"github-dark-dimmed"}
import "./App.css";
import CreateAccountForm from "./components/CreateAccountForm";

function App() {
  return (
    <>
      <CreateAccountForm />
    </>
  );
}

export default App;
```

## 4. Install and initialize the JavaScript agent

1. To integrate Fingerprint into your React app, first add the Fingerprint React SDK via npm:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/react
```

*Note: This quickstart is written for version 3.x of the Fingerprint React SDK*

2. Now that the React SDK is installed, import and initialize the Fingerprint provider in your app's entry point. Open `src/main.jsx` and add:

```jsx src/main.jsx theme={"theme":"github-dark-dimmed"}
import { FingerprintProvider } from "@fingerprint/react";
```

3. Wrap `<App />` with the FingerprintProvider component:

```jsx src/main.jsx theme={"theme":"github-dark-dimmed"}
createRoot(document.getElementById("root")).render(
  <StrictMode>
    <FingerprintProvider
      // FingerprintProvider supports the same options as the `start` method of the JavaScript agent.
      // To learn more, see https://docs.fingerprint.com/reference/js-agent-start-function
      apiKey="PUBLIC_API_KEY"
      region="us" // Ensure this matches your workspace region
      // For more information, see https://docs.fingerprint.com/docs/regions
    >
      <App />
    </FingerprintProvider>
  </StrictMode>,
);
```

4. Replace `PUBLIC_API_KEY` with your public API key from the [Fingerprint dashboard](https://dashboard.fingerprint.com/api-keys).

*Note: For production, consider using* *[Vite Env Variables](https://vite.dev/guide/env-and-mode)* *to configure the key.*

## 5. Trigger visitor identification

Now that the JavaScript agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps the **Create Account** button.

When making the visitor identification request, you will receive the `visitor_id` as well as an `event_id`. Instead of using the `visitor_id` returned directly on the frontend (which could be tampered with), you'll send the `event_id` to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. In `App.jsx`, import Fingerprint's `useVisitorData` hook:

```jsx src/App.jsx theme={"theme":"github-dark-dimmed"}
import "./App.css";
import CreateAccountForm from "./components/CreateAccountForm";
import { useVisitorData } from "@fingerprint/react"; // [!code ++]
```

2. Inside the `App` component, use Fingerprint's `useVisitorData` hook to obtain visitor data. The hook is configured here to defer identification until you call it, and it returns the state you'll need:

```jsx src/App.jsx theme={"theme":"github-dark-dimmed"}
function App() {
  const { getData, isLoading } = useVisitorData({ immediate: false }); // [!code ++]

  return (
    <>
      <CreateAccountForm />
    </>
  );
}
```

This gives you:

* `getData()`: A function to trigger visitor identification on demand.
* `isLoading`: A flag to monitor visitor identification progress.

By setting immediate to false you're triggering device identification only when needed with the `getData()` method.

*Check our* *[GitHub repo](https://github.com/fingerprintjs/react)* *for available useVisitorData options.*

3. Straight after the hook, define the submit handler to trigger identification when the user clicks **Create Account**:

```jsx src/App.jsx theme={"theme":"github-dark-dimmed"}
function App() {
  const { getData, isLoading } = useVisitorData({ immediate: false });

  async function handleSubmit() {
    // [!code ++:5]
    const { visitor_id, event_id } = await getData();

    console.log("Visitor ID:", visitor_id);
    console.log("Event ID:", event_id);

    // Example of how you could send the event_id and form data to your server:
    // await fetch("http://localhost:3000/api/create-account", {
    //   method: "POST",
    //   headers: { "Content-Type": "application/json" },
    //   body: JSON.stringify({
    //     username: username.value,
    //     password: password.value,
    //     event_id,
    //   }),
    // });
  } // [!code ++]

  return (
    <>
      <CreateAccountForm />
    </>
  );
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

In this function, `getData()` is being called and Fingerprint is analyzing the visitor's browser. The result of the identification will include an `event_id`, which you can then send to your backend along with the username and password for your fraud detection logic.

4. Pass the `isLoading` and `handleSubmit` props to `CreateAccountForm`:

```jsx src/App.jsx theme={"theme":"github-dark-dimmed"}
<CreateAccountForm isLoading={isLoading} handleSubmit={handleSubmit} />
```

## 6. Test the app

1. If your dev server isn't already running, start it with:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. In your browser, go to [http://localhost:5173](http://localhost:5173/) (Vite's default).
3. If you have any ad blockers, turn them off for localhost. View the [documentation](/docs/protecting-the-javascript-agent-from-adblockers) to learn how to protect your Fingerprint implementation from ad blockers in production.
4. Enter a username and password, then click **Create Account**.
5. Open the developer console in your browser and you should see the visitor ID and event ID in the output:

```text Output theme={"theme":"github-dark-dimmed"}
Visitor ID: JkLmNoPqRsTuVwXyZaBc
Event ID: 1234566477745.abc1GS
```

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the `event_id` to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information data and use it to make decisions and prevent fraud.

Check out these related resources:

* [React SDK reference](https://github.com/fingerprintjs/react)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Regional Pricing Enforcement
Source: https://docs.fingerprint.com/docs/regional-pricing-use-case-tutorial

Learn how to implement and enforce regional pricing

## Overview

This tutorial walks through implementing Fingerprint to enforce regional pricing and prevent visitors from using VPNs or location spoofing to claim discounts intended for other regions.

You'll begin with a starter app that includes a mock checkout page and a discount pricing flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to determine their real location and apply the correct regional price. You'll also block VPN users from activating discounts they aren't eligible for.

By the end, you'll have a sample app that enforces region-based pricing per visitor and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

<Note>
  This tutorial requires the VPN Detection Smart Signal, which is only available on paid plans.
</Note>

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `regional-pricing` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Checkout page with regional pricing" />

    <Tree.File name="index.js - Front-end logic for regional pricing" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="discounts.js - Regional pricing logic" />

    <Tree.File name="server.js - Serves static files and discount endpoint" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock checkout page from the starter app. You can test out the basic regional discount flow by clicking **Activate local discount**. You'll notice that the discount is applied based on your location. Try manipulating the discount by turning on a VPN and selecting a server in another country then activating the local discount on this page again.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Activate local discount**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including location data and VPN detection.

1. Before adding any new code, delete the client-side IP lookup. Specifically, open `public/index.js` and remove the `getIP()` function and any calls to it.
2. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

3. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
4. Near the bottom of `public/index.js`, the **Activate local discount** button already has an event handler for requesting a regional discount. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` in the body instead of the client-side IP.

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
activateBtn.addEventListener("click", async () => {
  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/region-discount", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ eventId }),
    });

    const data = await res.json();

	// ...
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your backend, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the full visitor details and [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/region-discount` route to extract `eventId` from the request body and pass it into the `getRegionDiscount` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/region-discount", async (req, reply) => {
  const { eventId } = req.body;
  const result = await getRegionDiscount(eventId);
  return reply.send(result);
});
```

2. The `server/discounts.js` file contains the logic for calculating regional discounts. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/discounts.js theme={"theme":"github-dark-dimmed"}
import fs from "fs";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `getRegionDiscount` function to accept `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/discounts.js theme={"theme":"github-dark-dimmed"}
export async function getRegionDiscount(eventId) {
  const event = await fpServerApiClient.getEvent(eventId);

  // ...
}
```

5. Now retrieve the visitor's real country directly from Fingerprint. Inside `getRegionDiscount`, read the `geolocation` object from the identification event and extract the country code and name fields. This replaces the previous IP-based lookup:

```javascript server/discounts.js theme={"theme":"github-dark-dimmed"}
export async function getRegionDiscount(eventId) {
  const event = await fpServerApiClient.getEvent(eventId);
  const ipInfoV4Location = event.ip_info.v4.geolocation;
  const countryCode = ipInfoV4Location.country_code;
  const countryName = ipInfoV4Location.country_name;

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Enforce VPN restrictions

For regional pricing, the core protection is making sure visitors aren't using a VPN to appear as if they are in a cheaper region. Fingerprint includes a VPN detection [Smart Signal](https://fingerprint.com/products/smart-signals/) that indicates whether the visitor is routing traffic through a VPN service. If a VPN is detected, the request should not receive any regional discount.

1. Continuing in `getRegionDiscount` logic to read the VPN signal from the identification event and block discounted pricing whenever VPN usage is present:

```javascript server/discounts.js theme={"theme":"github-dark-dimmed"}
export async function getRegionDiscount(eventId) {
  const event = await fpServerApiClient.getEvent(eventId);

  // ...

  const vpnDetected = event.vpn;
  if (vpnDetected) {
    console.error("VPN detected.");
    return {
      success: false,
      message:
        "VPN detected. Please turn off your VPN and use your normal connection before activating regional pricing.",
    };
  }
  // ...
}
```

This gives you a system to detect and block abusive regional pricing attempts. You can extend it by customizing how discounts are applied, adding country-specific rules, or layering in more Smart Signals based on your needs.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error handling, and data handling that align with your
  production standards.
</Info>

## 6. Block bots and suspicious devices

An additional way to protect your checkout is to block automated traffic from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity so you can deny discounted pricing to non-human traffic.

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found.

1. Continuing in the `getRegionDiscount` function in `server/discounts.js`, check the bot signal returned in the `event` object:

```javascript server/discounts.js theme={"theme":"github-dark-dimmed"}
export async function getRegionDiscount(eventId) {
  // ...

  const botDetected = event.bot !== "not_detected";

  if (botDetected) {
    console.error("Bot detected.");
    return {
      success: false,
      message: "No discount available for your location.",
    };
  }

  // ...
}
```

You can also use Fingerprint's [Suspect Score](/docs/suspect-score) to flag suspicious regional pricing requests. The Suspect Score is a weighted representation of all Smart Signals in the identification payload and can help you detect high-risk traffic. While you wouldn't normally deny regional pricing based only on this score, you could use it to flag the request for review or introduce additional checks.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the regional discount if it exceeds a chosen threshold (for example, 20):

```javascript server/discounts.js theme={"theme":"github-dark-dimmed"}
export async function getRegionDiscount(eventId) {
  // ...

  const suspectScore = event.suspect_score || 0;

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return {
      success: false,
      message: "No discount available for your location.",
    };
  }

  // ...
}
```

## 7. Test your implementation

Now that everything is wired up, you can test the protected regional pricing flow using the checkout page.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000/):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Click **Activate local discount** to fetch your country and apply the appropriate pricing.
3. Try activating the discount again while connected to a VPN. The request will be blocked, and no regional pricing will be applied.
4. Bonus: Test the flow using a headless browser or automation tool to see bot detection in action. A sample script is available in `test-bot.js`. While your app is running, run the script with `node test-bot.js` in your terminal and observe that automated discount attempts are also blocked.

## Next steps

You now have a working regional pricing flow secured with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), adjust discount rules per market, or add extra checks for suspicious visitors.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Regions and data retention
Source: https://docs.fingerprint.com/docs/regions

Learn more about where and how we store the identification data of your visitors.

## Regions

When creating your Fingerprint workspace, you can choose the region in which your data will be stored. Pick the one that best suits your infrastructure, latency, and regulatory compliance requirements. Your data never leaves the chosen region. Once chosen, your workspace region cannot be changed.

Fingerprint supports the following regions. The Global (US) region is used by default.

| Region      | Server location        | Code identifier                | Base API URL             |
| :---------- | :--------------------- | :----------------------------- | :----------------------- |
| Global (US) | Northern Virginia, USA | `us` (default, can be omitted) | `https://api.fpjs.io`    |
| EU          | Frankfurt, Germany     | `eu`                           | `https://eu.api.fpjs.io` |
| Asia        | Mumbai, India          | `ap`                           | `https://ap.api.fpjs.io` |

### Specifying region for the JavaScript agent

If you choose a non-default region (EU or Asia), you need to specify it when initializing the JavaScript agent. See the [JavaScript agent Reference > `region`](/reference/js-agent-start-function#region) for more details.

<CodeGroup>
  ```ts CDN theme={"theme":"github-dark-dimmed"}
  <script>
    const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY')
      .then(Fingerprint => Fingerprint.start({
        // Specify "region" as "eu" or "ap" if you don't use the default region
        region: 'eu' // [!code ++]
      }));
  </script>
  ```

  ```javascript NPM theme={"theme":"github-dark-dimmed"}
  import Fingerprint from '@fingerprint/agent'

  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    // Specify "region" as "eu" or "ap" if you don't use the default region
    region: 'eu' // [!code ++]
  })
  ```
</CodeGroup>

### Specifying region for the Server API

If you choose a non-default region (EU or Asia), you need to use a corresponding base API URL (`eu.api.fpjs.io` or `ap.api.fpjs.io`) when interacting with Fingerprint Server API. See the [Server API Reference](/reference/server-api#regions) for more details.

<CodeGroup>
  ```bash EU theme={"theme":"github-dark-dimmed"}
  curl --request GET
       --url https://api.fpjs.io/v4/events/YOUR_EVENT_ID # [!code --]
       --url https://eu.api.fpjs.io/v4/events/YOUR_EVENT_ID #[!code ++]
       --header 'Authorization: Bearer <YOUR_SECRET_KEY>'
       --header 'accept: application/json'
  ```

  ```bash Asia theme={"theme":"github-dark-dimmed"}
  curl --request GET
       --url https://api.fpjs.io/v4/events/YOUR_EVENT_ID # [!code --]
       --url https://ap.api.fpjs.io/v4/events/YOUR_EVENT_ID #[!code ++]
       --header 'Authorization: Bearer <YOUR_SECRET_KEY>'
       --header 'accept: application/json'
  ```
</CodeGroup>

## Data retention

For most plans, visit history is available through the Server API for the past **30 days**. For Enterprise plans, the data is kept for **90 days** or longer depending on the enterprise contract.

If you need to store data for longer than your plan allows or prefer a custom storage solution, you can use [Webhooks](/docs/webhooks). Webhooks allow you to automatically receive each identification response at your custom server endpoint and save them in your database.

## Data deletion

As a data processor that complies with several Data Processing Addendums (i.e., GDPR, US Privacy Laws, etc) Fingerprint, upon request from a data controller, will delete information belonging to a browser or a device. Please [contact support](https://fingerprint.com/support/?_gl=1*jrp5dd*_gcl_aw*R0NMLjE3NDc5MzQ1NjEuQ2owS0NRandscnZCQmhEbkFSSXNBSEVRZ09SNlJBQkJiMU9TbkNvcmx2bnpqaW1UTmJFUGEyaDFJd3NNWmlNcUtYWFI1cmdxLUNoYlpjb2FBdmk4RUFMd193Y0I.*_gcl_au*MjA5NzI4MTM3OS4xNzQ0NTQ3ODYwLjIxMjc2MTA3ODYuMTc1MDA4NTI1Ni4xNzUwMDg1MjU3*_ga*NDA5OTM0Mzc2LjE3MTA1NDE5NjU.*_ga_XVKDT0L5WV*czE3NTEyODc2NTEkbzE0OCRnMSR0MTc1MTI4NzkwMyRqNjAkbDAkaDk4NzgxODAxMg..) for more information.


# Roles & permissions
Source: https://docs.fingerprint.com/docs/roles-permissions



Any user of the Fingerprint Dashboard can only have access to one account. Within that account, access to multiple workspaces is determined by the account owners based on access preferences and user permissions.

To invite team members and manage their access, navigate to **Settings** > [**Team members**](https://dashboard.fingerprint.com/settings/users).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 56 11@2x" />
</Frame>

## Team Roles

Account administrators or team managers can invite other people to join the team and access the Fingerprint account.

When inviting a team member, you select their role. Standard roles include:

* **Viewer** - Read-only access on your account. Can view analytics and configuration resources on all workspaces.
* **Editor** - Edit access on your account. Can manage analytics and configuration resources on all workspaces.
* **Billing Admin** - Manages account-wide billing options, but no access to any workspace-specific resources.
* **Administrator** - Full unrestricted access.

## Granular Permissions

You have the ability to fine tune user access by customizing both account permissions, and permissions for each workspace.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 00 33@2x" />
</Frame>

For most permissions you can set them as **None**, **View**, or **Edit**.

* **None** - no access to specified features or resources
* **View** - read-only access to specified features or resources
* **Edit** - full managing access to specified features or resources

Reference of available granular permissions and their settings:

| Scope     | Permission                               | None                                 | View                                                                 | Edit                                                              |
| --------- | ---------------------------------------- | ------------------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Account   | **Billing**                              | Can't view billing information       | Can view billing information                                         | Can manage billing information, payment methods, and plan options |
| Account   | **Members**                              | Can't view team members              | Can view team members                                                | Can invite members and manage their permissions                   |
| Workspace | [**Analytics**](/docs/analytics)         | No access to analytics               | View access to analytical pages                                      | View access + ability to manage *Suspect Score*                   |
| Workspace | [**Configuration**](/docs/configuration) | No access to configuration resources | View access to configuration resources                               | Managing access to configuration resources                        |
| Workspace | **PII**                                  | Can't view PII                       | Visible IP address, country, and other data derived from geolocation | -                                                                 |


# Rules Engine (Beta)
Source: https://docs.fingerprint.com/docs/rules-engine

Protect your application with rules based on Fingerprint device intelligence. Define fraud detection rules in Fingerprint and evaluate them against identification events.

<Warning>
  **Feature in Beta**

  This feature is currently in an open Beta testing phase. We recommend testing it inside an isolated staging environment. All feedback is welcome! If you encounter any issues, please [contact](https://fingerprint.com/support/) our support team.
</Warning>

<Note>
  **Pre-requisites**

  * A Fingerprint account with an **Admin** role.
</Note>

The Rules Engine allows you to define an event **ruleset** — a collection of rules evaluated against a Fingerprint [identification event](/reference/server-api-get-event), including the [Visitor ID](/docs/identify-visitors) and [Smart Signals](/docs/smart-signals-introduction).

For example, you might want to prevent browsers in incognito mode from creating accounts in your application:

1. Open the Fingerprint Dashboard.
2. Navigate to **Rules Engine**.
3. Click **+ New ruleset**. You will see a canvas with an initial "Identify visitors" node.
4. Click **+ Add rule**.
5. Choose the **Browser incognito detection** Smart Signal as the rule condition.
6. Click on the added rule to start editing it using the right-hand sidebar.
7. Make sure the **If Incognito** condition is set to **True**.
8. Optionally, in the **Then** section, adjust the **Status** or the **Body** of the response, for example `{"message": "Incognito not allowed"}`
9. In the top right corner, click **Save** to save your changes.

The ruleset is saved right away, but it can take up to 60 seconds for the changes to propagate.

<img alt="" />

Keep learning about rulesets below, or just go straight to [Using the ruleset](#using-the-ruleset).

## Rule condition

A rule condition is a logical expression like

* `IF VPN is True`
* `IF Suspect Score is greater than 10 AND IPv4 Country Code is CN`
* `IF Incognito Mode is True AND Returning visitor is True AND (AntiDetect Browser is True OR Privacy-focused Settings is True)`

The simplest condition is a single comparison (for example, `VPN is True`), consisting of the event *property* (`VPN`), *operator* (`is`) and *value* (`True`).

You can combine multiple comparisons using logical operators (`AND` and `OR`) and groups.

<Note>
  To keep things simple, you must use the same logical operator between all comparisons within a group.

  * You cannot represent a condition like `a AND b OR c`.
  * But you can do `a AND b AND c`, `a OR b OR c`, `a AND (b OR c)`.
</Note>

<img alt="" />

### Rule name

A rule name is generated based on the initial comparison property. You can rename rules by clicking the name at the top of the rule form sidebar.

## Rule action

A rule action describes the recommended outcome when a rule's condition is true. There are two options:

* **Block with response** — the request should be blocked before reaching your application origin server, and a predefined response returned to the client.
  * You can define the headers and body of the response.
* **Allow with headers** — the request should be forwarded to your application origin server as normal.
  * Optionally, you can modify the request headers to pass additional, predefined information to your server.

The Rules Engine itself can't enforce the outcome. How the action is applied depends on how you [use the ruleset](#using-the-ruleset):

* With the **Server API**, the action is returned as a `rule_action` result in the identification event, and your application code decides how to act on it, for example by blocking, allowing, redirecting, or tagging the request.
* With a **Flow worker** on Cloudflare, the worker applies the action automatically, blocking the request or forwarding it to your origin server.

<img alt="" />

## Multiple rules

Each ruleset contains an **ordered** collection of rules. You can add a rule by clicking **Add rule** underneath your last rule on the canvas.

* Rules are evaluated first to last (top to bottom).
* When a rule is matched (its condition is true), the ruleset evaluation stops (no more rules are checked).
* The action of the matched rule is returned as the ruleset evaluation result.
* If no rules are matched, the ruleset evaluates to an **Allow** action without any header modifications.

<img alt="" />

## Ruleset settings

Click the **Settings** tab at the top to access ruleset settings. Here you can:

* Find the **Ruleset ID**.
* Change the ruleset **Name**.
* Change the ruleset **Description**.
* **Enable or disable** a ruleset.
  * A disabled ruleset always evaluates to a simple **Allow** action without any header modifications. It is equivalent to a ruleset with zero rules.
* **Deploy with Cloudflare** — deploy the ruleset using a Flow worker.
* **Delete** the ruleset. Note that if the ruleset is deployed, you need to remove the deployment first.

<img alt="" />

## Using the ruleset

An undeployed ruleset is just a row in the Fingerprint database. To actually use it, you evaluate the ruleset against identification events from your application, which requires integrating Fingerprint into your setup. There are two ways to do this:

* [**Server API**](#ruleset-evaluation-using-server-api) — Use the Fingerprint Server API to evaluate the ruleset against a specific identification event. Works with any setup and requires a one-time integration in your application code to evaluate rulesets and handle their results.
* [**Flow Cloudflare Workers**](#using-the-ruleset-with-flow-workers-on-cloudflare) — Deploy a Cloudflare worker on your website to identify visitors and protect API endpoints using your ruleset, with little to no application code changes. Works for websites hosted on Cloudflare.

<Info>
  **Deployment options explained**

  To illustrate the difference, a traditional Fingerprint integration without the Rules engine looks like this:

  1. [Install the JavaScript agent](/docs/install-the-javascript-agent) or mobile SDK in your web or mobile app.
  2. Use a custom subdomain or a [proxy integration to evade ad blockers](/docs/protecting-the-javascript-agent-from-adblockers).
  3. [Identify the visitor](/docs/identify-visitors) and pass the Fingerprint `event_id` from the client to your server as part of the API request you want to protect, for example, the `/create-account` API call.
  4. [On the server](/docs/get-server-side-intelligence), use the [Server API](/reference/server-api) to get the full identification result, including [Smart Signals](/docs/smart-signals-introduction).
  5. Write custom code to parse the identification event and handle the request accordingly. For example, returning an error instead of creating the account if `event.incognito` is `true`.

  When using the Rules Engine with **Server API**, steps 1-4 remain mostly the same. Step 5 is simplified by the Rules Engine.

  When using the Rules Engine with **Flow Cloudflare Workers**, the equivalent of all the steps (1-5) is performed by the worker, with little to no changes to your application code.
</Info>

### Ruleset evaluation using Server API

This option works well if your application is not hosted on Cloudflare or when you want to add the Rules engine to an existing Fingerprint integration.

<Info>
  The Rules Engine requires using [Server API v4](/reference/server-api-get-event) (not v3) to evaluate rulesets.
</Info>

1. Integrate Fingerprint into your application as usual (Steps 1-3 described above).
2. When [retrieving the full identification event from Server API](/reference/server-api-get-event), pass the `ruleset_id` of your ruleset as a query parameter to the `GET /events/{event_id}` API call. You can find the ruleset ID in the ruleset **Settings** tab and the Secret API Key in the [API Keys](https://dashboard.fingerprint.com/api-keys?type=api) section.
   ```curl theme={"theme":"github-dark-dimmed"}
   curl --request GET \
     --url 'https://api.fpjs.io/v4/events/<EVENT_ID>?ruleset_id=<RULESET_ID>' \
     --header 'Authorization: Bearer SECRET_API_KEY'
   ```
3. The Server API will evaluate the identification event against the ruleset and include a `rule_action` object in the result. This is the [Rule action](#rule-action) of the matched rule or an Allow action if no rules in the ruleset matched.
   ```json Server API Event response - Action blocked theme={"theme":"github-dark-dimmed"}
   {
     "event_id": "1768992558661.2J0stP",
     "identification": { /* ... */ },
     "incognito": true,
     "rule_action": {
       "ruleset_id": "rs_OyQUaHCx9tgkFp",
       "rule_id": "r_SGSkm40YLdBSGo",
       "rule_expression": "incognito",
       "type": "block",
       "status_code": 403,
       "headers": [
         {
           "name": "Content-Type",
           "value": "application/json"
         }
       ],
       "body": "{\"message\": \"Incognito not allowed\"}"
     },
     /* ... */ 
   }
   ```
   ```json Server API Event response - Action allowed theme={"theme":"github-dark-dimmed"}
   {
     "event_id": "1768992462622.Xk9nJu",
     "identification": { /* ... */ },
     "incognito": false,
     "rule_action": {
       "ruleset_id": "rs_OyQUaHCx9tgkFp",
       "type": "allow"
     },
     /* ... */
   }
   ```
4. Your server code can handle the client request using the contents of the returned `rule_action`, usually allowing, blocking, redirecting, or tagging the request.
   ```typescript app/create-account/route.ts theme={"theme":"github-dark-dimmed"}
   export async function POST(request: Request) {
     const body = await request.json();
     const { event_id } = body;
     const rulesetId = 'rs_OyQUaHCx9tgkFp';
     const apiKey = process.env.FP_SECRET_API_KEY;
     const url = `https://api.fpjs.io/v4/events/${event_id}?ruleset_id=${rulesetId}`;
     const response = await fetch(url, {
       method: 'GET',
       headers: {
           Authorization: `Bearer ${apiKey}`,
         },
     });
     const eventData = await response.json();
     const { rule_action } = eventData;
     // If a rule_action exists and is blocking, block the client request
     if (rule_action?.type === 'block') {
       const headers = Object.fromEntries(
         rule_action.headers.map((h: { name: string; value: string }) => [h.name, h.value])
       );
       return new Response(rule_action.body, { status: rule_action.status_code, headers });
     }
     // Action allowed, create the account (for example) and return success
     return Response.json({
       success: true,
     });
   }
   ```

See the [Server API reference](/reference/server-api-get-event) for more information.

Defining your protection rules in the Rules engine instead of keeping them in your application code directly has these benefits:

* You can update your protection rules fast, without having to update your application's source code and redeploy it. This removes friction, letting you quickly react to threats during attacks or incidents.
* Even less technical users can define and edit the rulesets directly. You can tweak protection rules without involving development teams.

### Using the ruleset with Flow Workers on Cloudflare

If your goal is to protect a website hosted on Cloudflare, you can use a Flow worker to integrate Fingerprint into your website with little to no application code changes and no DNS changes.

The Flow worker sits between the browser accessing your website and the origin server. It automatically handles all the steps described above for you:

* Injects the JavaScript agent into the pages you define.
* For the protected API endpoints you define, it triggers visitor identification.
* It evaluates the ruleset against the identification result and applies the result, blocking the request or forwarding it to the origin server.
* Requests are naturally same-site, no need for a separate proxy integration to deal with ad blockers.

See [Flow deployments on Cloudflare](/docs/flow-deployments) for more information.


# SMS Pumping
Source: https://docs.fingerprint.com/docs/sms-pumping-use-case-tutorial

Learn how to detect and prevent SMS pumping fraud

## Overview

This tutorial walks through implementing Fingerprint to prevent SMS pumping attacks, where fraudsters use bots to repeatedly trigger one-time passcode (OTP) messages or verification texts to many phone numbers in order to test stolen numbers or abuse your SMS gateway for profit.

You'll begin with a starter app that includes a mock account creation page and a basic flow to send an SMS verification code. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to detect and block automated SMS verification requests.

By the end, you'll have a sample app that rejects SMS-pumping bots and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

<Note>
  This tutorial requires the Bot Detection Smart Signal, which is only available on paid plans.
</Note>

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor:

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `sms-pumping` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Account creation page" />

    <Tree.File name="index.js - Front-end logic for SMS requests" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="server.js - Serves static files and SMS endpoint" />

    <Tree.File name="sms.js - SMS pumping prevention logic" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000/) to view the mock account creation page from the starter app. You can test the basic flow by entering an email and phone number, then clicking **Send code via SMS**.
7. Then try triggering SMS requests using the included headless bot script `test-bot.js`. While the app is running, execute `node test-bot.js` and observe that the automated script successfully requests SMS codes. By default, the server does not distinguish between bots and real users:

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Send code via SMS**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the account creation payload. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including bot detection and other signals.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Send code via SMS** button already has an event handler for submitting the account details. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the payload to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
submitBtn.addEventListener("click", async () => {
	// ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/send-sms", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name,
        phone,
        eventId,
      }),
    });

	// ...
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your server-side account creation logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and Bot Detection [Smart Signal](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file defines the API routes for the app. Update the `/api/send-sms` route there to also extract `eventId` from the request body and pass it into the `sendSMS` function:

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/send-sms", async (req, reply) => {
  const { name, phone, eventId } = req.body;
  const result = await sendSMS({ name, phone, eventId });
  return reply.send(result);
});
```

2. The `server/sms.js` file contains the logic for handling SMS verification requests. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`:

```javascript server/sms.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `sendSMS` function to also extract `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/sms.js theme={"theme":"github-dark-dimmed"}
export async function sendSMS({ name, phone, eventId }) {
  if (!name || !phone) {
    return { success: false, message: "Name and phone number are required." };
  }

  const event = await fpServerApiClient.getEvent(eventId);

  sendVerificationCode(phone);

  return {
    success: true,
    message: "A verification code has been sent to your phone.",
  };
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block SMS pumping bots

SMS pumping attacks rely heavily on automated account creations, so rejecting bots outright can stop the abuse. Fingerprint returns `not_detected` if no bot activity is found, `good` for known bots, like search engines, and `bad` for other automation tools. Any visitor identification that does not return `not_detected` can be blocked from sending SMS codes.

1. Continuing in the `sendSMS` function in `server/sms.js`, check the bot signal returned in the `event` object and block bots:

```javascript server/sms.js theme={"theme":"github-dark-dimmed"}
export async function sendSMS({ name, phone, eventId }) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, message: "SMS sending failed." };
  }

  // ...
}
```

You can also add [Suspect Score](/docs/suspect-score) as a secondary layer. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload, helping to identify suspicious activity. While you may not normally block SMS requests based only on a high risk score, you could flag them for review, modify rate-limits, or require additional verification.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the request if it exceeds a chosen threshold (for example, 20):

```javascript server/sms.js theme={"theme":"github-dark-dimmed"}
export async function sendSMS({ name, phone, eventId }) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, message: "SMS verification failed." };
  }

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, message: "SMS verification failed." };
  }

  // ...
}
```

## 6. Recognize repeat offenders by visitor ID

As a secondary measure, you can log the visitor ID along with each SMS verification request to spot suspicious activity. This lets you recognize and block the same device even if they clear cookies, change IPs, or rotate phone numbers.

Note: The starter app includes a SQLite database with this table already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
sms_codes – Stores SMS verification attempts and associated visitor IDs
  id INTEGER PRIMARY KEY AUTOINCREMENT
  visitorId TEXT
  phone TEXT NOT NULL
  code TEXT NOT NULL
  createdAt INTEGER NOT NULL
  expiresAt INTEGER NOT NULL
```

1. Add a new helper function to the bottom of the `server/sms.js` file to check how many SMS codes have been sent in the last 24 hours for a specific `visitor_id`:

```javascript server/sms.js theme={"theme":"github-dark-dimmed"}
// Count visitor's SMS code requests sent in the last 24 hours
function countRecentSMSRequests(visitorId) {
  const since = Date.now() - 24 * 60 * 60 * 1000;

  const row = db
    .prepare(
      `SELECT COUNT(*) AS count
       FROM sms_codes
       WHERE visitorId = ? AND createdAt >= ?`,
    )
    .get(visitorId, since);

  return row.count;
}
```

2. Also update the existing `sendVerificationCode` helper function to accept and use the `visitorId`:

```javascript server/sms.js theme={"theme":"github-dark-dimmed"}
// Generate, save, and send a random 6-digit verification code
function sendVerificationCode(phone, visitorId) {
  const code = Math.floor(100000 + Math.random() * 900000).toString();
  const createdAt = Date.now();
  const expiresAt = createdAt + 1000 * 60 * 10; // 10 minutes

  // No SMS integration in the tutorial. Just pretend. ;)
  console.log(`Pretending to send SMS to ${phone}`);

  db.prepare(
    "INSERT INTO sms_codes (visitorId, phone, code, createdAt, expiresAt) VALUES (?, ?, ?, ?, ?)",
  ).run(visitorId, phone, code, createdAt, expiresAt);
}
```

3. Update `sendSMS` to retrieve the `visitor_id`, and use it to check for an unusually high volume of recent SMS code requests made by the visitor and when saving a new code:

```javascript server/sms.js theme={"theme":"github-dark-dimmed"}
export async function sendSMS({ name, phone, eventId }) {
  // ...

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, message: "SMS verification failed." };
  }

  const visitorId = event.identification.visitor_id;

  if (countRecentSMSRequests(visitorId) >= 5) {
    console.error("Too many SMS verification codes sent in the last 24 hours.");
    return { success: false, message: "SMS verification failed." };
  }

  sendVerificationCode(phone, visitorId);

  return {
    success: true,
    message: "A verification code has been sent to your phone.",
  };
}
```

Together with the bot detection Smart Signal, this allows you to protect your verification flow and prevent SMS pumping attacks. No matter which phone number is used, you can monitor request velocity and tie activity back to the same browser or device. You can extend it by analyzing additional signals, changing rate limit thresholds, or varying your response based on risk.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error checking, and actual SMS sending that align with
  your production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full verification flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Try requesting a code by entering a name and phone number and clicking **Send code via SMS**. You should see a success response.
3. If you request SMS verification five times, additional attempts from the same device will be blocked based on the recent-code check. Open the page in incognito mode to see that you are still blocked since Fingerprint still recognizes your browser with the same visitor ID.
4. While your demo is running, run the included headless bot test script from the `sms-pumping` folder. This will attempt to trigger SMS sends using a headless browser, which will be flagged by the Bot Detection signal and rejected:

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

*Note: If you encounter errors launching the automated browser, make sure you have the testing browser installed:*

```bash Terminal theme={"theme":"github-dark-dimmed"}
npx puppeteer browsers install chrome
```

## Next steps

You now have a working verification flow that blocks SMS pumping attacks with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your business policies, or layer in additional defenses or step-up verification.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Survey Fraud
Source: https://docs.fingerprint.com/docs/survey-fraud-use-case-tutorial

Learn how to prevent survey fraud and ensure data quality

## Overview

This tutorial shows how to implement Fingerprint to prevent survey fraud, where participants try to claim an incentive multiple times, use fake identities, or use devices that show signs of automation or tampering.

You'll begin with a starter app that includes a mock survey page and a basic submission flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to check if they've already submitted the survey. Additionally, you'll see how to use Smart Signals to block or flag automated or suspicious devices submitting responses. This way, you can flag or block repeat submissions from the same device or suspicious sources.

By the end, you'll have a sample app that detects duplicate or high-risk survey submissions and can be customized to fit your use case and business rules.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `survey-fraud` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Survey form" />

    <Tree.File name="index.js - Front-end logic to handle survey submissions" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="server.js - Serves static files and survey endpoint" />

    <Tree.File name="survey.js - Survey fraud detection logic" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000/) to view the mock survey page from the starter app. You can test out the basic flow by filling in the fields and clicking **Submit survey**. You'll notice you can submit multiple responses by simply changing the email address.

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Submit survey**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the survey data. The server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including the verified visitor ID and risk signals such as browser tampering or bot activity.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Submit survey** button already has an event handler set up for sending a survey submission. Inside this handler, request visitor identification from Fingerprint using the `get()` method and include the returned `event_id` when sending the survey to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
submitBtn.addEventListener("click", async () => {
  // ...
  const q4El = document.getElementById("q4");

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  const data = {
    firstName: firstNameEl.value,
    email: emailEl.value,
    q1: q1El.value,
    q2: q2Selected ? q2Selected.value : null,
    q3: q3Selected ? q3Selected.value : null,
    q4: q4El.value,
    eventId,
  };

  // ...
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your survey submission logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the trusted visitor ID and [Smart Signals](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file already defines API routes for the app. The `/api/survey` route passes the request body to the `submitSurvey` function defined in `server/survey.js`. Because the frontend now sends `eventId` in the payload, that value will be available in the body when `submitSurvey` runs.

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/survey", async (req, reply) => {
  const result = await submitSurvey(req.body);
  return reply.send(result);
});
```

2. The `server/survey.js` file contains the logic for handling survey submissions. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/survey.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `submitSurvey` function to also extract the `eventId` from the passed request body and use it to fetch the full identification event details from Fingerprint:

```javascript server/survey.js theme={"theme":"github-dark-dimmed"}
export async function submitSurvey(body) {
  const { email, eventId } = body;

  const event = await fpServerApiClient.getEvent(eventId);

  if (checkForDuplicateSubmission(email)) {
    return { success: false, message: "Duplicate survey submission." };
  }

  const saveResult = saveSurveySubmission(body);
  if (!saveResult.success) return saveResult;

  return { success: true, message: "Survey submitted successfully." };
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, and Smart Signals like bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block bots and suspicious devices

<Note>
  This optional step uses the Bot Detection and Suspect Score Smart Signals, which are only
  available on paid plans.
</Note>

A simple but powerful way to prevent fraudulent survey submissions is to block automated responses coming from bots. The `event` object includes the [Bot Detection Smart Signal](https://fingerprint.com/products/bot-detection/) that flags automated activity, making it easy to reject bot traffic.

This signal returns `good` for known bots like search engines, `bad` for automation tools, headless browsers, or other signs of automation, and `not_detected` when no bot activity is found.

1. Continuing in the `submitSurvey` function in `server/survey.js`, check the bot signal returned in the `event` object:

```javascript server/survey.js theme={"theme":"github-dark-dimmed"}
export async function submitSurvey(body) {
  const { email, eventId } = body;

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, message: "Survey submission failed." };
  }

  // ...
}
```

You can also use Fingerprint's [Suspect Score](/docs/suspect-score) to flag high-risk survey submissions. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload and can help identify suspicious or manipulative activity.

While you typically wouldn't reject a submission based only on this score, this example shows how you might include it. In production, you might instead flag the response for review or require an extra verification step before issuing the incentive.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the submission if it exceeds a chosen threshold (for example, 20):

```javascript server/survey.js theme={"theme":"github-dark-dimmed"}
export async function submitSurvey(body) {
  const { email, eventId } = body;

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";
  if (botDetected) {
    console.error("Bot detected.");
    return { success: false, message: "Survey submission failed." };
  }

  const suspectScore = event.suspect_score || 0;
  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, message: "Survey submission failed." };
  }

  // ...
}
```

## 6. Prevent multiple survey submissions per visitor

Next, use the trusted visitor ID from the `event` object to enforce a one-response-per-visitor rule. If the same visitor ID tries to submit another survey to claim an additional reward, reject the submission. In production, you may choose to allow a limited number of responses per visitor, require additional verification, or flag repeat participants for review.

Note: The starter app includes a SQLite database with a table already created for you:

```text SQLite database tables theme={"theme":"github-dark-dimmed"}
survey_submissions - Stores survey responses
	id INTEGER PRIMARY KEY AUTOINCREMENT
	visitorId TEXT
	firstName TEXT
	email TEXT
	q1 TEXT
	q2 TEXT
	q3 TEXT
	q4 TEXT
	createdAt INTEGER
```

1. Update the existing duplicate-submission helper function at the bottom of `server/survey.js` so it checks both the email address *and* the `visitorId`. This ensures a visitor cannot submit again even if they change their email:

```javascript server/survey.js theme={"theme":"github-dark-dimmed"}
// Check for duplicate submission
function checkForDuplicateSubmission(email, visitorId) {
  const submission = db
    .prepare(
      `SELECT * FROM survey_submissions 
       WHERE email = ? OR visitorId = ?`,
    )
    .get(email, visitorId);

  return submission ? true : false;
}
```

2. Update `submitSurvey` to retrieve the `visitorId`, use it to enforce the one-submission-per-visitor rule, and record successful survey submissions. Also add the `visitorId` to the body object before passing it to the `saveSurveySubmission` helper function:

```javascript server/survey.js theme={"theme":"github-dark-dimmed"}
export async function submitSurvey(body) {
  // ...

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { success: false, message: "Survey submission failed." };
  }

  const visitorId = event.identification.visitor_id;
  if (checkForDuplicateSubmission(email, visitorId)) {
    console.error("Duplicate survey submission detected.");
    return { success: false, message: "Duplicate survey submission." };
  }

  const saveResult = saveSurveySubmission({ ...body, visitorId });
  if (!saveResult.success) return saveResult;

  return { success: true, message: "Survey submitted successfully." };
}
```

3. Finally update the `saveSurveySubmission` function to extract and include the `visitorId` when saving survey responses, so it can be referenced later:

```javascript server/survey.js theme={"theme":"github-dark-dimmed"}
// Save survey submission
function saveSurveySubmission(data) {
  const { firstName, email, q1, q2, q3, q4, visitorId } = data;

  try {
    db.prepare(
      `
      INSERT INTO survey_submissions (visitorId, firstName, email, q1, q2, q3, q4, createdAt)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
    ).run(visitorId, firstName, email, q1, q2, q3, q4, Date.now());
    return { success: true };
  } catch (error) {
    console.error("Failed to save survey submission.", error);
    return { success: false, message: "Failed to save survey submission." };
  }
}
```

This gives you a system to detect and block survey submission fraud. You can extend it by limiting how often a visitor can submit responses, adding extra verification before rewarding high-value incentives, reviewing only recent submissions, and tailoring enforcement to your business rules.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error checking, and data handling that align with your
  production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full protected survey submission flow using the survey page.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000/):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Reset the database by clicking **Reset demo** at the bottom of the survey page.
3. Fill out the form and click **Submit survey**. The submission should be accepted.
4. Change some details, like the email, and submit again. The second submission will be rejected because the same visitor has already submitted the survey.
5. Open the page in an incognito window and try submitting again. Your visitor ID will remain the same, and the submission is still blocked.
6. Bonus: Test the flow using a headless browser or automation tool to see bot detection in action. A sample script is available in `test-bot.js`. While your app is running, run the script with `node test-bot.js` in your terminal and observe that automated submissions are denied.

## Next steps

You now have a working survey submission flow secured with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your incentive policies, or add additional checks for suspicious or high-risk respondents.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Svelte
Source: https://docs.fingerprint.com/docs/svelte



The [Fingerprint Svelte SDK](https://github.com/fingerprintjs/svelte) integrates Fingerprint into Svelte applications. It supports all capabilities of the JavaScript agent including a built-in [caching mechanism](/reference/js-agent-start-function#cache). See the [Svelte quickstart](/docs/svelte-quickstart) for a step-by-step guide to get started.

### How to install

Add `@fingerprint/svelte` as a dependency to your application.

<CodeGroup>
  ```shell NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/svelte
  ```

  ```shell Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/svelte
  ```

  ```shell PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/svelte
  ```
</CodeGroup>

Wrap your application (or component) in `FingerprintProvider`. You need to specify your public API key and other configuration options based on your chosen region and active integration.

```svelte Svelte theme={"theme":"github-dark-dimmed"}
// src/App.svelte
<script>
  import { FingerprintProvider } from '@fingerprint/svelte'
  import VisitorData from './VisitorData.svelte'

  const options = {
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://metrics.yourwebsite.com',
    region: 'us',
  }
</script>

<FingerprintProvider {options}>
  <VisitorData />
</FingerprintProvider>
```

Use the `useVisitorData` hook in your components to identify visitors.

```svelte Svelte theme={"theme":"github-dark-dimmed"}
// src/VisitorData.svelte
<script>
  import { useVisitorData } from '@fingerprint/svelte';
  const { getData, data, isLoading, error } = useVisitorData({ immediate: false });
</script>

<div>
  <button on:click={() => getData()}>Get visitor data</button>
  {#if $isLoading} Loading... {/if}
  {#if $error} {$error.message} {/if}
  {#if $data}
    <pre>{JSON.stringify($data, null, 2)}</pre>
  {/if}
</div>
```

### Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/svelte). The repository also contains [example applications](https://github.com/fingerprintjs/svelte/tree/main/examples) demonstrating the usage of the library.

### Migration guide for Svelte SDK v3.0.0

Version 3.0.0 of the Svelte SDK switches from JavaScript agent v3 to [JavaScript agent v4](/reference/migrating-from-v3-to-v4). It also adds Svelte 5 support (the `svelte` peer dependency is widened to `^4.0.0 || ^5.0.0`).

1. Install the new version of the package:

<CodeGroup>
  ```bash NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/svelte
  ```

  ```bash Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/svelte
  ```

  ```bash PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/svelte
  ```
</CodeGroup>

2. Update the provider import and options.

The default caching strategy has changed from `sessionStorage` caching to **no caching by default**, aligned with the underlying [JavaScript agent v4 default](/reference/js-agent-start-function#cache). To preserve the previous behavior, explicitly configure caching in the provider options (see example below).

```svelte Update provider imports and usage theme={"theme":"github-dark-dimmed"}
<script>
// [!code --:4]
  import {
    FpjsProvider,
    FingerprintJSPro,
  } from '@fingerprintjs/fingerprintjs-pro-svelte'
// [!code ++]
  import { FingerprintProvider } from '@fingerprint/svelte'

// [!code --:10]
  const options = {
    loadOptions: {
      apiKey: 'PUBLIC_API_KEY',
      endpoint: ['https://metrics.yourwebsite.com', FingerprintJSPro.defaultEndpoint],
      scriptUrlPattern: [
        'https://metrics.yourwebsite.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js',
        FingerprintJSPro.defaultScriptUrlPattern,
      ],
    },
  }
// [!code ++:8]
  const options = {
    cache: {
      storage: 'sessionStorage',
      duration: 3600,
    },
    apiKey: 'PUBLIC_API_KEY',
    endpoints: ['https://metrics.yourwebsite.com'],
  }
</script>
```

Also rename the component in your template from `FpjsProvider` to `FingerprintProvider`:

```svelte theme={"theme":"github-dark-dimmed"}
<FingerprintProvider {options}>
  <slot />
</FingerprintProvider>
```

3. Update `useVisitorData` calls and result field names:

```javascript Update visitor data usage theme={"theme":"github-dark-dimmed"}
// [!code --]
import { useVisitorData } from '@fingerprintjs/fingerprintjs-pro-svelte';
import { useVisitorData } from '@fingerprint/svelte'; // [!code ++]

// [!code --:4]
const { getData, data, isLoading, error } = useVisitorData(
  { extendedResult: true },
  { immediate: false },
);
// `immediate` can now be set in the first argument // [!code ++:2]
const { getData, data, isLoading, isFetched, error } = useVisitorData({ immediate: false });

// [!code --:2]
const { visitorId, requestId } = await getData();
console.log(visitorId, requestId);
// [!code ++:2]
const { visitor_id, event_id } = await getData();
console.log(visitor_id, event_id);
```

The v4 agent uses snake\_case field names. `requestId` is now `event_id`, and `visitorId` is now `visitor_id`.


# Svelte Quickstart
Source: https://docs.fingerprint.com/docs/svelte-quickstart

Get started using the Fingerprint Svelte SDK

## Overview

In this quickstart, you'll add Fingerprint to a new [Svelte 5](https://svelte.dev/) project and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend integration. You'll install the [Fingerprint Svelte SDK](/docs/svelte) and initialize the JavaScript agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of [Svelte 5](https://svelte.dev/) and JavaScript

<Note>
  This quickstart only covers the **frontend setup**. You'll need a [backend
  server](/reference/server-sdks) to receive and process the device identification event to enable
  fraud detection. Check out one of the [backend quickstarts](/docs/server-quickstarts-overview)
  after completing this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the JavaScript agent.

## 2. Set up your project

To get started, scaffold a new Svelte app. If you already have a project you want to use, you can skip to the next section.

1. Create a new Vite project with the Svelte template:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm create vite@latest fingerprint-svelte-quickstart -- --template svelte
cd fingerprint-svelte-quickstart
npm install
```

2. Open the `fingerprint-svelte-quickstart` folder in your code editor and you're ready to go! To run your project, run:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

3. In your browser, go to [http://localhost:5173](http://localhost:5173/) (Vite's default), and you should see the Vite welcome page.

## 3. Set up your account creation form

1. Before adding Fingerprint, create a new component at `src/lib/CreateAccountForm.svelte` with the following:

```svelte src/lib/CreateAccountForm.svelte theme={"theme":"github-dark-dimmed"}
<script>
  // Logic will be added later
</script>

<div class="wrapper">
  <h1>Create an account</h1>
  <div class="input-group">
    <label for="username">Username</label>
    <input
      id="username"
      bind:value={username}
      type="text"
      placeholder="Username"
      required
    />
  </div>
  <div class="input-group">
    <label for="password">Password</label>
    <input
      id="password"
      bind:value={password}
      type="password"
      placeholder="Password"
      required
    />
  </div>
  <button disabled={$isLoading} onclick={handleSubmit}>
    {$isLoading ? "Loading…" : "Create Account"}
  </button>
</div>

<style>
  .wrapper {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    min-height: 100vh;
    gap: 1rem;
    padding: 1rem;
  }

  input {
    width: 100%;
    padding: 0.5rem;
    border: 1px solid #ccc;
    border-radius: 4px;
  }

  .input-group {
    width: 100%;
    display: flex;
    flex-direction: column;
    align-items: flex-start;
    gap: 0.5rem;
  }

  button {
    background-color: #f35b22;
    color: #fff;
    border: none;
    padding: 0.75rem 1.5rem;
    border-radius: 4px;
    cursor: pointer;
  }

  button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }
</style>
```

2. Import and add the component to your main app in `src/App.svelte`. You can replace the whole file with:

```svelte src/App.svelte theme={"theme":"github-dark-dimmed"}
<script>
  import CreateAccountForm from "./lib/CreateAccountForm.svelte";
</script>

<CreateAccountForm />
```

## 4. Install and initialize the JavaScript agent

1. To integrate Fingerprint into your Svelte app, first add the Fingerprint Svelte SDK via npm:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/svelte
```

*Note: This quickstart is written for version 3.x of the Fingerprint Svelte SDK.*

2. Now that the Svelte SDK is installed, you can import and configure the Fingerprint provider. Update `App.svelte` and add the following to the `<script>` block:

```svelte src/App.svelte theme={"theme":"github-dark-dimmed"}
<script>
  import CreateAccountForm from "./lib/CreateAccountForm.svelte";
  import { FingerprintProvider } from "@fingerprint/svelte"; // [!code ++]

  const options = { // [!code ++:5]
    apiKey: "PUBLIC_API_KEY",
    region: "us", // Ensure this matches your workspace region
    // For more information, see https://docs.fingerprint.com/docs/regions
  };
</script>
```

3. Replace `PUBLIC_API_KEY` with your actual public API key from the [Fingerprint dashboard](https://dashboard.fingerprint.com/api-keys).

*Note: For production, consider using* [*Vite Env Variables*](https://vite.dev/guide/env-and-mode) *to configure the key.*

4. Wrap `<CreateAccountForm />` with the `FingerprintProvider` component:

```svelte src/App.svelte theme={"theme":"github-dark-dimmed"}
<FingerprintProvider {options}>
  <CreateAccountForm />
</FingerprintProvider>
```

## 5. Trigger visitor identification

Now that the JavaScript agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps the **Create Account** button.

When making the visitor identification request, you will receive a visitor ID as well as an event ID. Instead of using the visitor ID returned directly on the frontend (which could be tampered with), you'll send the event ID to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. Within the empty script tags in `CreateAccountForm.svelte`, declare `username` and `password` as reactive variables to track your form inputs, and import the Fingerprint `useVisitorData` hook:

```svelte src/lib/CreateAccountForm.svelte theme={"theme":"github-dark-dimmed"}
<script>
  import { useVisitorData } from "@fingerprint/svelte";

  let username = $state("");
  let password = $state("");
</script>
```

2. Initialize `useVisitorData` and access the returned values you'll need:

```svelte src/lib/CreateAccountForm.svelte theme={"theme":"github-dark-dimmed"}
<script>
  import { useVisitorData } from "@fingerprint/svelte";

  let username = $state("");
  let password = $state("");

  const { isLoading, getData } = useVisitorData({ immediate: false }); // [!code ++]
</script>
```

This gives you:

* `getData()`: A function to trigger visitor identification on demand.
* `isLoading`: A flag to monitor visitor identification progress.

By setting `immediate` to `false` you're triggering device identification only when needed with the `getData()` method.

*Check the* [*Svelte SDK reference*](https://fingerprintjs.github.io/svelte/) *for available useVisitorData options.*

3. Define the submit handler to trigger identification when the user clicks **Create Account**:

```javascript theme={"theme":"github-dark-dimmed"}
async function handleSubmit() {
  const { visitor_id, event_id } = await getData();

  console.log('Visitor ID:', visitor_id);
  console.log('Event ID:', event_id);

  // Send the event_id to your server
  // await fetch("/api/create-account", {
  //   method: "POST",
  //   headers: { "Content-Type": "application/json" },
  //   body: JSON.stringify({
  //     username,
  //     password,
  //     event_id,
  //   }),
  // });
}
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

In this function:

* `getData()` is being called and Fingerprint is analyzing the visitor's browser; the result includes `visitor_id` and `event_id`.
* You can send the `event_id` to your backend along with the username and password for your fraud detection logic.

## 6. Test the app

1. If your dev server isn't already running, start it with:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. In your browser, go to [http://localhost:5173](http://localhost:5173) (Vite's default).
3. If you have any ad blockers, turn them off for localhost. View the [documentation](/docs/protecting-the-javascript-agent-from-adblockers) to learn how to protect your Fingerprint implementation from ad blockers in production.
4. Enter a username and password, then click **Create Account**.
5. Open the developer console in your browser and you should see the `visitor_id` and `event_id` in the output:

```text Output theme={"theme":"github-dark-dimmed"}
Visitor ID: JkLmNoPqRsTuVwXyZaBc
Event ID: 1234566477745.abc1GS
```

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the event ID to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information data and use it to make decisions and prevent fraud.

Check out these related resources:

* [Svelte SDK reference](https://fingerprintjs.github.io/svelte/)
* [Svelte SDK GitHub repository](https://github.com/fingerprintjs/svelte)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Troubleshooting Unexpected Usage Spikes
Source: https://docs.fingerprint.com/docs/troubleshooting-unexpected-usage-spikes

If you're seeing a sudden spike in Fingerprint usage, it usually comes down to two main causes: implementation issues or malicious traffic. This guide will help you quickly diagnose and resolve the issue.

## Quick Checklist

* **Check for recent code changes** - Spikes often correlate with a recent deployment. Review any updates that may have changed when or where the Fingerprint agent is called.
* **Check for caching** - Without caching, repeat visits or user actions can trigger multiple identification requests. Ensure visitor IDs are cached appropriately using `sessionStorage` or `localStorage`.
* **Audit for duplicate calls** - Look for React `useEffect` calls missing dependency arrays, or code that triggers `get()` multiple times per session.
  * The JavaScript agent only bills for `get()` calls. Confirm you’re calling it only when the visitor ID is needed, and not on every page load or render.
* **Review the "Insights" section** - On the [Overview](https://dashboard.fingerprint.com/overview) page of your Fingerprint dashboard, adjust the trend chart by selecting the "events per visitor" metric in the drop down. A noticeable increase could indicate your code is sending more identification requests than before.
* **Inspect bot traffic** - Use the [Bots & AI agents](https://dashboard.fingerprint.com/bot-detection) page to check for bot activity. Spikes caused by scraping or browser automation suggest abuse, not implementation error.
* **Secure your API key** - Check if your API key is used on unknown domains or apps. Set up [request filtering](/docs/request-filtering) to block unwanted domains, headers, or IPs.
* **Contact support** - If you’re still unsure, reach out to [Support](https://fingerprint.com/support/) or review our [bill forgiveness](/docs/billing#how-am-i-protected-from-overpaying) policy.

## Implementation Related Spike

These spikes are usually caused by integration issues. Clues include a spike following a recent code change or usage increasing alongside user activity. For example, if usage scales with traffic but seems higher than expected, it may indicate an implementation issue - such as more identification calls per user than intended. Common causes include missing caching, duplicate calls, or unintentional triggers.

### Missing Visitor ID Caching

* Without caching your visitor ID, each page load or user action can generate a new request, increasing your API usage.
* Choosing whether to cache depends on your use case and risk tolerance:
  * If your use case demands highly accurate identification, we recommend identifying the visitor [only when needed](/docs/identify-visitors#timing-identification-requests) and always using a fresh visitor ID *without* caching.
  * For less sensitive scenarios, caching can significantly reduce redundant calls and improve performance.
* You can store the visitor ID in `sessionStorage` (recommended) or `localStorage` to reuse the ID for up to 1 hour and reduce redundant calls.

Read: [Caching Visitor ID](/docs/identify-visitors#caching-the-visitor-id)

### Duplicate Calls from Loops

* Common in single-page applications (SPAs) where component re-renders or navigation triggers extra calls.
* In React, missing a dependency array in `useEffect` can cause `get()` to be called on every render.
* Use the [React SDK](/docs/react) to manage this more easily.

### Unintended Calls to Fingerprint

* For the JavaScript agent, `start()` requests are not billed, but `get()` requests are.
  * Only call `get()` when the visitor ID will be used by your application.
* Avoid triggering identification on every render or page view.
* Visit the [Optimizing JavaScript Agent Usage](/docs/optimize-javascript-agent#only-use-the-javascript-agent-where-you-need-it) page to learn more about common use cases and when to make the `get()` request.

## Malicious Traffic or Bot-Driven Spike

These spikes often happen suddenly and without any recent deployments. Look for unusual traffic patterns - like bursts of activity or off-hour usage. Use Smart Signals or the Server API to review recent identification events. A high number of “bad bot” detections typically points to automated abuse, not an integration issue.

### Bot Traffic

* Visit the **[Bots & AI agents](https://dashboard.fingerprint.com/bot-detection)** page to view traffic flagged as bots.
* A sudden increase in the **Scraping** or **Browser Automation** categories can indicate scraping or automated abuse.
* Use the [Bots and AI agents](/docs/dashboard-bots-ai-agents) guide to narrow the spike down to a specific bot, provider, or country.
* Use this information to adjust filters or rate-limiting rules in your app.

Some helpful resources to learn more:

* [Browser Bot detection](/docs/bot-detection/overview)
* [Bot detection: How to block bad bots in 2025](https://fingerprint.com/blog/bot-detection/)
* [How to Identify and Block Bots in Your Firewall](https://fingerprint.com/blog/bot-detection-powered-application-firewall/)
* [Mitigating bad bots at WAF level through Cloudflare](/docs/cloudflare-integration-blocking-ips-and-origins)

### Public API Key Misuse

* Public API keys are visible in client-side code and can potentially be leaked or copied.
* Check whether your API key is being used on unknown domains or in unauthorized mobile apps.
* It’s good practice to restrict your API key to only the domains, headers, or IP addresses where legitimate traffic is expected.
* Set up [**Request Filtering**](https://dashboard.fingerprint.com/traffic-rules) in the dashboard to prevent unwanted usage and protect your billing.

Protect your Public API key:

* [Request Filtering for Websites](/docs/request-filtering-for-websites)
* [Mobile App Filtering](/docs/mobile-app-filtering)
* [Search Bot Filtering](/docs/search-bots-filtering)
* [Network Filtering](/docs/network-request-filtering)

## Deep Dive: Exporting and Analyzing Identification Data

If you want to dig deeper into a spike, exporting your data to CSV allows for a more granular investigation. Here's how:

1. **Check usage trends** - Go to the [Overview](https://dashboard.fingerprint.com/overview?period=last_30_days) page and review API usage over the past 30 days.
2. **Identify the spike window** - Pinpoint the spike date, and include the day before and after.
3. **Filter identification events** - Navigate to the [Identification](https://dashboard.fingerprint.com/events) page and apply a date filter for that window.
4. **Export the data** - Use the export option to download a CSV file of events.
5. **Analyze usage patterns** - Use the CSV to review the data grouped by:
   * `identification.visitor_id`
   * `linked_id` or `tags`
   * `url`
   * `ip_info.geolocation.country_name`

This can help surface unusual usage patterns, like excessive requests from a single user or unexpected geographies.

## Next Steps and Support

* If you can’t resolve the issue on your own, please reach out to [support](https://fingerprint.com/support/).
* You may be eligible for partial [bill forgiveness](/docs/billing#how-am-i-protected-from-overpaying) in cases of unintentional spikes or confirmed malicious activity.

**Important:** Forgiveness can only be applied to your **most recent completed invoice** (i.e. the last completed billing cycle). Older invoices are not eligible, even if they experienced a spike.

***

[Billing and account limits explained](/docs/billing)


# Usage with server-side rendering frameworks
Source: https://docs.fingerprint.com/docs/usage-with-server-side-rendering-frameworks

Learn how to use Fingerprint with server-side rendering frameworks.

You can use Fingerprint with any frontend framework or meta-framework, whether your page is rendered in the browser, on the server, or statically generated. You just need to ensure that loading the Fingerprint JavaScript agent and performing the **visitor analysis happens on the client and not on the server**.

Since fingerprinting relies on signals from various browser APIs it cannot run outside the browser. Each (meta-)framework has its own way of specifying which code is client-only. If you use any of our [client SDKs](/docs/frontend-libraries), it typically handles this for you automatically, but the details can vary depending on the SDK. You can find more information in the respective framework sections below.

This guide will demonstrate the common patterns for Next.js, Nuxt, Gatsby, and Angular SSR.

## Next.js

<Tip>
  **Using our React SDK**

  We recommend using the [Fingerprint React SDK](https://github.com/fingerprintjs/react) which exposes the `getData` function and its result in a `useVisitorData()` hook. Since hooks cannot be used inside server components or server-side functions, you are forced to do the right thing by default.

  ```typescript TypeScript wrap theme={"theme":"github-dark-dimmed"}
  import { useVisitorData } from '@fingerprint/react';

  export default function Page() {
    const { data } = useVisitorData();
    return <div>Your visitor ID: {data?.visitor_id}</div>;
  }
  ```
</Tip>

In Next.js, the boundary between client and server is defined differently depending on if you are using the `pages` directory (how Next.js worked traditionally) or the new `app` directory (introduced in Next.js 13).

### The `pages` directory

You can import and use the JavaScript agent inside components but not inside `getStaticProps` or `getServerSideProps`. You can still use the JavaScript agent on a page that is server-side rendered or statically generated, just do it in the component itself.

> Note: In this context, "inside the component" means inside an event handler (e.g., `onClick`), a life cycle method (e.g., `componentDidMount`), or an effect (e.g., `useEffect`). Calling the JavaScript agent at the base of the component definition or its render method would also result in `document is not defined` error on server-side rendered pages.

Examples of correct JavaScript agent usage in a static page (with or without static props) and a server-rendered page:

<CodeGroup>
  ```typescript src/pages/default.tsx wrap theme={"theme":"github-dark-dimmed"}
  import Fingerprint, { type GetResult } from '@fingerprint/agent';
  import { useEffect, useState } from 'react';

  export default function FingerprintPage() {
    const [fingerprintData, setFingerprintData] = useState<GetResult | null>(null);

    // ✅ This works, effects run in the browser only
    useEffect(() => {
      (async () => {
        const fp = Fingerprint.start({
          apiKey: 'PUBLIC_API_KEY',
          endpoints: 'CUSTOM_SUBDOMAIN_URL',
        });

        const data = await fp.get();
        setFingerprintData(data);
      })();
    }, []);

    return <div>Your visitor ID: {fingerprintData?.visitor_id}</div>;
  }
  ```

  ```typescript src/pages/staticPage.tsx wrap theme={"theme":"github-dark-dimmed"}
  import Fingerprint, { GetResult } from '@fingerprint/agent';
  import { GetStaticProps, InferGetStaticPropsType } from 'next';
  import { useEffect, useState } from 'react';

  export default function ServerSide({ message }: InferGetStaticPropsType<typeof getStaticProps>) {
    const [fingerprintData, setFingerprintData] = useState<GetResult | null>(null);

    // ✅ This works, effects run in the browser only
    useEffect(() => {
      (async () => {
        const fp = Fingerprint.start({
          apiKey: 'PUBLIC_API_KEY',
          endpoints: 'CUSTOM_SUBDOMAIN_URL',
        });

        const data = await fp.get();
        setFingerprintData(data);
      })();
    }, []);

    return (
      <>
        <p>{message}</p>
        <p> Your visitor ID: {fingerprintData?.visitor_id}</p>
      </>
    );
  }

  export const getStaticProps: GetStaticProps<{
    message: string;
  }> = async () => {
    return { props: { message: 'This page was statically generated' } };
  };
  ```

  ```typescript src/pages/serverSide.tsx wrap theme={"theme":"github-dark-dimmed"}
  import Fingerprint, { GetResult } from '@fingerprint/agent';
  import { GetServerSideProps, InferGetServerSidePropsType } from 'next';
  import { useEffect, useState } from 'react';

  export default function ServerSide({ message }: InferGetServerSidePropsType<typeof getServerSideProps>) {
    const [fingerprintData, setFingerprintData] = useState<GetResult | null>(null);

    // ✅ This works, effects run in the browser only
    useEffect(() => {
      (async () => {
        const fp = Fingerprint.start({
          apiKey: 'PUBLIC_API_KEY',
          endpoints: 'CUSTOM_SUBDOMAIN_URL',
        });

        const data = await fp.get();
        setFingerprintData(data);
      })();
    }, []);

    return (
      <>
        <p>{message}</p>
        <p> Your visitor ID: {fingerprintData?.visitor_id}</p>
      </>
    );
  }

  export const getServerSideProps: GetServerSideProps<{
    message: string;
  }> = async () => {
    return { props: { message: 'This page was rendered server side' } };
  };
  ```
</CodeGroup>

Some examples of antipatterns:

<CodeGroup>
  ```typescript src/pages/serverAntipattern.tsx wrap theme={"theme":"github-dark-dimmed"}
  import Fingerprint from "@fingerprint/agent";

  // This is an antipattern
  // It's not possible to call Fingerprint agent on the server
  // It will result in `document is not defined` ReferenceError
  export default function AntipatternGetServerSidePropsPage({ data }) {
    return <pre>{JSON.stringify(data)}</pre>;
  }

  // ❌ This won't work, this code will run server-side at runtime
  export async function getServerSideProps() {
    let data;
    const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: 'CUSTOM_SUBDOMAIN_URL',
    });

    fp.get()
      .then((result) => {
        data = result;
      });

    return {
      props: {
        data: data ?? "document is not defined",
      },
    };
  }
  ```

  ```typescript src/pages/staticAntipattern.tsx wrap theme={"theme":"github-dark-dimmed"}
  import Fingerprint from "@fingerprint/agent";

  // This is an antipattern
  // It's not possible to call Fingerprint agent on the server
  // It will result in `document is not defined` ReferenceError
  export default function AntipatternGetStaticPropsPage({ data }) {
    return <pre>{JSON.stringify(data)}</pre>;
  }

  // ❌ This won't work, this code will run server-side at build time
  export async function getStaticProps() {
    let data;
    const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: 'CUSTOM_SUBDOMAIN_URL',
    });

    fp.get()
      .then((result) => {
        data = result;
      });

    return {
      props: {
        data: data ?? "document is not defined",
      },
    };
  }
  ```

  ```typescript src/pages/insideRenderAntipattern.tsx wrap theme={"theme":"github-dark-dimmed"}
  import Fingerprint from '@fingerprint/agent';
  import { GetServerSideProps, InferGetServerSidePropsType } from 'next';

  export default function AntipatternRenderMethod({
    message,
  }: InferGetServerSidePropsType<typeof getServerSideProps>) {

    // ❌ This won't work, this code will run server-side at runtime
    const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: 'CUSTOM_SUBDOMAIN_URL',
    });

    fp.get()
      .then((result) => {
        console.log(result.visitor_id);
      });

    return (
      <>
        <p>{message}</p>
      </>
    );
  }

  export const getServerSideProps: GetServerSideProps<{
    message: string;
  }> = async () => {
    return { props: { message: 'This page was rendered on the server at runtime.' } };
  };
  ```
</CodeGroup>

### The `app` directory

All components inside the `app` directory are [server-side by default](https://nextjs.org/docs/app/building-your-application/rendering/server-components). To use the JavaScript agent, put it in a Client Component that begins with the `'use client';` directive, and call the agent from `useEffect` or an event handler. This lets the component use client-side React APIs while ensuring the Fingerprint call runs in the browser.

<CodeGroup>
  ```typescript src/app/yourPage/visitorData.tsx wrap theme={"theme":"github-dark-dimmed"}
  'use client';

  import Fingerprint, { GetResult } from '@fingerprint/agent';
  import { useEffect, useState } from 'react';

  export default function VisitorData() {
    const [fingerprintData, setFingerprintData] = useState<GetResult | null>(null);

    // ✅ This works, effects run in the browser only and
    // you can use useEffect here because of the `use client` directive
    useEffect(() => {
      (async () => {
        const fp = Fingerprint.start({
          apiKey: 'PUBLIC_API_KEY',
          endpoints: 'CUSTOM_SUBDOMAIN_URL',
        });

        const data = await fp.get();
        setFingerprintData(data);
      })();
    }, []);

    return (
      <>
        <div>Your visitor ID: {fingerprintData?.visitor_id}</div>
      </>
    );
  };
  ```

  ```typescript src/app/yourPage/page.tsx wrap theme={"theme":"github-dark-dimmed"}
  import VisitorData from './visitorData';

  export default async function ServerPage() {
    return (
      <main>
        <h1>This page in the `app` directory was rendered server-side.</h1>
        <VisitorData />
      </main>
    );
  }
  ```
</CodeGroup>

If you are using the [Fingerprint React SDK](https://github.com/fingerprintjs/react), you need to wrap your app (or the part of it that uses Fingerprint) inside `FingerprintProvider`. You can do this by putting the provider in a `layout.tsx` file. Since the provider uses Context under the hood, you either need to turn the entire layout into a client-side component with `'use client';` or wrap the `FingerprintProvider` inside a client component:

<CodeGroup>
  ```typescript src/components/MyFingerprintProvider.tsx wrap theme={"theme":"github-dark-dimmed"}
  'use client';

  import { FingerprintProvider } from '@fingerprint/react';
  import { PropsWithChildren } from 'react';

  export function MyFingerprintProvider({ children }: PropsWithChildren) {
    return (
      <FingerprintProvider
        apiKey="PUBLIC_API_KEY"
        endpoints="https://metrics.yourwebsite.com"
      >
        {children}
      </FingerprintProvider>
    );
  }
  ```

  ```typescript src/app/layout.tsx wrap theme={"theme":"github-dark-dimmed"}
  import { MyFingerprintProvider } from '../components/MyFingerprintProvider';

  export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
      <html>
        <head />
        <body>
          <MyFingerprintProvider>{children}</MyFingerprintProvider>
        </body>
      </html>
    );
  }
  ```

  ```typescript src/app/yourPage/visitorData.tsx wrap theme={"theme":"github-dark-dimmed"}
  'use client';

  import { useVisitorData } from '@fingerprint/react';

  export default function VisitorData() {
    const { data } = useVisitorData();
    return <div>Your visitor ID: {data?.visitor_id}</div>;
  }
  ```
</CodeGroup>

See the [Next.js documentation](https://beta.nextjs.org/docs) for more details on client and server-side rendering.

## Nuxt

<Tip>
  **Using our Vue SDK**

  Instead of importing the JavaScript agent directly, we recommend you take advantage of the [Fingerprint Vue SDK](/docs/vuejs), available as `@fingerprint/vue`. The same principle applies here:

  * Register Fingerprint as a *client-side* plugin by creating a `fingerprintjs.client.ts` file inside the `plugins` folder (the `client` suffix is important).
  * Wrap the component using Fingerprint inside the `<ClientOnly>` tag in your app template.

  See the [Vue SDK documentation](/docs/vuejs) for more details and examples.
</Tip>

When using Nuxt, make sure to import and call the Fingerprint JavaScript agent in client-side code only. For example, you can create a component that calls the JS client inside its `<script setup>` tag, then wrap the component inside `<ClientOnly>`.

<CodeGroup>
  ```vue app.vue wrap theme={"theme":"github-dark-dimmed"}
  <template>
    <div>
      <h1>This Nuxt page is rendered server-side by default</h1>
      <ClientOnly>
        <!-- ✅ This works, `VisitorData` will be rendered in the browser only
        thanks to the `ClientOnly` wrapper -->
        <VisitorData />
      </ClientOnly>
    </div>
  </template>
  ```

  ```vue VisitorData.vue theme={"theme":"github-dark-dimmed"}
  <script setup>
  import { ref } from 'vue';

  const visitorId = ref();
  const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY').then((Fingerprint) =>
    Fingerprint.start(),
  );

  fpPromise
    .then((fp) => fp.get())
    .then((result) => {
      visitorId.value = result.visitor_id;
    });
  </script>

  <template>
    <div>
      <p>Your visitor ID is {{ visitorId }}</p>
    </div>
  </template>
  ```
</CodeGroup>

Learn more in [Nuxt documentation](https://nuxt.com/docs/api/components/client-only).

## Gatsby

Similar to Next.js, you can use the Fingerprint JavaScript agent inside component effects, event handlers and lifecycle methods. Using it inside `getServerData()`, component render functions and other server-side code will not work.

<CodeGroup>
  ```typescript index.tsx wrap theme={"theme":"github-dark-dimmed"}
  import * as React from 'react';
  import type { PageProps } from 'gatsby';
  import Fingerprint, { type GetResult } from '@fingerprint/agent';

  const IndexPage: React.FC<PageProps> = () => {
    const [fingerprintData, setFingerprintData] = React.useState<GetResult | null>(null);

    // ✅ This works, effects run in the browser only
    React.useEffect(() => {
      (async () => {
        const fp = Fingerprint.start({
          apiKey: 'PUBLIC_API_KEY',
          endpoints: 'CUSTOM_SUBDOMAIN_URL',
        });

        const data = await fp.get();
        setFingerprintData(data);
      })();
    }, []);

    return (
      <main>
        <h1>This site was statically generated by Gatsby</h1>
        <p>Your visitor ID is {fingerprintData?.visitor_id}</p>
      </main>
    );
  };

  export default IndexPage;
  ```

  ```typescript serverDataAntipattern.tsx theme={"theme":"github-dark-dimmed"}
  import * as React from 'react';
  import type { PageProps } from 'gatsby';
  import Fingerprint from '@fingerprint/agent';

  const IndexPage: React.FC<PageProps> = (props) => {
    return (
      <main>
        <h1>This site was statically generated by Gatsby</h1>
        <p>Your visitor ID is {props.serverData.visitorData.visitor_id}</p>
      </main>
    );
  };

  // ❌ This will result in a `document is not defined` error
  export async function getServerData() {
    const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: 'CUSTOM_SUBDOMAIN_URL',
    });

    const visitorData = await fp.get();
    return { props: { visitorData } };
  }

  export default IndexPage;
  ```

  ```typescript renderMethodAntipattern.tsx theme={"theme":"github-dark-dimmed"}
  import * as React from "react";
  import type { PageProps } from "gatsby";
  import Fingerprint from "@fingerprint/agent";

  const IndexPage: React.FC<PageProps> = () => {
    // ❌ This results in `document is not defined` error
    // during static site generation
    const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: 'CUSTOM_SUBDOMAIN_URL',
    });

    fp.get()
      .then((result) => {
        console.log(result.visitor_id);
      });

    return (
      <main>
        <h1>This site was statically generated by Gatsby</h1>
      </main>
    );
  };

  export default IndexPage;
  ```
</CodeGroup>

See the [Gatsby documentation](https://www.gatsbyjs.com/docs/using-client-side-only-packages/) for more details and alternative approaches to running client-side-only code. For a smoother development experience, consider using the `useVisitorData()` hook from the [Fingerprint React SDK](https://github.com/fingerprintjs/react).

## Angular SSR

The [Fingerprint Angular SDK](https://github.com/fingerprintjs/angular) (`@fingerprint/angular`) does not initialize the JavaScript agent on the server. `FingerprintService` checks `isPlatformBrowser` internally, so server rendering will not run the agent. Call `getVisitorData()` from browser-only flows, such as hydrated user interactions, or handle the rejected promise if the method can run during SSR.

If you prefer to use the JavaScript agent directly instead of the Angular SDK, make sure to run Fingerprint only in the browser. You can inject the Angular-provided [`PLATFORM_ID`](https://angular.dev/api/core/PLATFORM_ID) constant and check it with [`isPlatformBrowser`](https://angular.dev/api/common/isPlatformBrowser):

```typescript app.ts theme={"theme":"github-dark-dimmed"}
import { isPlatformBrowser } from '@angular/common';
import { Component, signal, Inject, PLATFORM_ID } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import Fingerprint from '@fingerprint/agent';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  templateUrl: './app.html',
  styleUrls: ['./app.css'],
})
export class App {
  protected readonly title = signal('my-angular-app');
  visitorId?: string = 'Waiting...';

  constructor(@Inject(PLATFORM_ID) private platformId: Object) {
    if (isPlatformBrowser(this.platformId)) {
      this.getVisitorId();
    }
  }

  // ✅ Browser events run after hydration
  handler = () => {
    this.getVisitorId();
  };

  getVisitorId() {
    const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      endpoints: 'CUSTOM_SUBDOMAIN_URL',
    });

    fp.get().then((result) => {
      this.visitorId = result.visitor_id;
      console.log(result);
    });
  }
}
```

Learn more about server-side rendering in the [Angular SSR documentation](https://angular.dev/guide/ssr).

## Other frameworks

* **Astro** is a multi-page application framework where all pages are static by default with "islands" of client-side interactivity. Use Fingerprint inside an island. Read more about [Astro's island architecture](https://docs.astro.build/en/concepts/islands/).
* **Remix** is a React meta-framework similar to Next.js. For information on how to avoid running browser-only code on the server with Remix, see their [Module constraints documentation](https://v2.remix.run/docs/guides/constraints/#browser-only-code-on-the-server).
* **SvelteKit** is a Svelte meta-framework providing static generation and server-side rendering capabilities. You can run Fingerprint client-side only inside [event handlers](https://svelte.dev/docs/svelte/basic-markup#Events), lifecycle methods like [`onMount`](https://svelte.dev/docs/svelte/lifecycle-hooks#onMount) or by checking the `browser` constant in the [`@app/environment` module](https://svelte.dev/docs/kit/\$app-environment).

Regardless of the framework you use, the principle is the same. Fingerprint relies on browser-only APIs so you can only run it in the browser, not on the server.


# Use Case Tutorials
Source: https://docs.fingerprint.com/docs/use-case-tutorials-overview

Step-by-step tutorials for implementing Fingerprint in common fraud prevention scenarios

Use case tutorials are step-by-step guides that show how to implement Fingerprint to solve specific challenges, with complete sample applications you can run locally and adapt. Each includes a starter repository, integration instructions, and server-side logic built with plain JavaScript, Node.js, and SQLite so you can quickly understand the patterns and apply them to your own stack.

## Protect your users

<Columns>
  <Card title="Account Takeover" icon="shield-alert" href="/docs/account-takeover-use-case-tutorial">
    Detect and block attackers from hijacking accounts.
  </Card>

  <Card title="Card Testing" icon="credit-card" href="/docs/card-testing-use-case-tutorial">
    Reduce fraud. Increase real payments.
  </Card>

  <Card title="Credential Stuffing" icon="key" href="/docs/credential-stuffing-use-case-tutorial">
    Stop automated logins using stolen credentials.
  </Card>

  <Card title="Loan Fraud" icon="landmark" href="/docs/loan-fraud-use-case-tutorial">
    Identify risky devices during loan applications.
  </Card>
</Columns>

## Grow your revenue

<Columns>
  <Card title="Coupon Abuse" icon="ticket-percent" href="/docs/coupon-abuse-use-case-tutorial">
    Prevent repeated or automated coupon redemption.
  </Card>

  <Card title="Account Sharing" icon="users-round" href="/docs/account-sharing-use-case-tutorial">
    Stop multiple users accessing one paid account.
  </Card>

  <Card title="Paywall Enforcement" icon="brick-wall" href="/docs/paywall-use-case-tutorial">
    Block free access to premium content.
  </Card>

  <Card title="Personalization" icon="sparkles" href="/docs/personalization-use-case-tutorial">
    Personalize the user experience for any visitor.
  </Card>

  <Card title="New Account Fraud" icon="user-round-plus" href="/docs/new-account-fraud-use-case-tutorial">
    Block repeat signups and trial abuse.
  </Card>

  <Card title="Regional Pricing" icon="globe" href="/docs/regional-pricing-use-case-tutorial">
    Stop users exploiting cheaper regional prices.
  </Card>

  <Card title="Survey Fraud" icon="clipboard-check" href="/docs/survey-fraud-use-case-tutorial">
    Prevent survey fraud and abuse.
  </Card>

  <Card title="SMS Pumping" icon="message-square-warning" href="/docs/sms-pumping-use-case-tutorial">
    Prevent automated SMS abuse that drives carrier costs.
  </Card>
</Columns>

## Protect your platform

<Columns>
  <Card title="Web Scraping" icon="bot" href="/docs/web-scraping-use-case-tutorial">
    Block automated scraping of site content or data.
  </Card>

  <Card title="Ban Enforcement" icon="ban" href="/docs/ban-enforcement-use-case-tutorial">
    Prevent banned users from returning.
  </Card>

  <Card title="Chargeback Dispute" icon="receipt" href="/docs/chargeback-dispute-use-case-tutorial">
    Provide device evidence to challenge fraud claims.
  </Card>
</Columns>


# User preferences
Source: https://docs.fingerprint.com/docs/user-preferences



You can access your own profile to manage personal settings by visiting **Settings** >[**My Profile**](https://dashboard.fingerprint.com/profile/settings).

## Personal Information

* **Profile details**: Manage your personal information.
* **Time zone**: This setting determines the time zone in which you will view all statistics and analytics in the dashboard.

## Email Notifications

Manage your personal email settings, including whether you will receive:

* **Summary emails**: Subscribe to receive daily or weekly summary emails.
* **Workspace alerts**: Including billing events, alerts about outdated libraries, and other relevant notifications.


# Overview
Source: https://docs.fingerprint.com/docs/using-the-dashboard

A guide to understanding the web-based interface for managing your Fingerprint account.

The Fingerprint Dashboard is the web-based interface for managing your Fingerprint account. It provides a central view of key metrics, configuration settings, and team management.

You can access the dashboard by visiting [**dashboard.fingerprint.com**](https://dashboard.fingerprint.com/).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 41 09@2x" />
</Frame>

The dashboard is optimized for both administrators and data analysts, making it easy to configure your fingerprinting setup and monitor traffic trends.

### Using the Dashboard

* **Manage your account and your team**: The dashboard enables account owners to invite and [assign roles to team members](/docs/roles-permissions), customize granular access permissions across [multiple workspaces](/docs/workspaces-environments), and allows users to manage their [personal profile details](/docs/user-preferences), time zone, and email notifications.
* **Configure resources**: Within each workspace, you [configure essential resources](/docs/configuration), including managing various API keys, setting up [multiple environments](/docs/multiple-environments), implementing security features like [request filtering](/docs/request-filtering) and [custom subdomains](/docs/custom-subdomain-setup) to counter ad blockers, and configuring [webhooks](/docs/webhooks) to securely receive identification data on your server.
* **View analytics**: The dashboard provides [detailed analytics](/docs/analytics) via an Overview page that shows key metrics like API usage, unique visitors, and top detection lists, a Smart Signals page for monitoring specific suspicious indicators, and an Identification page where users can list, extensively filter, export identification events to CSV, and review thorough event details, including suspect scores and visitor history. Additionally you can [monitor health](/docs/health)  of your integration and SDK upgrades via Health page.
* **Analyze bot traffic**: The [Bots & AI agents](/docs/dashboard-bots-ai-agents) section breaks down your automated traffic by category, provider, and identity, and lets you investigate individual AI agent and bot events.

### Navigating the Dashboard

You can navigate the Dashboard by using the sidebar. The sidebar contains:

* **Workspace selector**: switch between different workspaces
* **Get started**: useful instructions if you’re installing Fingerprint for the first time
* **Overview**: insights and charts to stay on top of your traffic
* **Identification**: look up details about specific identification requests
* **Bots & AI agents**: analyze bot and AI agent traffic, and investigate individual automation events
* **Smart Signals**: discover Smart Signal statistics and adjust Suspect Score configuration
* **API keys**: create and manage keys for API access, cloud proxy integrations and encryption
* **Health**: monitor your setup for latency issues or outdated libraries
* **Security**: configure rules to filter out unwanted requests
* **Webhooks**: configure webhooks to receive identification events on your server asynchronously
* **Libraries & Integrations**: manage proxy integrations and libraries
* **Plan & usage**: manage your plan and view usage for the current billing period

The **Settings** page consolidates options relevant to your workspace, account, and personal preferences into one place.

* (Workspace) **General settings**: general workspace settings
* (Workspace) **Environments**: manage your multi-environment setup
* (Workspace) **Subdomains**: manage your subdomains
* (Account) **Workspaces**: manage multiple workspaces
* (Account) **Team**: manage team members
* (Account) **Billing**: manage billing information and payment methods
* (User) **My profile**: manage your user settings
* (User) **My notifications**: manage your notification preferences

In the top-right section of the page, you will find links for easy access to documentation and support.


# Vue Quickstart
Source: https://docs.fingerprint.com/docs/vue-quickstart

Get started using the Fingerprint Vue SDK

## Overview

In this quickstart, you'll add Fingerprint to a new [Vue 3](https://vuejs.org/) project and identify the user's device.

The example use case in this quickstart is stopping new account fraud, where attackers create multiple fake accounts to abuse promotions, exploit systems, or evade bans. However, the steps you'll follow apply to most use cases. By identifying the device behind each sign-up attempt, login, or transaction, you can flag and block suspicious users early.

This guide focuses on the frontend integration. You'll install the [Fingerprint Vue SDK](/docs/vuejs) and initialize the JavaScript agent to generate an event ID to send to your backend for analysis. **To see how to implement fraud prevention with this ID, continue to one of the [backend quickstarts](/docs/server-quickstarts-overview) after completing this quickstart.**

> Estimated time: \< 10 minutes

## Prerequisites

Before you begin, make sure you have the following:

* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of [Vue 3](https://vuejs.org/) and JavaScript

<Note>
  This quickstart only covers the **frontend setup**. You'll need a [backend
  server](/reference/server-sdks) to receive and process the device identification event to enable
  fraud detection. Check out one of the [backend quickstarts](/docs/server-quickstarts-overview)
  after completing this quickstart.
</Note>

## 1. Create a Fingerprint account and get your API key

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial if you don't already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Copy your **public API key**; you'll need it to initialize the JavaScript agent.

## 2. Set up your project

To get started, scaffold a new Vue app. If you already have a project you want to use, you can skip to the next section.

1. Create a new Vite project with the Vue template:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm create vite@latest fingerprint-vue-quickstart -- --template vue
cd fingerprint-vue-quickstart
npm install
```

2. Open the `fingerprint-vue-quickstart` folder in your code editor and you're ready to go! To run your project, run:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

3. In your browser, go to [http://localhost:5173](http://localhost:5173/) (Vite's default), and you should see the Vite welcome page.

## 3. Set up your account creation form

1. Before adding Fingerprint, create a new component at `src/components/CreateAccountForm.vue` with the following:

```vue src/components/CreateAccountForm.vue theme={"theme":"github-dark-dimmed"}
<script setup>
// Logic will be added later
</script>

<template>
  <div class="wrapper">
    <h1>Create an account</h1>
    <div class="input-group">
      <label for="username">Username</label>
      <input id="username" v-model="username" type="text" placeholder="Username" required />
    </div>
    <div class="input-group">
      <label for="password">Password</label>
      <input id="password" v-model="password" type="password" placeholder="Password" required />
    </div>
    <button :disabled="isLoading" @click="handleSubmit">
      {{ isLoading ? 'Loading…' : 'Create Account' }}
    </button>
  </div>
</template>

<style scoped>
.wrapper {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  min-height: 100vh;
  gap: 1rem;
  padding: 1rem;
}

input {
  width: 100%;
  padding: 0.5rem;
  border: 1px solid #ccc;
  border-radius: 4px;
}

.input-group {
  width: 100%;
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 0.5rem;
}

button {
  background-color: #f35b22;
  color: #fff;
  border: none;
  padding: 0.75rem 1.5rem;
  border-radius: 4px;
  cursor: pointer;
}

button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
</style>
```

2. Import and add the component to your main view in `src/App.vue`:

```vue src/App.vue theme={"theme":"github-dark-dimmed"}
<script setup>
import CreateAccountForm from './components/CreateAccountForm.vue';
</script>

<template>
  <CreateAccountForm />
</template>
```

## 4. Install and initialize the JavaScript agent

1. To integrate Fingerprint into your Vue app, first add the Fingerprint Vue SDK via npm:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/vue
```

*Note: This quickstart is written for version 2.x of the Fingerprint Vue SDK*

2. Now that the Vue SDK is installed, import and initialize it in your app's entry point. Open `src/main.js` and import the Fingerprint plugin:

```javascript src/main.js theme={"theme":"github-dark-dimmed"}
import { FingerprintPlugin } from '@fingerprint/vue';
```

3. Before mounting, initialize the plugin:

```javascript src/main.js theme={"theme":"github-dark-dimmed"}
const app = createApp(App);

app.use(FingerprintPlugin, {
  apiKey: 'PUBLIC_API_KEY',
  region: 'us', // Ensure this matches your workspace region
  // For more information, see https://docs.fingerprint.com/docs/regions
});

app.mount('#app');
```

3. Replace `PUBLIC_API_KEY` with your public API key from the [Fingerprint dashboard](https://dashboard.fingerprint.com/api-keys).

*Note: For production, consider using* [*Vite Env Variables*](https://vite.dev/guide/env-and-mode) *to configure the key.*

## 5. Trigger visitor identification

Now that the JavaScript agent is initialized, you can identify the visitor only when needed. In this case, that's when the user taps the **Create Account** button.

When making the visitor identification request, you will receive a visitor ID as well as an event ID. Instead of using the visitor ID returned directly on the frontend (which could be tampered with), you'll send the event ID to your backend. This ID is unique to each identification event. Your server can then use the [Fingerprint Events API](/reference/server-api-get-event) to retrieve complete identification data, including the trusted visitor ID and other actionable insights like whether they are using a VPN or are a bot.

1. Within the empty script tags in `CreateAccountForm.vue`, import Vue's `ref` and declare `username` and `password` as reactive variables to track your form inputs. Also import the Fingerprint `useVisitorData` hook:

```javascript src/components/CreateAccountForm.vue theme={"theme":"github-dark-dimmed"}
import { ref } from 'vue';
import { useVisitorData } from '@fingerprint/vue';

const username = ref('');
const password = ref('');
```

2. Initialize `useVisitorData` and access the returned values you'll need:

```javascript src/components/CreateAccountForm.vue theme={"theme":"github-dark-dimmed"}
const username = ref('');
const password = ref('');

const { isLoading, getData } = useVisitorData({ immediate: false }); // [!code ++]
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

This gives you:

* `getData()`: A function to trigger visitor identification on demand.
* `isLoading`: A flag to monitor visitor identification progress.

By setting `immediate` to `false` you're triggering device identification only when needed with the `getData()` method.

*Check the* [*Vue SDK reference*](https://fingerprintjs.github.io/vue/) *for available useVisitorData options.*

3. Define the submit handler to trigger identification when the user clicks **Create Account**:

```javascript theme={"theme":"github-dark-dimmed"}
async function handleSubmit() {
  const { visitor_id, event_id } = await getData();

  console.log('Visitor ID:', visitor_id);
  console.log('Event ID:', event_id);

  // Send the event_id to your server
  // await fetch("/api/create-account", {
  //   method: "POST",
  //   headers: { "Content-Type": "application/json" },
  //   body: JSON.stringify({
  //     username: username.value,
  //     password: password.value,
  //     event_id,
  //   }),
  // });
}
```

In this function:

* `getData()` is being called and Fingerprint is analyzing the visitor's browser; the result includes `visitor_id` and `event_id`.
* You can send the `event_id` to your backend along with the username and password for your fraud detection logic.

## 6. Test the app

1. If your dev server isn't already running, start it with:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. In your browser, go to [http://localhost:5173](http://localhost:5173) (Vite's default).
3. If you have any ad blockers, turn them off for localhost. View the [documentation](/docs/protecting-the-javascript-agent-from-adblockers) to learn how to protect your Fingerprint implementation from ad blockers in production.
4. Enter a username and password, then click **Create Account**.
5. Open the developer console in your browser and you should see the `visitor_id` and `event_id` in the output:

```text Output theme={"theme":"github-dark-dimmed"}
Visitor ID: JkLmNoPqRsTuVwXyZaBc
Event ID: 1234566477745.abc1GS
```

## Next steps

To use the identification data for fraud detection (like blocking repeat fake account creation attempts), you'll need to send the event ID to your [backend](/docs/server-quickstarts-overview). From there, your server can call the [Fingerprint Events API](/reference/server-api-get-event) to retrieve the full visitor information data and use it to make decisions and prevent fraud.

Check out these related resources:

* [Vue SDK reference](https://github.com/fingerprintjs/vue)
* [Node.js backend quickstart](/docs/node-server-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering)


# Vue
Source: https://docs.fingerprint.com/docs/vuejs



The [Fingerprint Vue SDK](https://github.com/fingerprintjs/vue) integrates Fingerprint into Vue 3 applications. It supports all capabilities of the JavaScript agent including a built-in [caching mechanism](/reference/js-agent-start-function#cache). See the [Vue quickstart](/docs/vue-quickstart) for a step-by-step guide to get started.

### How to install

Add `@fingerprint/vue` as a dependency to your application.

<CodeGroup>
  ```shell NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/vue
  ```

  ```shell Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/vue
  ```

  ```shell PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/vue
  ```
</CodeGroup>

Register `FingerprintPlugin` in your application. You need to specify your public API key and other configuration options based on your chosen region and active integration.

```javascript Vue 3 theme={"theme":"github-dark-dimmed"}
// src/main.js
import { createApp } from 'vue';
import App from './App.vue';
import { FingerprintPlugin } from '@fingerprint/vue';

const app = createApp(App);

app
  .use(FingerprintPlugin, {
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://metrics.yourwebsite.com',
    region: 'us',
  })
  .mount('#app');
```

Use the `useVisitorData` hook in your components to identify visitors.

```vue Vue 3 theme={"theme":"github-dark-dimmed"}
<!-- src/App.vue -->
<script setup>
import { useVisitorData } from '@fingerprint/vue';

const { data, error, isLoading, getData } = useVisitorData({ immediate: true });
</script>

<template>
  <div>
    <button @click="getData()">Reload data</button>
    <p v-if="isLoading">Loading...</p>
    <p v-else>Visitor ID: {{ data?.visitor_id }}</p>
    <p v-if="error">{{ error.message }}</p>
    <pre v-if="data">{{ JSON.stringify(data, null, 2) }}</pre>
  </div>
</template>
```

### Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/vue). The repository also contains [example applications](https://github.com/fingerprintjs/vue/tree/main/examples) demonstrating the usage of the library.

### Migration guide for Vue SDK v2.0.0

Version 2.0.0 of the Vue SDK switches from JavaScript agent v3 to [JavaScript agent v4](/reference/migrating-from-v3-to-v4).

1. Install a new version of the package:

<CodeGroup>
  ```bash NPM theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/vue
  ```

  ```bash Yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/vue
  ```

  ```bash PNPM theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/vue
  ```
</CodeGroup>

2. Update the plugin import and options.

The default caching strategy has changed from `sessionStorage` caching to **no caching by default**, aligned with the underlying [JavaScript agent v4 default](/reference/js-agent-start-function#cache). To preserve the previous behavior, explicitly configure caching in the plugin options (see example below).

```javascript Change plugin imports and usage theme={"theme":"github-dark-dimmed"}
// [!code --:5]
import {
  fpjsPlugin,
  FingerprintJSPro,
  CacheLocation,
} from '@fingerprintjs/fingerprintjs-pro-vue-v3';
// [!code ++]
import { FingerprintPlugin } from '@fingerprint/vue';

// [!code --:12]
app.use(fpjsPlugin, {
  cacheLocation: CacheLocation.LocalStorage,
  cacheTimeInSeconds: 60,
  loadOptions: {
    apiKey: 'PUBLIC_API_KEY',
    endpoint: ['https://metrics.yourwebsite.com', FingerprintJSPro.defaultEndpoint],
    scriptUrlPattern: [
      'https://metrics.yourwebsite.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js',
      FingerprintJSPro.defaultScriptUrlPattern,
    ],
  },
});
// [!code ++:8]
app.use(FingerprintPlugin, {
  cache: {
    storage: 'sessionStorage',
    duration: 3600,
  },
  apiKey: 'PUBLIC_API_KEY',
  endpoints: ['https://metrics.yourwebsite.com'],
});
```

3. Update `useVisitorData` calls and result field names:

```javascript Update visitor data usage theme={"theme":"github-dark-dimmed"}
// [!code --]
import { useVisitorData } from '@fingerprintjs/fingerprintjs-pro-vue-v3';
import { useVisitorData } from '@fingerprint/vue'; // [!code ++]

// [!code --:4]
const { data, isLoading, getData } = useVisitorData(
  { timeout: 1000, ignoreCache: true },
  { immediate: false },
);
// `immediate` can now be set in the first argument // [!code ++:3]
// `ignoreCache` is no longer available; configure cache on the plugin instead
const { data, isLoading, getData } = useVisitorData({ timeout: 1000, immediate: false });

// [!code --:2]
const { visitorId, requestId } = await getData();
console.log(visitorId, requestId);
// [!code ++:2]
const { visitor_id, event_id } = await getData();
console.log(visitor_id, event_id);
```

The v4 agent uses snake\_case field names. `requestId` is now `event_id`, and `visitorId` is now `visitor_id`.


# Web Scraping
Source: https://docs.fingerprint.com/docs/web-scraping-use-case-tutorial

Learn how to detect and prevent unauthorized web scraping

## Overview

This tutorial walks through implementing Fingerprint to prevent web scraping, where bots attempt to extract proprietary or sensitive data from your website automatically.

You'll begin with a starter app that includes a mock flight search page and a basic querying flow. From there, you'll add the JavaScript agent to identify each visitor and use server-side logic with Fingerprint data to detect and block automated scraping attempts.

By the end, you'll have a sample app that blocks bot-driven data scraping and can be customized to fit your use case and access control policies.

This tutorial uses just plain JavaScript and a Node server with SQLite on the backend. For language- or framework-specific setups, see the quickstarts.

> Estimated time: \< 15 minutes

<iframe title="YouTube video player" />

<Note>
  This tutorial requires the Bot Detection Smart Signal, which is only available on paid plans.
</Note>

## Prerequisites

Before you begin, make sure you have the following:

* A copy of the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) (clone with Git or download as a ZIP)
* [Node.js](https://nodejs.org/) (v20 or later) and npm installed
* Your favorite code editor
* Basic knowledge of JavaScript

## 1. Create a Fingerprint account and get your API keys

1. [Sign up](https://dashboard.fingerprint.com/signup) for a free Fingerprint trial, or log in if you already have an account.
2. After signing in, go to the [**API keys**](https://dashboard.fingerprint.com/api-keys) page in the dashboard.
3. Save your **public API key**, which you'll use to initialize the JavaScript agent.
4. Create and securely store a **secret API key** for your server. Never expose it on the client side. You'll use this key on the backend to retrieve full visitor information through the Fingerprint Server API.

## 2. Set up your project

1. Clone or download the [starter repository](https://github.com/fingerprintjs/use-case-tutorials) and open it in your editor.

```bash Terminal theme={"theme":"github-dark-dimmed"}
git clone https://github.com/fingerprintjs/use-case-tutorials.git
```

2. This tutorial will be using the `web-scraping` folder. The project is organized as follows:

<Tree>
  <Tree.Folder name="public">
    <Tree.File name="index.html - Flight search page" />

    <Tree.File name="index.js - Front-end logic for flight search" />
  </Tree.Folder>

  <Tree.Folder name="server">
    <Tree.File name="db.js - SQLite database connection" />

    <Tree.File name="flights.js - Flight search and bot detection" />

    <Tree.File name="server.js - Serves static files and search endpoint" />
  </Tree.Folder>

  <Tree.File name=".env.example - Example environment variables" />
</Tree>

3. Install dependencies:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm install
```

4. Copy or rename `.env.example` to `.env`, then add your Fingerprint API keys:

```bash Terminal theme={"theme":"github-dark-dimmed"}
FP_PUBLIC_API_KEY=your-public-key
FP_SECRET_API_KEY=your-secret-key
```

5. Start the server:

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

6. Visit [http://localhost:3000](http://localhost:3000) to view the mock flight search page from the starter app. Try a sample query (for example, SFO to MIA) and click **Search**.
7. Then try to search for flights using the included headless bot test script `test-bot.js`. While the app is running, execute `node test-bot.js` and observe that the automated search request returns all results. By default, the server does not distinguish between bots and real users.

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

## 3. Add Fingerprint to the frontend

In this step, you'll load the JavaScript agent when the page loads and trigger identification when the user clicks **Search**. The JavaScript agent returns both a `visitor_id` and an `event_id`. Instead of relying on the `visitor_id` from the browser, you'll send the `event_id` to your server along with the search inputs. Your server will then call the [Fingerprint Events API](/reference/server-api-get-event) to securely retrieve the full identification details, including bot detection and other signals.

1. At the top of `public/index.js`, load the JavaScript agent:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
const fpPromise = import(`https://fpjscdn.net/v4/${window.FP_PUBLIC_API_KEY}`).then((Fingerprint) =>
  Fingerprint.start({ region: "us" }),
);
```

2. Make sure to change `region` to match your workspace region (e.g., `eu` for Europe, `ap` for Asia, `us` for Global (default)).
3. Near the bottom of `public/index.js`, the **Search** button already has an event handler for submitting the query. Inside this handler, request visitor identification using `get()` and include the returned `event_id` when sending the search to the server:

```javascript public/index.js theme={"theme":"github-dark-dimmed"}
searchBtn.addEventListener("click", async () => {
  // ...

  const fp = await fpPromise;
  const { event_id: eventId } = await fp.get();

  try {
    const res = await fetch("/api/fetch-flights", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ from, to, departDate, passengers, eventId }),
    });
    const data = await res.json();

    // ...
  }
});
```

<Note>
  **Linking your own identifiers:** if you already have an identifier for the user at this point, like an account, order, or session ID, pass it as `linkedId`. It's returned as `linked_id` on the event and indexed, so you can retrieve every event tied to that identifier through the Server API. Learn more about adding more context to your identification events in [Linking and tagging information](/docs/tagging-information).
</Note>

The `get()` method sends signals collected from the browser to Fingerprint servers, where they are analyzed to identify the visitor and determine if they are a bot. The returned `event_id` acts as a reference to this specific identification event, which your server can later use to fetch the full visitor details.

For lower latency in production, use [Sealed Client Results](/docs/sealed-client-results) to return full identification details as an encrypted payload from the `get()` method.

## 4. Receive and use the event ID to get visitor insights

Next, pass the `eventId` through to your flight search logic, initialize the [Fingerprint Node Server SDK](/reference/node-server-sdk), and fetch the full visitor identification event so you can access the Bot Detection [Smart Signal](https://fingerprint.com/products/smart-signals/).

1. In the backend, the `server/server.js` file already defines API routes for the app. The `/api/fetch-flights` route passes the request body to the `fetchFlights` function defined in `server/flights.js`. Because the frontend now sends `eventId` in the payload, that value will be available in the body when `fetchFlights` runs.

```javascript server/server.js theme={"theme":"github-dark-dimmed"}
app.post("/api/fetch-flights", async (req, reply) => {
  const result = await fetchFlights(req.body);
  return reply.send(result);
});
```

2. The `server/flights.js` file contains the logic for handling flight searches. Start by importing and initializing the Fingerprint Node Server SDK there, and load your environment variables with `dotenv`.

```javascript server/flights.js theme={"theme":"github-dark-dimmed"}
import { db } from "./db.js";
import { config } from "dotenv";
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

config();

const fpServerApiClient = new FingerprintServerApiClient({
  apiKey: process.env.FP_SECRET_API_KEY,
  region: Region.Global,
});
```

3. Make sure to change `region` to match your workspace region (e.g., `EU` for Europe, `AP` for Asia, `Global` for Global (default)).
4. Update the `fetchFlights` function to accept the `eventId` and use it to fetch the full identification event details from Fingerprint:

```javascript server/flights.js theme={"theme":"github-dark-dimmed"}
export async function fetchFlights({ from, to, departDate, eventId }) {
  if (!from || !to || !departDate || !eventId) {
    console.error("Missing required fields.");
    return { success: false, message: "Missing required fields." };
  }

  const event = await fpServerApiClient.getEvent(eventId);

  // ...
}
```

Using the `eventId`, the getEvent method will retrieve the full data for the visitor identification event. The returned object will contain the visitor ID, IP address, device, and browser details, as well as Smart Signals, including bot detection, browser tampering detection, VPN detection, and more.

You can see a full example of the event structure and test it with your own device in the [demo playground](https://demo.fingerprint.com/playground).

For additional checks to ensure the validity of the data coming from your frontend, view [how to protect from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering).

## 5. Block content scraping bots

Web scraping relies on automated requests, so rejecting bots outright helps protect proprietary data. Fingerprint returns `not_detected` if no bot activity is found, `good` for known bots, like search engines, and `bad` for other automation tools. Any visitor identification that does not return `not_detected` can be blocked from retrieving flight data.

1. Continuing in the `fetchFlights` function in `server/flights.js`, check the bot signal returned in the `event` object and block bots:

```javascript server/flights.js theme={"theme":"github-dark-dimmed"}
export async function fetchFlights({ from, to, departDate, eventId }) {
  // ...

  const event = await fpServerApiClient.getEvent(eventId);

  const botDetected = event.bot !== "not_detected";

  if (botDetected) {
    console.error("Bot detected.");
    return { flights: [] };
  }

  // ...
}
```

You can also add [Suspect Score](/docs/suspect-score) as a secondary defense layer. The Suspect Score is a weighted representation of all Smart Signals present in the identification payload, helping to identify suspicious or automated activity. You likely wouldn't block searches based only on a high risk score, but you can use it to change how you respond, such as by adding a rate limit or requiring additional verification.

2. Below the bot detection check, add a condition that reads the Suspect Score from the `event` object and blocks the search if it exceeds a chosen threshold (for example, 20):

```javascript server/flights.js theme={"theme":"github-dark-dimmed"}
export async function fetchFlights({ from, to, departDate, eventId }) {
  // ...

  const botDetected = event.bot !== "not_detected";

  if (botDetected) {
    console.error("Bot detected.");
    return { flights: [] };
  }

  const suspectScore = event.suspect_score || 0;

  if (suspectScore > 20) {
    console.error(`High Suspect Score detected: ${suspectScore}`);
    return { flights: [] };
  }

  // ...
}
```

Smart Signals allow you to protect your site and prevent web scraping. You can extend this by analyzing additional signals, adjusting rate limits, varying responses for suspicious traffic, and more.

<Info>
  This is a minimal example to show how to implement Fingerprint. In a real application, make sure
  to implement proper security practices, error handling, and access controls that align with your
  production standards.
</Info>

## 7. Test your implementation

Now that everything is wired up, you can test the full protected search flow.

1. Start your server if it isn't already running and open [http://localhost:3000](http://localhost:3000):

```bash Terminal theme={"theme":"github-dark-dimmed"}
npm run dev
```

2. Try a normal search (for example, SFO to JFK). You should get matching flights returned.
3. Next, run the included headless bot test script. While the app is running, execute `node test-bot.js` and observe that the automated search requests do not return any results and the bot's access is blocked.

```bash Terminal theme={"theme":"github-dark-dimmed"}
node test-bot.js
```

*Note: If you encounter errors launching the automated browser, make sure you have the testing browser installed:*

```bash Terminal theme={"theme":"github-dark-dimmed"}
npx puppeteer browsers install chrome
```

## Next steps

You now have a working flight search flow that blocks scraping bots with Fingerprint. From here, you can expand the logic with more [Smart Signals](/docs/smart-signals-reference), fine-tune rules based on your business policies, or layer in additional defenses, such as rate limiting or dynamic content obfuscation.

To dive deeper, explore the other use case tutorials for more step-by-step examples.

Check out these related resources:

* [Node SDK Reference](/reference/node-server-sdk)
* [Vue frontend quickstart](/docs/vue-quickstart)
* [React frontend quickstart](/docs/react-quickstart)
* [API reference for the Events endpoint](/reference/server-api-get-event)
* [Use case tutorial: Detecting new account fraud](/docs/new-account-fraud-use-case-tutorial)
* [Low-latency identification with Sealed Client Results](/docs/sealed-client-results)


# Workspaces & environments
Source: https://docs.fingerprint.com/docs/workspaces-environments



Workspaces and environments let you organize projects and separate traffic contexts.

## Workspaces

A **Workspace** is a dedicated project space (tied to your account) where you manage and configure Fingerprint for a given application or business unit. Each workspace has its own data and settings – for example, you might have one workspace for your primary business and another for your secondary business managed by a dedicated team.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 53 32@2x" />
</Frame>

To switch between different workspaces, use the **workspace selector (1)** on the top of the sidebar.

To manage your workspaces, go to **Settings** > [**Workspaces**](https://dashboard.fingerprint.com/settings/workspaces). Your plan is tied to your workspace. If you’re on the Enterprise plan, reach out to [Customer Support](https://fingerprint.com/support/) for additional workspaces.

## Environments

A workspace can contain multiple **Environments**, which are useful for isolating production vs. development or staging setups. For instance, you might have “Prod” and “Dev” environments under the same workspace, or different domains under separate environments. Learn more about [multiple environments](/docs/multiple-environments).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 54 12@2x" />
</Frame>

To see environment specific data and resources, look for **environment filter options** on the pages you’re working with.

To manage your environments, go to **Settings** > [**Environments**](https://dashboard.fingerprint.com/environments). Each workspace starts with a default environment which cannot be removed, but you can add or delete others as needed.

You can optionally set a **API usage threshold** for each environment if you want to be notified about excess usage. If you're an Enterprise customer, you can also set a limit to **restrict API usage** for each environment.

## Comparison

If you manage multiple websites, applications, or business units, the best option will depend on your specific use case and how separate you need them to be. Both workspaces and environments have advantages and trade-offs, which you can compare below.

|                    | Workspaces                                                                                                         | Environments                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| **Regions**        | Each workspace can be created on a different region.                                                               | They belong to a single workspace, so they are always in the same region.                    |
| **Identification** | Identification is completely separate, so same device will get a different visitor ID on different workspaces.     | Identification is shared, so same device will get the same visitor ID on every environment.  |
| **Observability**  | Each workspace is separate so there's no high-level observability and shared statistics for multiple workspaces.   | Full support for observability and statistics for multiple environments.                     |
| **Management**     | Created and managed manually.                                                                                      | Can be created and managed programmatically via [Management API](/reference/management-api). |
| **Team access**    | Team members can be given access to specific workspaces with [granular user permissions](/docs/roles-permissions). | When they have access to workspace, team members have full access to all environments.       |


# AI agent detection
Source: https://docs.fingerprint.com/docs/ai-agents

Detect and verify AI agents visiting your web properties, and distinguish them from malicious bots.

AI agent detection lets you identify authorized AI agents visiting your website and distinguish them from malicious bots.

It uses [Web Bot Auth](/docs/bot-detection/web-bot-auth-implementation), a cryptographic signing protocol, to verify agent identity. When Fingerprint detects an agent, it returns structured metadata, including the agent's provider, name, and the identity verification status in the `bot_info` field of the Server API response.

This lets you make precise access decisions: allow authorized agents, block unverified automation, or apply different logic based on agent category and provider.

## How verification works

1. The agent signs its HTTP requests using a private key.
2. Fingerprint retrieves the agent's public key from a directory hosted at a known URL.
3. Fingerprint verifies the signature and returns an `identity` value in `bot_info`.

The `identity` value reflects the outcome of the verification:

| Value      | Meaning                                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| `signed`   | Signature verified against the agent's public key directory                                                    |
| `verified` | Signature verified, and the agent is operated exclusively by its vendor (not configurable by vendor customers) |
| `unknown`  | Agent recognized, but no verifiable identity was presented                                                     |
| `spoofed`  | Agent presented an identity that failed verification                                                           |

## API response

When Fingerprint detects a bot or agent, the [Server API](/reference/server-api-get-event) response includes the following fields:

| Field      | Type   | Description                                      |
| ---------- | ------ | ------------------------------------------------ |
| `bot`      | string | `good`, `bad`, or `not_detected`                 |
| `bot_type` | string | Additional classification, e.g. `ai_agent`       |
| `bot_info` | object | Extended metadata for recognized agents and bots |

The `bot_info` object contains:

| Field      | Description                                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | Agent category, e.g. `ai_agent`, `ai_browser`, `browser_automation` ([full list](/docs/bot-detection/bot-directory#bot_info-metadata)) |
| `provider` | The organization that operates the agent, e.g. `OpenAI` or `AWS`                                                                       |
| `name`     | Human-readable agent name, e.g. `ChatGPT Agent`                                                                                        |
| `identity` | Verification status: `signed`, `verified`, `unknown` or `spoofed`                                                                      |

`bot_info` is available in Server API v4 and only when Fingerprint recognizes the agent or bot. See the [Server API reference](/reference/server-api-get-event#response-bot-info) for the full schema.

## Supported AI agents

The following agents are currently detected and return `bot_info` metadata:

| Name              | Provider    | Category     | Identity |
| ----------------- | ----------- | ------------ | -------- |
| ChatGPT Agent     | OpenAI      | `ai_agent`   | `signed` |
| Bedrock AgentCore | AWS         | `ai_agent`   | `signed` |
| Browserbase Agent | Browserbase | `ai_agent`   | `signed` |
| Manus Agent       | Manus       | `ai_agent`   | `signed` |
| AGI Agent         | AGI Inc     | `ai_agent`   | `signed` |
| Anchor Browser    | Anchor      | `ai_browser` | `signed` |

For the full list of all detectable bots and agents, see the [Bot Directory](/docs/bot-detection/bot-directory).

## Using detection results

The `bot` field (`good`, `bad`, `not_detected`) is a legacy signal. For AI agents and other recognized bots, use `bot_info.identity` instead, as it provides more precise, actionable information.

Note that `identity` is only available for well-known bots and agents in the [Bot Directory](/docs/bot-detection/bot-directory). Some generic browser automation tools (Selenium, Playwright, headless Chrome, etc.) will not have a `bot_info` entry and should be handled using the `bot: bad` signal.

| Scenario                               | Suggested action                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `bot_info.identity: verified`          | **Allow**: agent identity is confirmed and safety verified                                 |
| `bot_info.identity: signed`            | **Allow**: agent identity is cryptographically verified                                    |
| `bot_info.identity: unknown`           | **Apply custom logic**: agent is recognized but unverified                                 |
| `bot_info.identity: spoofed`           | **Review**: verification failed, which may indicate misconfiguration or malicious spoofing |
| `bot` is `bad`, no `bot_info` (legacy) | **Review or Block**: unrecognized and potentially malicious automation                     |

## Next steps

<Columns>
  <Card title="Bot Directory" icon="globe" href="/docs/bot-detection/bot-directory">
    Full list of detectable bots and agents
  </Card>

  <Card title="Web Bot Auth implementation" icon="braces" href="/docs/bot-detection/web-bot-auth-implementation">
    Cryptographically sign your agent to verify identity
  </Card>

  <Card title="Submit your agent to Fingerprint directory" icon="shield" href="https://dashboard.fingerprint.com/submit-bot">
    Submit your agent or bot to the Fingerprint Bot Directory
  </Card>
</Columns>


# AI assistant detection
Source: https://docs.fingerprint.com/docs/ai-assistants

Detect and verify AI assistants visiting your web properties or API endpoints and distinguish them from malicious bots.

<Info>
  AI assistant detection requires a [Flow worker](/docs/flow-deployments#using-a-flow-worker-to-detect-bots-at-the-edge) deployment.
</Info>

AI assistants are LLM chat applications that can answer questions, summarize information, and make requests to websites to gather information. When an AI assistant is making a request to a website, Fingerprint can detect these requests and identity the assistant category, provider and identity. The most common AI assistants are ChatGPT, Gemini, and Claude.ai.

Fingerprint's AI assistant detection lets you detect and verify AI assistants visiting your website or using your APIs and distinguish them from malicious bots.

It uses [Web Bot Auth](/docs/bot-detection/web-bot-auth-implementation), IP, and DNS checks to verify AI assistant identity. When Fingerprint detects an assistant, it returns structured metadata, including the assistant's provider, name, and the identity verification status in the `bot_info` field of the Server API response.

This lets you make precise access decisions: allow authorized assistants, block unverified automation, or apply different logic based on assistant category and provider.

## How identity verification works

Fingerprint will use all available methods to verify the assistant identity and will also detect spoofing / impersonation attempts.

The `identity` value reflects the outcome of the verification:

| Value      | Meaning                                                     |
| ---------- | ----------------------------------------------------------- |
| `verified` | Identity verified                                           |
| `unknown`  | Assistant recognized, but the identity couldn't be verified |
| `spoofed`  | Assistant presented an identity that failed verification    |

## API response

When Fingerprint detects a bot, the [Server API](/reference/server-api-get-event) response includes the following fields:

| Field      | Type   | Description                                                   |
| ---------- | ------ | ------------------------------------------------------------- |
| `bot`      | string | `good`, `bad`, or `not_detected`                              |
| `bot_type` | string | Additional classification, e.g. `ai_assistant`                |
| `bot_info` | object | Extended metadata for recognized assistants, agents, and bots |

The `bot_info` object contains:

| Field      | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `category` | `ai_assistant`                                                             |
| `provider` | The organization that operates the assistant, e.g. `OpenAI` or `Anthropic` |
| `name`     | Human-readable assistant name, e.g. `ChatGPT-User`                         |
| `identity` | Verification status: `verified`, `unknown` or `spoofed`                    |

`bot_info` is available in Server API v4 and only when Fingerprint recognizes the AI tool or a bot. See the [Server API reference](/reference/server-api-get-event#response-bot-info) for the full schema. The full list of bots is available here: [full list](/docs/bot-detection/bot-directory#bot_info-metadata).

## Supported AI assistants

For the full list of all detectable AI tools and bots, see the [Bot Directory](/docs/bot-detection/bot-directory).

## Using detection results

The `bot` field (`good`, `bad`, `not_detected`) is a legacy signal. For AI assistants and other recognized bots, use `bot_info.identity` instead, as it provides more precise, actionable information.

Note that `identity` is only available for well-known bots and assistants in the [Bot Directory](/docs/bot-detection/bot-directory). Some generic browser automation tools (Selenium, Playwright, headless Chrome, etc.) will not have a `bot_info` entry and should be handled using the `bot: bad` signal.

| Scenario                               | Suggested action                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `bot_info.identity: verified`          | **Allow**: assistant identity is confirmed and safety verified                             |
| `bot_info.identity: unknown`           | **Apply custom logic**: assistant is recognized but unverified                             |
| `bot_info.identity: spoofed`           | **Review**: verification failed, which may indicate misconfiguration or malicious spoofing |
| `bot` is `bad`, no `bot_info` (legacy) | **Review or Block**: unrecognized and potentially malicious automation                     |

## Next steps

<Columns>
  <Card title="Bot Directory" icon="globe" href="/docs/bot-detection/bot-directory">
    Full list of detectable bots and agents
  </Card>

  <Card title="AI agent detection" icon="braces" href="/docs/ai-agents">
    Detect and verify AI agents
  </Card>

  <Card title="Submit your assistant to Fingerprint directory" icon="shield" href="https://dashboard.fingerprint.com/submit-bot">
    Submit your assistant or bot to the Fingerprint Bot Directory
  </Card>
</Columns>


# AI bot request filtering
Source: https://docs.fingerprint.com/docs/ai-bot-filtering

Allow basic AI bots filtering through a single switch in the Request Filtering

AI bots use scrapers to gather content for model training as well as offering tools that process a webpage for additional information. The bots can generate a significant amount of traffic and cause a surge in billable API calls. To prevent this scenario, Fingerprint offers AI Bots Filtering toggle in the Dashboard.

AI bots that are filtered through this setting then behave in the same way as other request filtering rules and you don't get billed for them. Keep in mind that we won't return any information except `event_id` in those cases.

<Note>
  AI bots filtering based on `User-Agent` is a basic mechanism we provide for free to filter out
  commonly encountered and generally well behaved search bots. Because of its simplicity, it might
  introduce both **false positive and false negative** cases. If you need **better protection
  against sophisticated bots**, check out our [Smart Signals that contain a paid Bot Detection
  product](/docs/smart-signals-reference#browser-bot-detection).
</Note>

## Configuration

AI Bots Filtering can be turned on or off in our Dashboard.

1. Navigate to **Dashboard** > **[Security](https://dashboard.fingerprint.com/traffic-rules)** and switch to the **Bots** tab.
2. Enable **Exclude AI Bots** to start filtering AI bots from your billable API calls.

<img alt="" />

## List of supported search bots `User-Agent` strings

The list of AI bots `User-Agent` strings we support is public and we keep it updated based on the currently supported `User-Agent` strings. The following table contains all supported `User-Agent` strings with their respective information sources.

| Owner        | User-Agent (Substrings)      |
| ------------ | ---------------------------- |
| OpenAI       | `ChatGPT-User`<br />`GPTBot` |
| Duckduckgo   | `DuckAssistbot`              |
| Google       | `GoogleOther`                |
| Huawei       | `PetalBot`                   |
| LinerBot     | `LINER Bot`                  |
| Factset      | `Factset_spyderbot`          |
| Amazon       | `Amazonbot`                  |
| Apple        | `Applebot`                   |
| OAISearchBot | `OAI-SearchBot`              |
| Qualified    | `QualifiedBot`               |
| ICC          | `ICC Crawler`                |
| Anthropic    | `ClaudeBot`                  |
| Facebook     | `meta-webindexer`            |
| Facebook     | `meta-externalagent`         |
| Facebook     | `meta-externalfetcher`       |


# Migrate Akamai integration from API v3 to API v4
Source: https://docs.fingerprint.com/docs/akamai-v3-to-v4-migration-guide



**Welcome!** This guide helps you migrate your Akamai integration from API v3 to API v4.

You will first gather your existing integration details, then upgrade your Akamai property configuration so it can handle both v3 and v4 routes, validate v4 traffic through the proxy before changing production, update your app to JavaScript Agent v4, and finally monitor the rollout and clean up any v3-specific configuration once v3 traffic has fully stopped.

<Note>
  Follow the steps below in order. If you keep v3 working while you validate v4, you can roll
  forward safely and avoid user impact.
</Note>

## Step 0: Collect Inputs (no changes yet)

You should have:

* Your current integration domain (example: `https://metrics.yourwebsite.com`)
* Your current proxy secret (`FPJS_PROXY_SECRET` property sensitive variable)
* Your current v3 integration path variables:
  * `FPJS_INTEGRATION_PATH` (found in the path match criteria of the *Fingerprint* rule)
  * `FPJS_AGENT_PATH` (found in the path match criteria of the *Fingerprint* > *Origin for Agent* rule)
  * `FPJS_RESULT_PATH` (found in the path match criteria of the *Fingerprint* > *Origin for Ingress* rule)
* Your public API key
* Your region (example: `us`, `eu`, `ap`)

<Note>
  After migration is complete and your website is fully on agent v4, the client agent only needs `FPJS_INTEGRATION_PATH`. The Terraform rules template still requires `fpjs_agent_path` and `fpjs_result_path` to be defined (see Step 1.1). Keep them set to your real v3 values while v3 clients are still active, and switch them to placeholder values once you retire v3 (see Step 4).
</Note>

## Step 1: Upgrade your Akamai integration

Update the Akamai property configuration to a version that supports JavaScript Agent v4. Choose your deployment method below.

### 1.1 Using Terraform

1. Update your `akamai_property_rules_template` variable blocks:

   * Keep `fpjs_agent_path` and `fpjs_result_path` set to their current v3 path values until no clients use v3.
   * Add the new `fpjs_integration_path_escaped` variable.

   ```terraform main.tf theme={"theme":"github-dark-dimmed"}
   data "akamai_property_rules_template" "rules" {
         template_file = "/rules/main.json"
         variables {
           name  = "fpjs_integration_path"
           value = "FPJS_INTEGRATION_PATH"
           type = "string"
         }
         variables {
           name  = "fpjs_integration_path_escaped"
           value = "YOUR_INTEGRATION_PATH_ESCAPED" # same as FPJS_INTEGRATION_PATH but with / escaped as \\/ and . escaped as \.
           type = "string"
         }
         variables {
           name  = "fpjs_agent_path"
           value = "FPJS_AGENT_PATH" # Keep this v3 value until no clients use v3.
           type = "string"
         }
         variables {
           name  = "fpjs_result_path"
           value = "FPJS_RESULT_PATH" # keep your existing v3 value until no clients use v3 (see Step 4)
           type = "string"
         }
         variables {
           name  = "fpjs_proxy_secret"
           value = "FPJS_PROXY_SECRET"
           type = "string"
         }
   }
   ```

2. Download the latest `terraform-fingerprint-property-rules.json` and `terraform-fingerprint-property-variables.json` files from the [latest release][proxy-latest-release] and replace the existing ones in your `rules` directory.

3. Run `terraform plan` to review your changes.

4. Run `terraform apply`.

For full details, see [Deploy Akamai proxy integration using Terraform][akamai-terraform].

### 1.2 Using Akamai Property Manager API (PAPI)

1. Clone the [Akamai proxy integration repository][proxy-github-repo]:

   ```bash theme={"theme":"github-dark-dimmed"}
   git clone git@github.com:fingerprintjs/akamai-proxy.git
   ```

2. Install dependencies:

   ```bash theme={"theme":"github-dark-dimmed"}
   pnpm install
   ```

3. Generate the patch body. Note that `--agent-path` and `--result-path` are no longer needed:

   ```bash theme={"theme":"github-dark-dimmed"}
   pnpm build --type patchBody \
       --integration-path "FPJS_INTEGRATION_PATH" \
       --proxy-secret "FPJS_PROXY_SECRET"
   ```

4. Follow the PAPI deployment steps (clone property version, remove existing Fingerprint artifacts, patch, activate) as described in [Deploy Akamai proxy integration using PAPI][akamai-papi].

### 1.3 Verify

Acceptance criteria:

* The integration can still serve v3 agent download and identification requests.
* The integration can also route v4 requests, for example requests under `/FPJS_INTEGRATION_PATH/web/v4/...`.

Verification ideas:

* Open `https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/status` and confirm the integration is healthy.
* Confirm your existing (v3) production client still works and can identify.
* Validate v4 routing through the proxy with a quick test:

  ```javascript NPM theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent';

  const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: ['https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
  });

  fp.get().then((result) => console.log(result));
  ```

## Step 2: Validate v4 routing before changing your production client

Before flipping your app, test v4 through the proxy.

Options:

* Use a staging site / feature flag to load agent v4.
* Temporarily run agent v4 in a dev environment.

What to check:

* The agent script loads through the proxy (no ad blocker or CDN errors)
  * You may use browser dev tools' network tab to confirm the script is loaded from the proxy.
* Identification requests go through the proxy (not directly to Fingerprint default endpoints)
* Results are returned successfully

## Step 3: Update your application to JavaScript Agent v4

Update your website to load and initialize agent v4 using your proxy base URL. Replace the placeholders with your values:

<CodeGroup>
  ```javascript NPM theme={"theme":"github-dark-dimmed"}
  import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'; // [!code --]
  import * as Fingerprint from '@fingerprint/agent'; // [!code ++]

  // [!code --:11]
  const fpPromise = FingerprintJS.load({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      scriptUrlPattern: [
          'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_AGENT_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
          FingerprintJS.defaultScriptUrlPattern,
      ],
      endpoint: [
          'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_RESULT_PATH?region=us',
          FingerprintJS.defaultEndpoint,
      ],
  });

  // [!code ++:5]
  const fp = Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: ['https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
  });
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  // [!code --:7]
  const url = 'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_AGENT_PATH?apiKey=PUBLIC_API_KEY';
  const fpPromise = import(url)
  .then(FingerprintJS => FingerprintJS.load({
      region: 'us',
      endpoint: [
          'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_RESULT_PATH?region=us',
          FingerprintJS.defaultEndpoint,
      ],
  }));

  // [!code ++:6]
  const fpPromise =
  import('https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/web/v4/PUBLIC_API_KEY?region=us').then(
    (Fingerprint) =>
      Fingerprint.start({
        region: 'us',
        endpoints: ['https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
      }),
  );
  ```
</CodeGroup>

To learn more about JavaScript Agent v4 changes, see the [JavaScript Agent v3 to v4 migration guide][js-agent-migration].

## Step 4: Monitor and finalize

After rollout:

* Monitor proxied traffic and error rate from the [integration status page][fingerprint-integrations] in the Fingerprint Dashboard.
* Confirm the majority of traffic is using v4 paths.

Optional cleanup (later):

* If you introduced any temporary parallel paths for testing, remove them.
* When you are confident no clients use v3, you can remove v3-specific configuration:
  * **Terraform**: Keep the `fpjs_agent_path` and `fpjs_result_path` variable blocks set to placeholder values from Step 1 — Terraform still requires them even though they're no longer used for routing.
  * **PAPI**: The updated property rules no longer use `FPJS_AGENT_PATH` and `FPJS_RESULT_PATH`, so no additional cleanup is needed.

[akamai-papi]: /docs/deploy-akamai-proxy-integration-via-papi

[akamai-terraform]: /docs/deploy-akamai-proxy-integration-via-terraform

[fingerprint-integrations]: https://dashboard.fingerprint.com/integrations

[js-agent-migration]: /reference/migrating-from-v3-to-v4

[proxy-github-repo]: https://github.com/fingerprintjs/akamai-proxy

[proxy-latest-release]: https://github.com/fingerprintjs/akamai-proxy/releases/latest


# Android SDK Changelog
Source: https://docs.fingerprint.com/docs/android-sdk-changelog





# Overview
Source: https://docs.fingerprint.com/docs/azure-proxy-integration



<Warning>
  **Azure proxy integration v1 is no longer supported.**

  Please use Azure Proxy Integration v2 instead.

  If you are currently using Azure integration v1, please see **[Migrating Azure proxy integration from v1 to v2](/docs/azure-proxy-integration-migration-from-v1-to-v2)**.
</Warning>

Fingerprint Azure Proxy Integration is responsible for proxying identification and agent-download requests between your website and Fingerprint through your Azure infrastructure.

The proxy integration must be served through Azure Front Door to ensure the true client IP address is captured and used for identification. Your website itself does not need to run on Azure or Front Door, although serving both through the same Front Door distribution is optimal for ease of setup and maximum accuracy benefits.

This guide explains the benefits and components of the Azure proxy integration and shows how to set it up step-by-step. It assumes a basic familiarity with Azure.

<Info>
  This guide assumes you are using [JavaScript agent v4](/reference/js-agent). If you are still
  using JavaScript agent v3, see [Azure Proxy Integration
  (v3)](/docs/v3/azure-proxy-integration) or migrate to [JavaScript agent v4](/reference/migrating-from-v3-to-v4).
</Info>

<Warning>
  **Limitations**

  Support for the Azure Proxy Integration is provided only to customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup](/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](/docs/cloudflare-integration).
</Warning>

<Warning>
  **Update expectations**

  The underlying data contract in the identification logic can change to keep up with browser and device releases. Using the Azure Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.
</Warning>

<img alt="" />

The integration consists of several components:

* Your website, which may be running on Azure Front Door but doesn't have to.
* [Azure functions](https://learn.microsoft.com/en-us/azure/azure-functions/functions-overview):
  * `proxy` — responsible for proxying requests to our CDN and API.
  * `management` — updates the main integration function.
* [Front Door distribution](https://learn.microsoft.com/en-us/azure/frontdoor/front-door-overview) which delivers the functions through Microsoft's content delivery network:
  * If your website is already running on Front Door, you can use the same distribution for the proxy integration. This is the recommended setup to maximize the accuracy benefits of the integration. See [Step 5](#step-5-configure-front-door-to-deliver-the-proxy-function) for more details.
  * If your website is not running on Front Door, you can create a new Front Door distribution just for the proxy integration (see [Step 5](#step-5-configure-front-door-to-deliver-the-proxy-function)).
* [Azure storage](https://learn.microsoft.com/en-us/azure/storage/common/storage-introduction) account stores the functions' source code. The source code is uploaded to storage during [deployment ](https://github.com/fingerprintjs/azure-frontdoor-proxy/blob/main/azuredeploy.json) and then kept up to date by the management Azure function.
* [Application Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview?tabs=net) monitors your Azure function
* [App Service Plan](https://learn.microsoft.com/en-us/azure/app-service/overview-hosting-plans) defines the operating system, the number and size of virtual machine instances, and the pricing tier used by the functions.

The proxy integration source code is 100% open-source and [available on GitHub](https://github.com/fingerprintjs/azure-frontdoor-proxy).

## The benefits of using the Azure Integration

* Ad blockers will not block the Fingerprint JavaScript agent from loading or performing identification requests. Ad blockers can block requests to Fingerprint domains but will allow requests to your own domain or subdomain.
* Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox.
* Cookies are now recognized as "first-party." This means they can live in the browser even when third-party cookies are blocked and extend the lifetime of visitor information.
* Insight and control over the identification requests in your own infrastructure.
* With the Azure Integration, you can manage an unlimited number of subdomains or paths and provide Fingerprint services to all your customers at any scale while benefiting from all the 1st-party integration improvements.
* Cookie security: Azure integration drops all the cookies sent from the origin website. The Azure function code is open-source so this behavior can be transparently verified and audited.
* Easy to meet compliance and auditing requirements.

## Prerequisites

* An Azure account.
* If you have an existing Front Door distribution that serves the web app's content you can use it to also serve the proxy function. Otherwise, you will create a new Front Door distribution that is configured to serve the proxy function on a subdomain of your website. Both scenarios are covered in [Step 5](#step-5-configure-front-door-to-deliver-the-proxy-function).

## Integration setup overview

The integration setup consists of several manual and automatic steps. Each of the following steps is discussed in detail in a separate section below.

1. Issue a *Proxy Secret* in the Fingerprint dashboard.
2. Create a route prefix used by the Azure configuration and JavaScript agent configuration on your website.
3. Deploy the Azure function and other related resources using our deployment template.
4. Verify the Azure function deployment.
5. Configure your Front Door distribution to deliver the proxy Azure function.
6. Configure the Fingerprint JavaScript agent on your website.

If you run into trouble implementing the integration, you can [contact our support](mailto:support@fingerprint.com) for assistance.

## Step 1. Issue a Proxy Secret

You need to issue a *Proxy Secret* to authenticate requests to Fingerprint API from your Azure function.

1. Go to the Fingerprint [dashboard](https://dashboard.fingerprint.com/) and select your workspace.
2. In the left-side menu, go to **API keys**.
3. Click **Create proxy key**.
4. Give it a name, for example, `Azure proxy integration`.
   1. Optionally, you can [choose an environment](/docs/multiple-environments#proxy-integrations-and-proxy-secrets) for the proxy secret.
   2. By default, the proxy secret works for all environments in your workspace.
   3. A proxy secret scoped to a specific environment can only authenticate identification requests made with a public API key from the same environment.
5. Click **Create API Key**.

You will later use this value in the `FPJS_PROXY_SECRET` variable, so store it somewhere safe. You cannot retrieve the secret later.

## Step 2. Create a route prefix

You need to create a route prefix that you will use throughout your Azure proxy integration configuration (Steps 3,4,5) and the JavaScript agent configuration on your website ([Step 6](#step-6-configure-the-fingerprint-javascript-agent-on-your-website)). Its value is arbitrary. Just decide its value and write it down somewhere.

For the rest of the guide, the route prefix will be referred to as `FPJS_ROUTE_PREFIX` to keep things easier to follow. However, the actual value used in production should be a random string value like `ore54guier`.

A random string value is required because some ad blockers might automatically block requests from any URL containing fingerprint-related terms like "fingerprint", "fpjs", "track", etc.

## Step 3. Deploy the Azure function

You can use a [deployment template](https://github.com/fingerprintjs/azure-frontdoor-proxy/blob/main/azuredeploy.json) to deploy the Azure function automatically using the Resource Manager.

<img alt="" />

[Click here to open the template deployment dialog.](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Ffingerprintjs%2Fazure-frontdoor-proxy%2Fmain%2Fazuredeploy.json/createUIDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2Ffingerprintjs%2Fazure-frontdoor-proxy%2Fmain%2FcreateUiDefinition.json)

### Basics step

1. Select your Azure **Subscription**.
2. Select or create a **Resource group** (we suggest using a separate resource group for the integration).
3. Specify **Region** and **Location**.
4. Set **Function App Name,** for example, `azure-frontdoor-proxy-app`. The final function name will have the resource group ID at the end of it, for example, `azure-frontdoor-proxy-app-appi4fghxf32z36q`.
5. Click **Next** to navigate to the next step.

### Routing configuration step

1. Set **Route Prefix** to your chosen value of `FPJS_ROUTE_PREFIX`, the value you created in [Step 2](#step-2-create-a-route-prefix) of this guide.
2. Click **Next** to navigate to the next step.

### Scaling configuration step

1. Set **Maximum instance count** to the highest number of instances the integration can scale out to under load. The template provides a default value.

   This setting is a ceiling, not a reservation. A higher value does not increase your baseline cost because instances that never start are never charged. Raising it can improve resilience to traffic spikes by letting the proxy scale out instead of throttling requests. Lowering it caps the maximum number of instances that can run concurrently during a spike.

   If you are unsure, leave the default. Consider raising it if you expect high or bursty request volumes, or lowering it if you want to bound peak-time scale-out. For guidance on choosing a value for your traffic, see [Azure Functions Flex Consumption scaling](https://learn.microsoft.com/en-us/azure/azure-functions/event-driven-scaling).

2. Click **Next** to navigate to the next step.

<Info>
  **Changing the maximum instance count after deployment**

  You can adjust this value at any time without redeploying the integration:

  1. In the [Azure portal](https://portal.azure.com), open the **Resource group** you deployed the integration into and select the function app (for example, `azure-frontdoor-proxy-app-appi4fghxf32z36q`).
  2. In the left menu, go to **Settings** > **Scale and concurrency**.
  3. Under **Maximum instance count**, enter the new value.
  4. Select **Save**. The change takes effect for subsequent scaling decisions; you do not need to restart the app.
</Info>

### Security step

1. Set **Proxy Secret** to the value of the secret generated in [Step 1](#step-1-issue-a-proxy-secret) of this guide.
2. Click **Review + Create** to validate the function.
3. Click **Create** to deploy the function.

<Note>
  **Note: Proxy secret required**

  Proxied identification requests without a valid proxy secret will result in an authentication error and fail to record identification results.
</Note>

<Note>
  **Other deployment options**

  The function code is available on [GitHub](https://github.com/fingerprintjs/azure-frontdoor-proxy) so you can build the function locally and use [Azure Function Core Tools](https://github.com/Azure/azure-functions-core-tools) to publish it on your Azure infrastructure. See the official [Azure guide here](https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local?tabs=v4%2Clinux%2Ccsharp%2Cportal%2Cbash#publish).

  Also, you can automate the deployment by using the [deployment template](https://github.com/fingerprintjs/azure-frontdoor-proxy/blob/main/azuredeploy.json) in infrastructure-as-code tools like [Terraform](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_group_template_deployment).
</Note>

## Step 4. Verify your deployment

Once deployed, you can use the function in your web resources.

<img alt="" />

1. Click **Go to resource group** to open the resource group with Fingerprint resources, used in [Step 3](#step-3-deploy-the-azure-function).
   <img alt="" />
2. In the resources list, use the **Type** column to find your **Function App**. Its name will match the name given in [Step 3](#step-3-deploy-the-azure-function). Click on the name to navigate to the function app page.
3. Inside the function app page, click **Overview** in the left-side menu.
   The overview page lists two functions:

   * `proxy` — the main integration function responsible for proxying requests from your website to our CDN and API.
   * `management` — responsible for updating the main integration function. By default it uses [timer](https://learn.microsoft.com/en-us/azure/azure-functions/functions-bindings-timer?pivots=programming-language-javascript\&tabs=python-v2%2Cin-process) trigger to check for new releases every 30 minutes. Azure Functions are set to a timeout of 10 minutes, which is necessary for the management function to perform updates correctly with each new release.

   <Warning>
     **Do not disable the management function**

     The management function (`management`) is responsible for updating the integration. It makes sure visitor identification on your website keeps up with new browser releases and fingerprinting evasion techniques. An outdated integration can lead to lower accuracy or break visitor identification completely. Don't disable or delete the management function.
   </Warning>

   Click **proxy** to open the function.
4. Inside the function page, click **Get Function Url** and copy the `default (function key)` URL. It will look like this: `https://fingerprint-pro-azure-integration-appi4fghxf32z36q.azurewebsites.net/{*restOfPath}`.
5. Build the function's status page URL by replacing the `{*restOfPath}` with `FPJS_ROUTE_PREFIX/status`.\
   For example `https://fp-pro-integration-appi4fghxf32z36q.azurewebsites.net/FPJS_ROUTE_PREFIX/status`.
6. Open the status page in your browser. If your function is running and the proxy secret and route prefix are configured, it will say: "*All environment variables are set*".

## Step 5. Configure Front Door to deliver the proxy function

To get all the first-party accuracy benefits of the integration, you need to access the proxy function through your website's domain. The proxy integration is designed to work with the Azure Front Door CDN service. Front Door replicates the Azure function to data centers across the globe and delivers it to visitors based on their geographic location.

<Note>
  Using Front Door is required to ensure the true client IP address is captured and used for identification. Proxied identification requests with a local or bogon IP address will be rejected.
</Note>

* If your website is already running on Front Door, you can use the same distribution and domain for the proxy integration → Follow only [Step 5.2](#step-5-2-add-a-route-to-front-door).
  <Note>
    This is the recommended setup. Your website and the proxy function will not only share a domain but also be served by the same CDN (from IP addresses in the same range). This has implications for cookie lifetimes in Safari — they will be saved in the browser for one year instead of 7 days.
  </Note>
* If your website is not running on Front Door, you can create a new Front Door distribution and website subdomain just for the proxy integration → Follow steps 5.1, 5.2, and 5.3.
  <Note>
    This setup results in Safari cookie lifetime being limited to 7 days, because your website and the proxy function are likely to have different IP ranges. This is still an improvement over third-party cookies getting blocked entirely by Safari, but we recommend serving your website and the proxy function using the same Front Door distribution if possible.
  </Note>

### Step 5.1 Create a Front Door distribution

If your website is already behind Front Door, you can skip this step.

1. Go to the **Front Door** service.
2. Click **Create** to create a new Front Door instance.
3. Set offering to **Azure Front Door**.
4. Set Front Door options to **Custom create**.
5. Click **Continue to create a Front Door**.
   <img alt="" />
6. Switch to the **Basics** tab:
   1. Select the **Resource group** with your Fingerprint integration (or create a new one).
   2. Set **Name** for the Front Door profile, for example, `fp-proxy-frontdoor`.
7. Select a **Tier** according to your requirements. The **Standard** tier is enough for typical Fingerprint integration scenarios.
   <img alt="" />
8. Switch to the **Endpoint** tab.
9. Click **Add an endpoint**:
   1. Set **Endpoint name**.
   2. Keep **Enable this endpoint** selected.
   3. Click **Add** to save the endpoint. Your endpoint will show up as a tile in the **Endpoint** tab.\\
      <img alt="" />
10. Inside the endpoint, click **Add a route**:
    1. Configure the route according to [Step 5.2](#step-5-2-add-a-route-to-front-door), including the subdomain setup. You can then skip Step 5.2.
    2. Click **Review + create** to validate your Front Door configuration.
11. Review the profile's summary and click **Create**.

### Step 5.2 Add a route to Front Door

1. Open your Front Door distribution.

2. On the left-side menu, go to **Settings** → **Front Door manager**.

3. Inside your Front Door endpoint, click **Add a route**.

4. Set **Name** to something descriptive like `fingerprint-integration-route`.

5. Keep **Enable route** selected (only applicable when creating a route on a pre-existing Front Door distribution, don't worry if you don't see the checkbox).

6. Set **Domains** to all domains you want to access the integration from. If your website is already behind Front Door, pick your existing domain. Azure might complain about the routes overlapping until you set **Patterns to match**.\
   Alternatively, if you need to create a new subdomain for the integration, click **Add a new domain** instead.

   1. If your DNS is managed outside Azure, switch **DNS management** to **All other DNS services**.
   2. Set **Custom domain** to the subdomain you want to use for your integration, for example: `metrics.yourwebsite.com`. Use something general, not `fingerprint.yourwebsite.com` or similar which could be blocked by ad blockers.
   3. Keep the other default settings and click **Add** to save the custom domain.

7. In **Patterns to match** add `/FPJS_ROUTE_PREFIX/*` and `/FPJS_ROUTE_PREFIX`.

8. Set **Accepted protocols** to `HTTPS only`.

9. Keep **Redirect all traffic to use HTTPS** selected.

10. Click **Add a new origin group.**
    1. Set the **Name** to something descriptive like `fp-origin-group`.
    2. Click **Add an origin**. A new form will open on top of the current one.
    3. Set the origin **Name** to something descriptive, like `fp-origin`.
    4. Set **Origin type** to `App services`.
    5. Set **Host name** to the Fingerprint integration Function app created in Step 3. The origin host header will be filled automatically.
    6. Keep the default values for all other settings.
    7. Click **Add** to save the origin.
    8. Back inside the **Add an origin group** form, keep **Enable health probes** selected.
    9. Set health probe **Path** to `/FPJS_ROUTE_PREFIX/status`.
    10. Set **Protocol** to `HTTPS`.
    11. Set **Probe method** to `GET`.
    12. Click **Add** to save the origin group.

11. Set **Forwarding protocol** to `HTTPS only`.

12. Click **Add** to save the route.

If you used the same domain and Front Door as your website for the integration, continue to Step 6. If you created a new Front Door and subdomain for the integration, you still need to verify your subdomain in Step 5.3.

### Step 5.3 Verify the integration subdomain

If you are using your website's domain for the integration, you can skip this step.

1. Inside **Front Door manager** → **Endpoint** → **Routes**, open your newly created subdomain.
   <img alt="" />
2. Under **Validation state**, click **Pending.**
3. Take the displayed **Record type** and **Record name** and add them as a `TXT` record into your website's DNS records. This proves your ownership of the domain to Azure.
4. Inside your website's DNS records, add a `CNAME` record with your chosen subdomain (for example `metrics.yourwebsite.com`) pointing to the endpoint of your Front Door distribution (for example `your-endpoint-cugsapgvd4c9epg9.z01.azurefd.net`). This redirects traffic from your subdomain to Front Door.
5. Wait until the DNS changes propagate and the domain validation state switches to **Approved**.

## Step 6. Configure the Fingerprint JavaScript agent on your website

<Note>
  **Migrating from JavaScript agent v3**

  Azure Proxy Integration remains compatible with JavaScript agent v3, so you can upgrade when it works for your rollout plan.

  When you migrate to JavaScript agent v4:

  * Remove `scriptUrlPattern` and `endpoint`
  * Replace them with a single `endpoints` option that points to the worker route, for example `https://yourwebsite.com/ROUTE_PREFIX/?region=us`
  * See [Migrating JavaScript agent from v3 to v4](/reference/migrating-from-v3-to-v4#use-endpoints-instead-of-scripturlpattern) for more details
</Note>

Use the route prefix created in [Step 2](#step-2-create-a-route-prefix) to construct the agent-download and result-endpoint URLs.

If your website and the proxy integration are behind the same Front Door distribution and domain, the JavaScript agent configuration will use URLs inside your domain, for example:

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: 'https://yourwebsite.com/FPJS_ROUTE_PREFIX/?region=us'
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  const url = 'https://yourwebsite.com/FPJS_ROUTE_PREFIX/web/v4/PUBLIC_API_KEY';
  const fpPromise = import(url)
    .then(Fingerprint => Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: 'https://yourwebsite.com/FPJS_ROUTE_PREFIX/?region=us',
  }));

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

If your website is not behind Front Door and you have set up a new Front Door distribution on a subdomain according to steps [5.1](#step-5-1-create-a-front-door-distribution), [5.2](#step-5-2-add-a-route-to-front-door), [5.3](#step-5-3-verify-the-integration-subdomain), the JavaScript agent configuration will use that subdomain to interact with Fingerprint, for example:

<CodeGroup>
  ```javascript NPM package theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  // Initialize the agent at application startup.
  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: 'https://metrics.yourwebsite.com/FPJS_ROUTE_PREFIX/?region=us'
  });

  fp.get().then((result) => console.log(result.visitor_id));
  ```

  ```javascript CDN theme={"theme":"github-dark-dimmed"}
  const url = 'https://metrics.yourwebsite.com/FPJS_ROUTE_PREFIX/web/v4/PUBLIC_API_KEY';
  const fpPromise = import(url)
    .then(Fingerprint => Fingerprint.start({
      apiKey: 'PUBLIC_API_KEY',
      region: 'us',
      endpoints: 'https://metrics.yourwebsite.com/FPJS_ROUTE_PREFIX/?region=us',
  }));

  fpPromise.then((fp) => fp.get()).then((result) => console.log(result.visitor_id));
  ```
</CodeGroup>

<Note>
  **Parameter URL nuances**

  * Pass a `region` query parameter to the `endpoints` URL in the following format: `?region=eu`. The value needs to reflect the [region](/docs/regions) of your workspace.
</Note>

If everything is configured correctly, the agent will successfully receive data using the Azure integration as its endpoint.

## Monitoring the integration

Go to **Dashboard** > [**SDKs & integrations**](https://dashboard.fingerprint.com/integrations) > **Azure** to see the status of your integration. Here you can monitor:

* If the integration is up to date.
* How many identification requests are coming through the integration (and how many are not).
* The error rate of proxied identification requests (caused by missing or incorrect proxy secret).

The information on the status page is cached so allow a few minutes for the latest data points to be reflected.

<img alt="" />

## Updating the route prefix and proxy secret

To change the Function App parameters:

1. Open your Function App page.
2. Using the left-side menu, expand **Settings** and click **Environment variables**.
3. Edit parameter values inside the **App settings**.
4. Click **Save**.

The function will restart with the new settings applied.

<img alt="" />

## Caching and compression for the Front Door route

Enable caching for the Front Door route that points to the Fingerprint proxy Azure function.

1. Go to your Front Door distribution.
2. In the left side menu, under **Settings**, go to **Optimizations**.
   <img alt="" />
3. Find the route that points to the proxy function and click **Context menu (⋯)** → **Configure route**.
   <img alt="" />
4. On the Update route page, select **Enable caching.**
5. Set **Query string caching behavior** to `Ignore Query String`.
6. Select **Enable compression**.
7. Click **Update**.

<img alt="" />

## Azure cost calculation

You can use the [Azure pricing calculator](https://azure.microsoft.com/en-us/pricing/calculator/) to estimate your expenses.

### Azure Functions

* The number of executions is roughly equal to visitor identification events multiplied by two.
* Memory size is 128 MB.
* Execution time depends on your availability settings.
* The typical duration of the agent download request is 200ms.
* The typical duration of the Fingerprint Identification API request is 500ms.

### Storage account

* A Storage account is used to store function code in your infrastructure.
* Our template has the following settings:
  * The storage type is `Block Blob Storage`.
  * Performance is `Standard`.
  * Storage Account Type is `General Purpose V2`.
  * Redundancy is `LRS`.
  * The capacity used is approximately 10 MB.

### Azure Front Door

1. The **number of requests** from your client to Front Door is roughly equal to visitor identification events multiplied by three. There are up to 3 requests for each visitor identification.
   * The first request downloads the agent script. This request is typically cached by the browser.
   * The second request calls the identification endpoint. Caching the identification request is up to you, but most of our [frontend libraries](/docs/frontend-libraries) have a caching mechanism built in.
   * Potentially, a third helper request may be used to improve accuracy. This request is typically cached by the browser.
2. The number of requests from your client to Front Door is roughly equal to visitor identification events multiplied by two.
3. Data transfer from Front Door edge to origin (your Azure Function):
   * Each identification request has a payload size of 5-10 KB.
4. Data transfer from the origin to Front Door is not charged.
5. Data transfer from Front Door to the client:
   * The agent’s size is approximately 50-60 KB, depending on the exact version and network compression algorithm used (some browsers may not support `br` encoding).
   * The identification result size is up to 1KB per request.
   * Enabling compression on the Front Door route will reduce the cost of data transfer to the client.

See [Azure Front Door billing](https://learn.microsoft.com/en-us/azure/frontdoor/billing) in the Azure documentation for more details.


# Migrating Azure Proxy integration from v1 to v2
Source: https://docs.fingerprint.com/docs/azure-proxy-integration-migration-from-v1-to-v2



This migration guide describes how to switch to Fingerprint Azure integration v2 if you are currently running the first version. The migration steps ensure zero downtime.

<Note>
  **Improvements over v1**

  * **New runtime and consumption plan**: The functions now run using the new [Flex Consumption plan](https://learn.microsoft.com/en-us/azure/azure-functions/flex-consumption-plan) and runtime 4.x.
  * **Updated Node runtime**: The v1 functions run on Node 20. The v2 functions run on Node 24.
  * **JavaScript agent v4 Support**: The v2 version of the integration fully supports the [JavaScript agent v4](/reference/js-agent) while maintaining backward compatibility with the [JavaScript agent v3](/reference/v3/javascript-agent).
</Note>

<Warning>
  Azure is sunsetting the old consumption plan and runtime 3.x. v1 of the Azure Proxy Integration will stop working after September 30, 2026. See the [Azure Functions consumption plan documentation](https://learn.microsoft.com/en-us/azure/azure-functions/consumption-plan).

  We recommend updating to the v2 of the integration as soon as possible to avoid possible downtime. The v2 version of the proxy integration is also required to use the [JavaScript agent v4](/reference/js-agent).
</Warning>

## Migration overview

1. Deploy Azure integration v2 on a new path. You will have v1 and v2 running in parallel.
2. Verify that the new integration works.
3. Switch from v1 to v2 proxy integration.
4. Optional: Migrate to [JavaScript agent v4](/reference/js-agent).
5. Optional: Remove the old integration.

## Step 1: Deploy Azure Proxy Integration v2 on a new path

### Step 1.1: Issue a proxy secret

You need a proxy secret to authenticate requests to the Fingerprint API from your Azure function.

1. Go to the Fingerprint [dashboard](https://dashboard.fingerprint.com/) and select your workspace.
2. In the left-side menu, go to **API keys**.
3. Click **Create proxy key**.
4. Give it a name, for example, `Azure proxy integration v2`.
5. Click **Create API Key**.

Store this value somewhere safe, you cannot retrieve it later.

### Step 1.2: Choose a path variable

Choose a value for `FPJS_ROUTE_PREFIX_v2` that is different from the one used by your v1 integration. Use a random string rather than a descriptive name, some ad blockers block URLs containing fingerprint-related terms like "fingerprint", "fpjs", or "track".

You will use this value in the deployment template and when configuring the JavaScript agent.

### Step 1.3: Deploy the Azure function

[Click here to open the template deployment dialog.](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Ffingerprintjs%2Fazure-frontdoor-proxy%2Fmain%2Fazuredeploy.json/createUIDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2Ffingerprintjs%2Fazure-frontdoor-proxy%2Fmain%2FcreateUiDefinition.json)

**Basics step**

1. Select your Azure **Subscription**.
2. Select or create a **Resource group**. We suggest using a separate resource group for the v2 integration.
3. Specify **Region** and **Location**.
4. Set **Function App Name**, for example, `azure-frontdoor-proxy-app-v2`.
5. Click **Next**.

**Routing configuration step**

1. Set **Route Prefix** to your `FPJS_ROUTE_PREFIX_v2` value.
2. Click **Next**.

**Security step**

1. Set **Proxy Secret** to the proxy secret generated in Step 1.1.
2. Click **Review + Create**, then **Create**.

### Step 1.4: Verify the deployment

1. After deployment completes, click **Go to resource group**.
2. In the resources list, find your **Function App** using the **Type** column and click it.
3. Click **Overview** in the left-side menu and confirm that both the `proxy` and `management` functions are listed.
4. Click **proxy**, then **Get Function URL** and copy the `default (function key)` URL.
5. Build the status page URL by replacing `{*restOfPath}` with `FPJS_ROUTE_PREFIX_v2/status` and open it in your browser. If it says *All environment variables are set*, your function is running correctly.

### Step 1.5: Add a route to your Front Door distribution

Since you already have a Front Door distribution from the v1 integration, add a new route to it for v2.

1. Open your Front Door distribution.
2. Go to **Settings** → **Front Door manager**.
3. Inside your Front Door endpoint, click **Add a route**.
4. Set **Name** to something descriptive, like `fingerprint-integration-v2-route`.
5. Keep **Enable route** selected.
6. Set **Domains** to the same domain used by your v1 integration.
7. In **Patterns to match**, add `/FPJS_ROUTE_PREFIX_v2/*` and `/FPJS_ROUTE_PREFIX_v2`.
8. Set **Accepted protocols** to `HTTPS only`.
9. Keep **Redirect all traffic to use HTTPS** selected.
10. Click **Add a new origin group**:
    1. Set **Name** to something descriptive, like `fp-origin-group-v2`.
    2. Click **Add an origin**:
       1. Set **Name** to something descriptive, like `fp-origin-v2`.
       2. Set **Origin type** to `App services`.
       3. Set **Host name** to the function app deployed in Step 1.3.
       4. Click **Add** to save the origin.
    3. Keep **Enable health probes** selected.
    4. Set health probe **Path** to `/FPJS_ROUTE_PREFIX_v2/status`.
    5. Set **Protocol** to `HTTPS`.
    6. Set **Probe method** to `GET`.
    7. Click **Add** to save the origin group.
11. Set **Forwarding protocol** to `HTTPS only`.
12. Click **Add** to save the route.

The route update may take up to 20 minutes to propagate.

Do not configure the JavaScript agent yet, that is covered in [Step 2](#step-2-verify-that-the-integration-works) and [Step 5](#step-5-remove-the-old-integration).

## Step 2: Verify that the integration works

At this point, you should have both v1 and v2 integration running side by side. You can go to their respective status pages to confirm:

* `yourwebsite.com/FPJS_ROUTE_PREFIX/status` should display a status page of Azure integration v1.x.
* `yourwebsite.com/FPJS_ROUTE_PREFIX_v2/status` should display a status page of Azure integration v2.x.

Try using the v2 integration with your client agent to test the integration. For example:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize the agent at application startup.
const fpPromise = FingerprintJS.load({
  apiKey: 'PUBLIC_API_KEY',
  scriptUrlPattern: [
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>', // [!code --]
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>', // [!code ++]
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_GET_RESULT_PATH?region=us', // [!code --]
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_GET_RESULT_PATH?region=us', // [!code ++]
    FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
  ],
});
```

All requests from the agent should go through v2 and resolve successfully. Confirm by using the **Network** tab in your browser's developer tools, as the JavaScript agent can fall back to default endpoints in case of an integration error.

## Step 3: Switch from v1 to v2

You have two options for migrating from your v1 integration to v2. Choose the one that suits you best depending on your deployment options:

* **Option A** (recommended): Update your JavaScript agent configuration to point to the v2 path. If you can update your client-side code, choose this option: it is simple, requires no downtime, and is easy to roll back.
* **Option B**: Update the Front Door distribution to route the v1 path to the v2 function. Choose this if you cannot update your client-side code, for example, because you are serving a mobile app and need to wait for users to upgrade.

### Option A: Update your client agent to use the v2 Front Door path (recommended)

Update your client agent to use the v2 integration on the new path, as shown in the previous step. Both integrations remain fully operational during the switch, making it easy to roll back in case of any problems. If you are using our [NPM package](https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro) or [client library](/docs/frontend-libraries), you can even use the v1 integration as a fallback for v2:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize the agent at application startup.
const fpPromise = FingerprintJS.load({
  apiKey: 'PUBLIC_API_KEY',
  scriptUrlPattern: [
   'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>', // [!code ++]
   'https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_GET_RESULT_PATH?region=us', // [!code ++]
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_GET_RESULT_PATH?region=us',
    FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
  ],
});
```

### Option B: Update the existing v1 route to use the v2 function

If you can't update your client-side code and can't afford downtime, you can update your v1 proxy route configuration to match the v2 configuration in the Azure UI.

1. Navigate to the deployed v2 function app in the Azure portal.
2. In the left sidebar, expand **Settings** and click **Environment Variables**.
3. Locate `fpjs_route_prefix` variable and set it to the same value used by your v1 integration. (`FPJS_ROUTE_PREFIX`).
4. Click **Save**.
5. Go to your Front Door distribution.
6. On the right side in the **Properties** tab, locate your **Endpoint hostname** and click it.
7. Locate the route of your Azure Integration v1 and click it.
8. Add an additional pattern in the **Patterns to match**: `/FPJS_ROUTE_PREFIX`
9. Replace **Origin group** with the new origin group that you've created for your v2 integration.
10. If you have caching enabled, set **Query string caching behavior** to `Ignore Query String`.
11. Click **Update**.

Requests coming to the original v1 route prefix are now being processed by the v2 function. Updating the Front Door distribution may take up to 20 minutes.

## Step 4: Migrate to JavaScript agent v4

At this point, you can start migrating your application to use the new JavaScript agent v4.

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
import * as FingerprintJS from "@fingerprintjs/fingerprintjs-pro"; // [!code --]
import * as Fingerprint from "@fingerprint/agent"; // [!code ++]

// [!code --:10]
const fpPromise = FingerprintJS.load({
  apiKey: "PUBLIC_API_KEY",
  region: "us",
  scriptUrlPattern: [
    "https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>",
  ],
  endpoint: ["https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_GET_RESULT_PATH?region=us"],
});

// [!code ++:10]
const fp = Fingerprint.start({
  apiKey: "PUBLIC_API_KEY",
  region: "us",
  endpoints: "https://yourwebsite.com/FPJS_ROUTE_PREFIX/?region=us",
});
```

To learn more, see the [JavaScript agent v4 migration guide](/reference/migrating-from-v3-to-v4).

## Step 5: Remove the old integration

When all your client application agents use the new integration, you can remove the old integration.

1. In your Front Door distribution, remove the origin group of the v1 integration. If you went with option A, you can also remove the route of the v1 integration.
2. Locate the resource group of the v1 integration.
   * If during the v1 deployment you created a new resource group and use it only for the v1 integration, simply delete it.
   * Otherwise follow steps below to only delete the v1 resources without deleting the resource group:
     1. In the resource group page, in the left sidebar expand **Settings** and click **Deployments**.
     2. Locate the deployment of the v1 integration, select the checkbox and click **Delete**.


# Bot Directory
Source: https://docs.fingerprint.com/docs/bot-detection/bot-directory

This directory lists bots Fingerprint can detect. This is not an exhaustive list, more bots are coming soon.

<Note>
  **This is not a complete list of what Fingerprint detects**

  Fingerprint detects many more bots and AI agents than are listed here. To confirm coverage for a specific bot or agent, [contact support](https://fingerprint.com/support/).
</Note>

## Bot Types

<Accordion icon="bot-message-square" title="Good bots">
  | **Result** | **Type**                                  |
  | ---------- | ----------------------------------------- |
  | `good`     | agi\_agent                                |
  | `good`     | ahrefsbot                                 |
  | `good`     | anchor\_browser                           |
  | `good`     | bedrock\_agentcore                        |
  | `good`     | bingbot                                   |
  | `good`     | browserbase\_agent                        |
  | `good`     | cartai\_agentic\_commerce\_as\_a\_service |
  | `good`     | chatgpt\_agent                            |
  | `good`     | cloudflare\_browser\_rendering            |
  | `good`     | cloudflare\_radar\_url\_scanner           |
  | `good`     | cybaaagent                                |
  | `good`     | cybaabot                                  |
  | `good`     | datadog                                   |
  | `good`     | fingerprint\_agent                        |
  | `good`     | google                                    |
  | `good`     | henryagent                                |
  | `good`     | manus\_agent                              |
  | `good`     | notte\_browser                            |
  | `good`     | prerender                                 |
  | `good`     | websitetrackerbot                         |
</Accordion>

<Accordion icon="bot-off" title="Bad bots">
  | **Result** | **Type**                    |
  | ---------- | --------------------------- |
  | `bad`      | adspower                    |
  | `bad`      | browser\_automation\_studio |
  | `bad`      | headless\_chrome            |
  | `bad`      | playwright                  |
  | `bad`      | puppeteer                   |
  | `bad`      | selenium                    |
  | `bad`      | webdriver                   |
</Accordion>

### `bot_info` metadata

Additional bot information is a detailed, modern bot metadata [format](/reference/server-api-get-event#response-bot-info) that we return for some bot categories.

| **Category**               | **Provider**     | **Name**                             | **Identity** |
| -------------------------- | ---------------- | ------------------------------------ | ------------ |
| `ai_agent`                 | `AGI Inc`        | AGI Agent                            | `signed`     |
| `ai_agent`                 | `OpenAI`         | ChatGPT Agent                        | `signed`     |
| `ai_agent`                 | `AWS`            | Bedrock AgentCore                    | `signed`     |
| `ai_agent`                 | `Browserbase`    | Browserbase Agent                    | `signed`     |
| `ai_agent`                 | `CartAI`         | CartAI Agentic Commerce as a Service | `verified`   |
| `ai_agent`                 | `Fingerprint`    | Fingerprint Agent                    | `verified`   |
| `ai_agent`                 | `Henry`          | HenryAgent                           | `signed`     |
| `ai_agent`                 | `Manus`          | Manus Agent                          | `signed`     |
| `ai_assistant`             | `Anthropic`      | Claude-User                          | `verified`   |
| `ai_assistant`             | `DuckDuckGo`     | DuckAssistBot                        | `verified`   |
| `ai_assistant`             | `Google`         | Gemini Deep Research                 | `verified`   |
| `ai_assistant`             | `Google`         | Gemini NotebookLM                    | `verified`   |
| `ai_assistant`             | `OpenAI`         | ChatGPT-User                         | `verified`   |
| `ai_browser`               | `Anchor`         | Anchor Browser                       | `signed`     |
| `ai_browser`               | `Notte`          | Notte Browser                        | `signed`     |
| `browser_automation`       | `AdsPower`       | AdsPower SunBrowser                  | `unknown`    |
| `browser_automation`       | `AdsPower`       | AdsPower FlowerBrowser               | `unknown`    |
| `browser_automation`       | `Cloudflare`     | Cloudflare Browser Rendering         | `signed`     |
| `monitoring_and_analytics` | `Cloudflare`     | Cloudflare Radar URL Scanner         | `signed`     |
| `monitoring_and_analytics` | `WebsiteTracker` | WebsiteTrackerBot                    | `verified`   |
| `security`                 | `Cybaa`          | CybaaAgent                           | `signed`     |
| `security`                 | `Cybaa`          | CybaaBot                             | `verified`   |
| `unknown`                  | `Google`         | Google                               | `verified`   |

### Useful links

* [**Add your bot to Fingerprint Directory ↗**](https://dashboard.fingerprint.com/submit-bot)
* [**Test your Web Bot Auth implementation ↗**](https://fingerprint.com/web-bot-auth/test/)


# Bot Detection Overview
Source: https://docs.fingerprint.com/docs/bot-detection/overview

Overview of Fingerprint bot detection for AI automation, browsers and tools

## What is Fingerprint Bot Detection?

Fingerprint Bot Detection detects automated activity on your websites or API endpoints. It detects both AI tools (agents, assistants) and traditional bots. When performing bot detection, Fingerprint analyzes hundreds of browser attributes and network signals and gives you back a bot detection result with one of three values:

* **Good bot** - includes several categories of bots, such as authorized AI agents, AI assistants, verified search crawlers, marketing, monitoring, and SEO optimization tools.
* **Bad bot** - includes browser automation tools like Selenium, Puppeteer, Playwright, or anything that impersonates verified tools. Bad bots can take over accounts, submit spam, steal passwords, scrape data, waste resources, etc.
* **Bot not detected** - the visitor is likely a human using a regular browser.

<Expandable title="AI tools detection">
  Fingerprint supports the detection of AI tools, such as AI agents and AI assistants. When an AI tool is detected, additional bot metadata is returned in the `bot_info` object that includes:

  * Category (`ai_assistant`, `ai_agent`, etc)
  * Identity (`signed`, `verified`, `unknown`, or `spoofed`)
  * Provider (who operates the bot, e.g. OpenAI)
  * Name (the name of the bot, e.g. ChatGPT)
</Expandable>

You can use the provided bot detection result to better understand your AI and human traffic or implement protective measures against malicious bots.

## Viewing bot traffic in the Dashboard

To see the bots reaching your application without writing any code, go to **Dashboard** > [**Bots & AI agents**](https://dashboard.fingerprint.com/bot-detection). It breaks your automated traffic down by category, provider, and identity, and lets you inspect individual automation events.

See [Bots and AI agents](/docs/dashboard-bots-ai-agents) for a guide to those pages.

## How to enable Fingerprint Bot Detection?

If you want to use Fingerprint Bot Detection, upgrade to the Pro Plus plan. If you have an Enterprise plan, reach out to your Customer Success Manager or [Fingerprint support team](https://fingerprint.com/support/).

## Integrating Bot Detection

Bot detection supports two integration methods: JavaScript agent and Flow worker (does not require JavaScript). They can be used together. This section covers the JavaScript agent integration. See [Flow worker integration](#flow-worker-integration-currently-in-beta) in the Automation Intelligence API section below.

### JavaScript agent integration

This method is ideal to detect browser automation or AI agents that orchestrate browsers. It also supports antidetect browsers, and traditional browser automation libraries, such as Playwright, Selenium, or Puppeteer.

To use this integration:

1. Add the [JavaScript agent](https://docs.fingerprint.com/docs/install-the-javascript-agent) in the frontend part of your web application.
2. Get the [`event_id`](https://docs.fingerprint.com/reference/js-agent-get-function#event_id) from the JavaScript agent response and pass it to your server.
3. Use [Fingerprint Events API](https://docs.fingerprint.com/reference/server-api-get-event)  from your backend to retrieve the Bot Detection result. Use the information about AI tools and bots in your business logic.

### JavaScript agent

The JavaScript agent is a client-side library that collects browser signals and sends them to the Fingerprint backend. The library returns an object with multiple fields, but for Bot detection only the `event_id` is needed to get the results on the backend.

<Note>
  **Bot Detection and JavaScript agent versions**

  Bot Detection works only with JavaScript agent version 3.7.0 or newer. Check your version and [update](https://docs.fingerprint.com/docs/migrating-from-fingerprintjs-to-fingerprint-pro) it if needed.
</Note>

### Bot Detection results on the client side

Since the data from the client browser might be spoofed by fraudulent parties, Fingerprint strongly recommends server verification using the [Server API](https://docs.fingerprint.com/reference/server-api-get-event).

Bad actors can replace the `event_id` with a fake value or completely delete this field. Check the request timestamp returned by the Server API – it shouldn't be older than several seconds or minutes depending on the implemented scenario. If the `event_id` doesn't pass the verification, you need to ask your users for additional verification (CAPTCHA, 2FA) or deny access to the requested resource.

However, the most secure way of using the Fingerprint platform is [Zero Trust Mode](https://docs.fingerprint.com/docs/zero-trust-mode) which makes only `event_id` available on the frontend.

### Native mobile libraries

Bot Detection doesn't currently support native mobile libraries.

### Fingerprint's SDKs and libraries

Bot Detection is supported by all [provided client and server-side libraries](https://docs.fingerprint.com/reference/server-sdks), but the AI tool detection results are available in [server API v4](https://docs.fingerprint.com/reference/server-api-get-event) or later.

## Automation Intelligence API: detecting automation without a browser

The Automation Intelligence API is a separate, standalone API (Public Preview) that detects the same kind of automated traffic as Bot Detection, such as AI agents, AI assistants, and AI browsers. Unlike the JS-based Bot Detection described above, it detects automation from HTTP request metadata alone, such as headers, method, URL, and IP address, with no JavaScript agent and no browser execution required. It's also platform-agnostic: it works with any CDN provider, cloud platform, or server backend, unlike the Flow worker integration, which is Cloudflare-specific.

| Dimension                                                                                  | JS-based Bot Detection (Smart Signal)                                  | Automation Intelligence API                                                 |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Data source                                                                                | Browser attributes + network signals collected by the JavaScript agent | HTTP request metadata only (headers, method, URL, IP)                       |
| Requires JavaScript execution                                                              | Yes (JS agent integration); Flow worker path does not                  | No                                                                          |
| Deployment                                                                                 | Frontend (JS agent) + your backend                                     | Any CDN, cloud platform, or server backend, edge, pre-origin, or middleware |
| Detects browser automation tools (Selenium, Puppeteer, Playwright) and antidetect browsers | Yes                                                                    | Not applicable — there is no browser to inspect                             |
| Detects AI agents / AI assistants over plain HTTP (no browser)                             | No                                                                     | Yes, on any platform                                                        |
| Adds IP intelligence (geolocation, datacenter, proxy, VPN)                                 | Yes                                                                    | Yes                                                                         |
| Status                                                                                     | Generally available                                                    | Public Preview                                                              |
| Combine with Identification (`visitor_id`)                                                 | Yes, recommended, same JS agent + `event_id`                           | Not applicable — no visitor identification                                  |

### When to use which

Use JS-based Bot Detection (JS agent) when you control the frontend and want to detect browser-level automation, such as headless browsers, Selenium, Puppeteer, Playwright, or antidetect browsers, and want to combine bot detection with visitor Identification in the same request.

Use the Automation Intelligence API when traffic reaches your server or edge directly over HTTP with no browser and no JavaScript execution at all, for example AI agents or assistants calling your API directly, MCP servers, or any backend-to-backend traffic, and when you want edge or pre-origin detection.

JS-based Bot Detection and the Automation Intelligence API aren't mutually exclusive: they cover different traffic (browser-executed vs. non-browser HTTP), so many teams run both.

To get the best bot detection accuracy and coverage, use the Automation Intelligence API together with the JavaScript agent integration.

The Dashboard keeps the two methods side by side for the same reason. On the [Bots & AI agents](/docs/dashboard-bots-ai-agents) Overview page, the **Automation Intelligence API** and **JS Agent** tabs report the traffic each method detected, so you can compare coverage across your own traffic.

For full request/response details, see the [Automation Intelligence API](https://docs.fingerprint.com/reference/automation-intelligence-api) reference.

### Flow worker integration (currently in beta)

If you want to detect AI tools and bots at the edge level, use the Flow integration running on Cloudflare. Flow's edge bot detection is built on top of the Automation Intelligence API described above.

Flow workers can detect AI agents, AI assistants, and bots that access your pages and API endpoints.

After [enabling **Edge Bot Detection**](https://docs.fingerprint.com/docs/flow-deployments#using-a-flow-worker-to-detect-bots-at-the-edge), the Flow worker provides IP intelligence and bot detection data to your pages and API endpoints by setting HTTP request headers in the requests it forwards. The headers are delivered to your protected origins synchronously with each request.

This method does not require the JavaScript agent and will work for all bot types.

## Identification and Bot Detection

Fingerprint Identification and Bot Detection produce the best results when used together.

A combination of Identification and Bot Detection gives you a powerful tool to prevent online fraud. Using both products is recommended. One JavaScript agent running in the browser and one `event_id` value to get both identification and bot detection results on the backend without additional latency.

### Useful links

* [**Bots and AI agents**](/docs/dashboard-bots-ai-agents) - analyze your bot traffic and investigate automation events in the Dashboard
* [**Bot Directory**](https://docs.fingerprint.com/docs/bot-detection/bot-directory) - list of bots and AI agents Fingerprint can detect
* [**Automation Intelligence API**](https://docs.fingerprint.com/reference/automation-intelligence-api) - detect AI agents and automation from HTTP request metadata alone, without a JavaScript agent (Public Preview)
* [**Collect Intelligence endpoint**](https://docs.fingerprint.com/reference/automation-intelligence-api-collect-intelligence) - the API reference for the Collect Intelligence endpoint


# Web Bot Auth Implementation
Source: https://docs.fingerprint.com/docs/bot-detection/web-bot-auth-implementation

Web Bot Auth is used as a verification method for verified bots and signed agents.

This guide explains how to implement Web Bot Auth signing in your AI agent and register it with Fingerprint. Registering your bot has several advantages: it becomes an authorized bot and Fingerprint will not flag it as malicious. You can also decide how your bot is represented by Fingerprint APIs, by picking the desired bot name, category and provider.

# Web Bot Auth

Web Bot Auth is an authentication method that leverages cryptographic signatures in HTTP messages to verify that a request comes from an authorized AI Agent.

It relies on two active IETF drafts: a [directory draft ↗](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory) allowing the agent to share their public keys, and a [protocol draft ↗](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture) defining how these keys should be used to attach agent’s identity to HTTP requests.

This documentation goes over specific integration within Fingerprint.

# **Generate a valid signing key**

You need to generate a signing key which will be used to authenticate your agent’s requests.

Generate a unique [Ed25519 ↗](https://ed25519.cr.yp.to/) private key to sign your requests. This example uses the [OpenSSL ↗](https://openssl-library.org/) `genpkey` command:

```bash theme={"theme":"github-dark-dimmed"}
# make sure you're using the latest OpenSSL, not an older LibreSSL
# older versions of LibreSSL don't support Ed25519
# you can install the latest version with homebrew
openssl genpkey -algorithm ed25519 -out private-key.pem
```

Needless to say, keep your private-key.pem file secret.

**Extract your public key**

```bash theme={"theme":"github-dark-dimmed"}
openssl pkey -in private-key.pem -pubout -out public-key.pem
```

**Convert the public key to JSON Web Key (JWK) using a tool of your choice.**

This example uses [`jwker ↗`](https://github.com/jphastings/jwker) command line application.

```bash theme={"theme":"github-dark-dimmed"}
go install github.com/jphastings/jwker/cmd/jwker@latest
jwker public-key.pem public-key.jwk
```

By following these steps, you have generated a private key and a public key, then converted the public key to a JSON web key (jwk) format.

<Accordion title="JSON web key (jwk) file example">
  ```json theme={"theme":"github-dark-dimmed"}
  {"kty":"OKP","crv":"Ed25519","x":"HzO8jiKnwNPaQZDnTzQN5_GrHwdFb8IqT-Z-HTxus44"}
  ```
</Accordion>

**Compute the JWK thumbprint and add it as a `kid` attribute**

Now you need to generate the [base64 URL-encoded JWK thumbprint ↗](https://www.rfc-editor.org/rfc/rfc8037.html#appendix-A.3) from the public key.

<Accordion title="JWK thumbprint code example and result">
  ```javascript theme={"theme":"github-dark-dimmed"}
  const crypto = require('crypto');
  const fs = require('fs');
  // reading the public key in JWK format we created in the previoius step
  const jwk = JSON.parse(fs.readFileSync('public-key.jwk'));

  // taking only the required attributes in sorted order (canonicalization)
  const required = Object.fromEntries(
    ['crv', 'kty', 'x'].map(k => [k, jwk[k]])
  );

  // calculating the thumbprint
  const kid = crypto
    .createHash('sha256')
    .update(JSON.stringify(required))
    .digest('base64url');

  // adding the thumbprint hash as a new `kid` attribute (key ID)
  fs.writeFileSync('public-key.jwk', JSON.stringify({ ...jwk, kid }));

  ```

  The resulting file should look like this:

  ```json theme={"theme":"github-dark-dimmed"}
  {"kty":"OKP","crv":"Ed25519","x":"HzO8jiKnwNPaQZDnTzQN5_GrHwdFb8IqT-Z-HTxus44",
  "kid":"KYG4GtgVVPWw3r1AXgM6fYFw5kAvRZiJVxZY1Rsgc3Q"}
  ```
</Accordion>

At this stage you should have your public key in JWK format with the `kid` attribute required for Web Bot Auth, now it's time to host it publicly.

# Host a key directory

You need to host a key directory which creates a way for your agent to authenticate its requests to Fingerprint. This directory should follow the definition from the active IETF [draft draft-meunier-http-message-signatures-directory-05 ↗](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory-05).

<Steps>
  <Step title="Host a key directory">
    Host a key directory at `https://ai-agent.fyi/.well-known/http-message-signatures-directory` (note that the full path is a requirement). This key directory should serve a JSON Web Key Set (JWKS) with the public key derived from your private signing key.
  </Step>

  <Step title="Serve the directory over HTTPS">
    **This URL should serve a standard JWKS**

    Besides `x`, `crv`, `kid`, and `kty`, you can include other standard JSON Web Key parameters. Multiple Ed25519 keys are supported. Only those for which you provide a signature in the above format are going to be used. Fingerprint will ignore all other key types and key parameters except those containing `kty`, `crv`, `kid`, and `x`created above.

    <Accordion title="Hosted JWKS example">
      ```bash theme={"theme":"github-dark-dimmed"}
      $ curl https://ai-agent.fyi/.well-known/http-message-signatures-directory
      {"keys": [{"kty":"OKP","crv":"Ed25519","x":"HzO8jiKnwNPaQZDnTzQN5_GrHwdFb8IqT-Z-HTxus44","kid":"KYG4GtgVVPWw3r1AXgM6fYFw5kAvRZiJVxZY1Rsgc3Q","use":"sig"}]}
      ```
    </Accordion>
  </Step>

  <Step title="Ensure correct media type">
    Ensure the directory response has the `Content-Type` HTTP header value of `application/http-message-signatures-directory+json`.

    <Accordion title="How to verify the content-type header">
      ```bash theme={"theme":"github-dark-dimmed"}
      $ curl -si https://ai-agent.fyi/.well-known/http-message-signatures-directory \
        | grep -i -E "content-type:"
      # expected output
      content-type: application/http-message-signatures-directory+json

      ```
    </Accordion>
  </Step>
</Steps>

# Register Your Agent

You can submit a request to register your agent using this form in the Fingerprint Dashboard: [Submit Your Bot](https://dashboard.fingerprint.com/submit-bot).

After submitting all the required information, please wait 1-2 weeks for the agent registration. You’ll get a confirmation email when we have successfully registered  your agent.

# Sign Your Requests

After a successful agent registration, start signing the requests. The signature protocol is defined in [draft-meunier-web-bot-auth-architecture-05 ↗](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture-05).

Fundamentally, signing the requests means adding three mandatory HTTP signature headers to each request that your agent makes: `Signature`, `Signature-Input`, and `Signature-Agent`.

## Choose a set of components to sign

A component is either an HTTP header, or any [derived components ↗](https://www.rfc-editor.org/rfc/rfc9421#name-derived-components) in the HTTP Message Signatures specification.

Fingerprint recommends the following:

Choose at least the `@authority` and `signature-agent`  components. You can optionally add more, such as HTTP method or another HTTP header.  The `@authority` represents the host you are sending requests to. The `signature-agent` is the  root URI of the agent’s public key directory.

Consider this example:

| Name                          | Value                                                                |
| ----------------------------- | -------------------------------------------------------------------- |
| AI agent public key directory | `https://ai-agent.fyi/.well-known/http-message-signatures-directory` |
| `signature-agent` component   | `"https://ai-agent.fyi"`                                             |
| AI agent making requests to   | `https://example.com/blog/2029-12-31-introduction`                   |
| `@authority` component        | `"example.com"`                                                      |

<Note>
  **Use components with only ASCII values.**

  Fingerprint currently does not support `bs` or `sf` parameter designed to serialize non-ASCII values into ASCII equivalents.
</Note>

## Construct the required headers

Construct the three required headers for Web Bot Auth.

### `Signature-Agent` header

Construct a `Signature-Agent header ↗` that points to your key directory root URI. Note that Fingerprint will fail to verify a message if:

* The message includes a `Signature-Agent` header that is not an `https://`
* The `Signature-Agent` is not a bare domain (paths, query params are not allowed)
* The message includes a valid URI but does not enclose it in double quotes. This is due to `Signature-Agent` being a [structured field ↗](https://www.rfc-editor.org/rfc/rfc8941.html)
* The message includes a structured field [label](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture-05#section-5.7.1\$0) (e.g. **sig1**="[https://ai-agent.fyi](https://ai-agent.fyi)"), as labeling is not supported.

### `Signature-Input` header

Construct a [`Signature-Input header ↗`](https://www.rfc-editor.org/rfc/rfc9421#name-the-signature-input-http-fi) over your chosen components. The header must meet the following requirements.

| **Required component parameter** | **Requirement**                                                                                                                                                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tag`                            | web-bot-auth                                                                                                                                                                                                                                     |
| `keyid`                          | This should be equal to the `kid` value of the public key<br />(notice the difference in naming, `keyid` vs `kid`)                                                                                                                               |
| `alg`                            | ed25519                                                                                                                                                                                                                                          |
| `created`                        | This should be equal to a Unix timestamp associated with when the message was sent by your agent                                                                                                                                                 |
| `expires`                        | This should be equal to a Unix timestamp associated with when Fingerprint should no longer attempt to verify the message. <br />A short `expires` reduces the likelihood of replay attacks, and Fingerprint recommends using a one hour duration |
| `nonce`                          | Strongly recommended: a random value that must not be reused, at least 16 bytes, base64 encoded                                                                                                                                                  |

### `Signature` header

Construct a [`Signature header ↗`](https://www.rfc-editor.org/rfc/rfc9421#name-the-signature-http-field) over your chosen components by signing them with your private key and converting to base64.

<Accordion title="JavaScript example of header generation">
  ```javascript theme={"theme":"github-dark-dimmed"}
  /**
  * Build and sign the HTTP message signature for a given URL.
  * Signed components: @authority, signature-agent
  * @param {string} url - The full URL of the request being signed
  * @returns {{ 'signature-agent': string, 'signature-input': string, 'signature': string }}
  */
  async function getSignatureHeaders(url) {
    const signatureAgentUri = 'https://ai-agent.fyi';
    const { hostname } = new URL(url);
    
    const created = Math.floor(Date.now() / 1000);
    // expires = now + 1 hour
    const expires = created + 60*60;
    
    // Component values
    const authorityValue = hostname;
    
    const nonce = crypto.randomBytes(16).toString('base64');
    
    // Signature Input string (what gets signed)
    // Format per RFC 9421 Section 2.1:
    //   "<component-name>": <value>\n  (one per component)
    //   "@signature-params": <sig-params>
    const signatureParams =
    `("@authority" "signature-agent")` +
    `;created=${created}` +
    `;expires=${expires}` +
    `;keyid="${KID}"` + // KID is the JWK thumbprint from the public key
    `;alg="ed25519"` +
    `;nonce="${nonce}"` +
    `;tag="web-bot-auth"`;
    
    // Signature base string per RFC 9421 Section 2.5
    // Each component line: "<name>": <value>
    // Header values are quoted strings; @authority is a plain token (hostname)
    const signingInput = [
    `"@authority": ${authorityValue}`,
    `"signature-agent": "${signatureAgentUri}"`,
    `"@signature-params": ${signatureParams}`,
    ].join('\n');
    
    // Sign with Ed25519 private key
    const signature = crypto.sign(null, Buffer.from(signingInput), PRIVATE_KEY_PEM);
    
    return {
    'signature-agent': `"${signatureAgentUri}"`,
    'signature-input': `sig1=${sigParams}`,
    'signature': `sig1=:${signature.toString('base64')}:`,
    };
  }
  ```
</Accordion>

### Add the headers to your agent’s requests

Attach these three headers to your agent’s requests. Note that all requests need to be signed, including requests that make fetch requests or download static resources.

One option to attach custom headers to all requests is by using [Page.route ↗](https://playwright.dev/docs/api/class-route) functionality of Playwright.

An example request header collection may look like this:

```bash theme={"theme":"github-dark-dimmed"}
Signature-Agent: "https://ai-agent.fyi"
Signature-Input: sig1=("@authority" "signature-agent")
 ;created=1735689600;expires=1735693200
 ;keyid="poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U"
 ;alg="ed25519"
 ;nonce="3q2+7oBVKDJKNGHs1A9pYQ=="
 ;tag="web-bot-auth"
Signature: sig1=:jdq0SqOwHdyHr9+r5jw3iYZH6aNGKijYp/EstF4RQTQdi5N5YYKrD+mCT1HA1nZDsi6nJKuHxUi/5Syp3rLWBA==:
```

<Info>
  **All requests**, made by your agent, must be signed, including static resource (images, javascript) and [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) requests. If using Playwright to add custom headers is not an option, an alternative way to do it is via a browser extension.
</Info>

If you have any questions, please reach out to **`bot-registration@fingerprint.com`**

## Helpful Links

* [**Example of a public key directory ↗**](https://chatgpt.com/.well-known/http-message-signatures-directory)

## Next Steps

<Columns>
  <Card title="Test your Web Bot Auth implementation ↗" icon="braces" href="https://fingerprint.com/web-bot-auth/test">
    Using Fingerprint's Web Bot Auth Verifier (WBAV) app to test if your agent adheres to the standard
  </Card>

  <Card title="Submit your agent to Fingerprint directory" icon="shield" href="https://dashboard.fingerprint.com/submit-bot">
    Submit your agent or bot to the Fingerprint Bot Directory
  </Card>

  <Card title="Automation Intelligence API reference" icon="code" href="/reference/automation-intelligence-api">
    Send requests to the Collect Intelligence endpoint and read the response fields.
  </Card>
</Columns>


# Changelog (JavaScript agent)
Source: https://docs.fingerprint.com/docs/changelog





# Deploy Akamai Integration using Property Manager API
Source: https://docs.fingerprint.com/docs/deploy-akamai-proxy-integration-via-papi



<Info>
  **Before you start: Read the general Akamai guide**

  This document only covers deploying the Fingerprint Akamai proxy integration using the Akamai Property Manager API ([PAPI][akamai-papi]). It assumes you have already read the [general Akamai guide][akamai-guide] and completed the following steps:

  * [Step 1][akamai-step-1]: You have issued a proxy secret in the Fingerprint Dashboard (`FPJS_PROXY_SECRET`).
  * [Step 2][akamai-step-2]: You have defined a path variable for the integration (`FPJS_INTEGRATION_PATH`)

  If you want to use Terraform instead of PAPI to install the integration, see [Deploy Akamai proxy integration using Terraform][akamai-terraform].
</Info>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup][custom-subdomain] or [Cloudflare Proxy Integration][cloudflare-proxy].
</Warning>

***

## Prerequisites

This deployment guide assumes you already have a working Akamai property and are familiar with the Akamai Control Panel. It uses [Postman][postman] to make the HTTP requests, but feel free to adjust the instructions to use your preferred HTTP client.

## Step 3: Authenticate with EdgeGrid

1. Follow the Akamai documentation to [Create EdgeGrid authentication credentials][akamai-auth]. You should end up downloading a credentials text file containing the values used below.

2. Inside Postman, use the values from the credentials file to configure the EdgeGrid authentication for your HTTP requests:
   1. Go to the **Authorization** tab.
   2. Set the **Type** to `Akamai EdgeGrid`.
   3. Set `Access Token`, `Client Token`, and `Client Secret` to the values from the credentials file.
   4. Set the base URL of the request according to the `host` value from the credentials file, e.g. `https://akab-xxxxxxxx.luna.akamaiapis.net`.

> Note: If your HTTP client does not support EdgeGrid authentication, you can use the same values to manually create the EdgeGrid authentication header. See the [EdgeGrid Protocol Specification][akamai-edgegrid-spec] for more details.

## Step 4: Clone the Akamai integration repository

1. Clone [the repository][proxy-github-repo]:

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  git clone git@github.com:fingerprintjs/akamai-proxy.git
  ```
</CodeGroup>

2. Install dependencies using [PNPM][pnpm]:

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  pnpm install
  ```
</CodeGroup>

## Step 5: Generate Patch Body

Use the `build` npm command to generate the integration's property rules for your Akamai property. Use the values from [previous steps][akamai-guide] to configure the command:

* `integration-path` should be a short, unique string — avoid using `fpjs` or other recognizable words.
* `proxy-secret` can be created in [Fingerprint Dashboard → API Keys][fingerprint-api-keys].

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  pnpm build --type patchBody \
      --integration-path "FPJS_INTEGRATION_PATH" \
      --proxy-secret "FPJS_PROXY_SECRET"
  ```
</CodeGroup>

<Note>
  Replace variables between double quotes with the values you want to use. For example, `"FPJS_INTEGRATION_PATH"` should be replaced with the value you set for `FPJS_INTEGRATION_PATH` in [Step 2][akamai-step-2].
</Note>

The output will be saved to `dist/patch-body/body.json`.

## Step 6: Deploy using Property Manager API

Use the following sequence of PAPI requests to collect the necessary data and deploy the integration.

* `baseURL` is created from the `host` value from the credentials file, e.g. `https://akab-xxxxxxxx.luna.akamaiapis.net`.
* Authenticate all requests using EdgeGrid credentials as described in [Step 3](#step-3-authenticate-with-edgegrid).

### Step 6.1: Get your Contract ID

<CodeGroup>
  ```http theme={"theme":"github-dark-dimmed"}
  GET https://{baseURL}/papi/v1/contracts
  ```
</CodeGroup>

**Sample Response:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "accountId": "act_A-CCT5678",
    "contracts": {
      "items": [
        {
          "contractId": "ctr_C-0N7RAC71",
          "contractTypeName": "DIRECT_CUSTOMER"
        }
      ]
    }
  }
  ```
</CodeGroup>

Save the `contractId` to use in later requests.

### Step 6.2: Get your Group ID

<CodeGroup>
  ```http theme={"theme":"github-dark-dimmed"}
  GET https://{baseURL}/papi/v1/groups
  ```
</CodeGroup>

**Sample Response:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "accountId": "act_A-CCT3456",
    "accountName": "Internet Company",
    "groups": {
      "items": [
        {
          "contractIds": ["ctr_C-0N7RAC71"],
          "groupId": "grp_32145",
          "groupName": "Example.com-1-1TJZH5"
        }
      ]
    }
  }
  ```
</CodeGroup>

Save the `groupId` associated with your `contractId` to use in later requests.

### Step 6.3: Get your Property ID

<CodeGroup>
  ```http theme={"theme":"github-dark-dimmed"}
  GET https://{baseURL}/papi/v1/properties?contractId=ctr_C-0N7RAC71&groupId=grp_32145
  ```
</CodeGroup>

**Sample Response:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "properties": {
      "items": [
        {
          "accountId": "act_A-CCT9012",
          "assetId": "aid_101",
          "contractId": "ctr_C-0N7RAC7",
          "groupId": "grp_54321",
          "latestVersion": 2,
          "propertyId": "prp_175780",
          "propertyName": "example.com"
        }
      ]
    }
  }
  ```
</CodeGroup>

Find the property you want to deploy the integration to. Save its `propertyId` and `latestVersion` to use in later requests.

### Step 6.4: Get your Property Versions (optional but recommended)

To make changes to your property, you first need to clone one of its versions. To decide which version to clone, you can get the list of all versions for your property.

<CodeGroup>
  ```http theme={"theme":"github-dark-dimmed"}
  GET https://{baseURL}/papi/v1/properties/{propertyId}/versions?contractId=ctr_C-0N7RAC71&groupId=grp_32145
  ```
</CodeGroup>

**Sample Response:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "accountId": "act_A-CCT7890",
    "assetId": "aid_101",
    "contractId": "ctr_C-0N7RAC71",
    "groupId": "grp_54321",
    "propertyId": "prp_173136",
    "propertyName": "981.catalog.jsmith.net",
    "versions": {
      "items": [
        {
          "propertyVersion": 2,
          "note": "updated caching",
          "productionStatus": "INACTIVE",
          "stagingStatus": "ACTIVE"
        },
        {
          "propertyVersion": 1,
          "note": "initial version",
          "productionStatus": "ACTIVE",
          "stagingStatus": "INACTIVE"
        }
      ]
    }
  }
  ```
</CodeGroup>

### Step 6.5: Clone the current version of your property

<CodeGroup>
  ```http theme={"theme":"github-dark-dimmed"}
  POST https://{baseURL}/papi/v1/properties/{propertyId}/versions?contractId=ctr_C-0N7RAC71&groupId=grp_32145
  ```
</CodeGroup>

**Request Body:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "createFromVersion": PROPERTY_VERSION_TO_CLONE
  }
  ```
</CodeGroup>

<Note>
  `PROPERTY_VERSION_TO_CLONE` is the version number of the version you want to clone. For example, if you want to clone the version 2 of your property, set this value to `2`.
</Note>

**Sample Response:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "versionLink": "/papi/v0/properties/prp_173136/versions/2?contractId=ctr_C-0N7RAC71&groupId=grp_15225"
  }
  ```
</CodeGroup>

### Step 6.6: Remove existing Fingerprint artifacts (if needed)

If your Akamai property already has the Fingerprint proxy integration installed, manually remove the Fingerprint artifacts before updating the integration. Otherwise, some artifacts will be duplicated and the integration will not work.

1. Navigate to [Akamai Control Center][akamai-control-center] → Properties.
2. Find the cloned property version.
3. Click **Edit** to begin editing rules.
4. Navigate to the **Variables** section and remove all variables that start with `PMUSER_FPJS_`.
5. Scroll to the bottom of the rule tree and delete the rule named **Fingerprint**.
6. Click **Save** to confirm the cleanup.

### Step 6.7: Patch the new version with Fingerprint integration rules

Finally, send a PATCH request to update your property's rule tree with the Fingerprint integration rules:

<CodeGroup>
  ```http theme={"theme":"github-dark-dimmed"}
  PATCH https://{baseURL}/papi/v1/properties/{propertyId}/versions/{newVersion}/rules?contractId=ctr_C-0N7RAC71&groupId=grp_32145
  ```
</CodeGroup>

* **Request body:** Copy-paste the content of the `dist/patch-body/body.json` file you created in [Step 5](#step-5-generate-patch-body).
* **Content-type:** header `application/json-patch+json`

**Sample Response:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "accountId": "act_A-CCT1234",
    "contractId": "ctr_K-0N7RAK71",
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "groupId": "grp_12345",
    "propertyId": "prp_173136",
    "propertyName": "mytestproperty.com",
    "propertyVersion": 3,
    "ruleFormat": "v2015-08-08",
    "rules": {
      "name": "default",
      "behaviors": [],
      "children": []
    }
  }
  ```
</CodeGroup>

### Step 6.8: Activate the Patched Version

<CodeGroup>
  ```http theme={"theme":"github-dark-dimmed"}
  POST https://{baseURL}/papi/v1/properties/{propertyId}/activations?contractId=ctr_C-0N7RAC71&groupId=grp_32145
  ```
</CodeGroup>

* **Request body:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "propertyVersion": PROPERTY_VERSION_TO_ACTIVATE,
    "network": "PRODUCTION",
    "notifyEmails": ["NOTIFY_EMAIL_ADDRESS_ABOUT_ACTIVATION_STATUS"],
    "acknowledgeAllWarnings": true,
    "activationType": "ACTIVATE"
  }
  ```
</CodeGroup>

<Note>
  `PROPERTY_VERSION_TO_ACTIVATE` is the version number of the version you previously cloned. For example, if you cloned version 2 of your property and created version 3, set this value to `3`.
</Note>

<Note>
  Please do not forget to replace `NOTIFY_EMAIL_ADDRESS_ABOUT_ACTIVATION_STATUS` with your email address.
</Note>

**Sample Response:**

<CodeGroup>
  ```bash theme={"theme":"github-dark-dimmed"}
  {
    "activationLink": "/papi/v0/properties/prp_173136/activations/atv_67037?contractId=ctr_K-0N7RAK7&groupId=grp_15225"
  }
  ```
</CodeGroup>

<Warning>
  This will directly activate the version in `PRODUCTION`. If you want to deploy to staging first,
  change the `network` value to `STAGING`.
</Warning>

### Troubleshooting API requests

If you encounter an error, check the following:

| Issue                     | Resolution                                                                                                        |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `403 Unauthorized`        | Ensure your EdgeGrid credentials are correct and Postman is configured properly.                                  |
| `409 Conflict`            | You are trying to patch an already active version. Clone a new version first.                                     |
| `400 Bad Request`         | Check that your patch body is valid JSON and that `Content-Type` is set correctly.                                |
| `503 Service Unavailable` | [Check troubleshooting guide for SSL Verification error](/docs/troubleshooting-akamai-supernet-error)             |
| Activation status unknown | Use the Akamai Control Center to monitor activations. The Property Manager API does not support progress polling. |

## Step 7: Configure the Fingerprint client agent

Please see the main Akamai proxy integration guide to [Configure the client agent on your website or mobile app][akamai-configure-agent].

[akamai-papi]: https://techdocs.akamai.com/property-mgr/reference/api

[akamai-guide]: /docs/akamai-proxy-integration

[akamai-step-1]: /docs/akamai-proxy-integration#step-1-issue-a-fingerprint-proxy-secret

[akamai-step-2]: /docs/akamai-proxy-integration#step-2-create-a-path-variable

[akamai-terraform]: /docs/deploy-akamai-proxy-integration-via-terraform

[akamai-control-center]: https://control.akamai.com/

[akamai-configure-agent]: /docs/akamai-proxy-integration#configure-fingerprint-agent

[akamai-auth]: https://techdocs.akamai.com/developer/docs/set-up-authentication-credentials

[akamai-edgegrid-spec]: https://techdocs.akamai.com/developer/docs/authenticate-with-edgegrid#authentication-protocol-specification

[cloudflare-proxy]: /docs/cloudflare-integration

[custom-subdomain]: /docs/custom-subdomain-setup

[fingerprint-api-keys]: https://dashboard.fingerprint.com/api-keys

[pnpm]: https://pnpm.io/

[postman]: https://www.postman.com/

[proxy-github-repo]: https://github.com/fingerprintjs/akamai-proxy


# Deploy Akamai Integration using Terraform
Source: https://docs.fingerprint.com/docs/deploy-akamai-proxy-integration-via-terraform



<Info>
  **Before you start: Read the general Akamai guide**

  This document only covers deploying the Fingerprint Akamai proxy integration using Terraform. It assumes you have already read the [general Akamai guide][akamai-guide] and completed the following steps:

  * [Step 1][akamai-step-1]: You have issued a proxy secret in the Fingerprint Dashboard (`FPJS_PROXY_SECRET`).
  * [Step 2][akamai-step-2]: You have defined a path variable for the integration (`FPJS_INTEGRATION_PATH`)

  If you want to use Akamai Property Manager API instead of Terraform to install the integration, see [Install Akamai proxy integration using Akamai Property Manager API][akamai-papi].
</Info>

<Warning>
  **Limitations**

  This integration is exclusively supported for customers on the **Enterprise** Plan. Other customers are encouraged to use [Custom subdomain setup][custom-subdomain] or [Cloudflare Proxy Integration][cloudflare-proxy].
</Warning>

<Warning>
  **Requirements: Terraform setup and `latest` rule format expected**

  This guide assumes you use Terraform to manage your site infrastructure on Akamai and that your site uses the `latest` Akamai rule format. If your Akamai property uses a different rule format or a different deployment method, please contact our [support team][support].
</Warning>

To install the integration, adjust your Terraform configuration to incorporate the variable blocks, property rules, and property variables required by the integration.

## Step 3: Add `variable` blocks to your rules template

<Warning>
  The following section assumes you are using the [Rules template][akamai-rules-template] to manage your Akamai property rules. If you are using a plain JSON file instead, reach out to our [support team][support].
</Warning>

Specify a randomized path value and the Fingerprint proxy secret you have created in [Step 1][akamai-step-1]:

* `fpjs_integration_path`
* `fpjs_proxy_secret`

For the path value, pick any random string that is a valid URL path. Be careful not to include words often blocked by ad blockers, such as *fingerprint* or *fpjs*. You can use [any random value generator][random-value-generator] or Terraform's [Random Provider][terraform-random-provider] if you prefer.

Find the `akamai_property_rules_template` data block in your Terraform configuration file and add the following variables:

```terraform main.tf theme={"theme":"github-dark-dimmed"}
data "akamai_property_rules_template" "rules" {
      # Assuming this is property's rules file
      template_file = "/rules/main.json"
      variables {
        name  = "fpjs_integration_path"
        value = "FPJS_INTEGRATION_PATH"
        type = "string"
      }
      variables {
        name  = "fpjs_integration_path_escaped"
        value = "YOUR_INTEGRATION_PATH_ESCAPED" # same as FPJS_INTEGRATION_PATH but with / escaped as \\/ and . escaped as \.
        type = "string"
      }
      variables {
        name  = "fpjs_agent_path"
        value = "deprecated-agent" # APIv3 only; unused on APIv4 — see note below
        type = "string"
      }
      variables {
        name  = "fpjs_result_path"
        value = "deprecated-result" # APIv3 only; unused on APIv4 — see note below
        type = "string"
      }
      variables {
        name  = "fpjs_proxy_secret"
        value = "FPJS_PROXY_SECRET"
        type = "string"
      }
}
```

<Note>
  **Note: Proxy secret required**

  Proxied identification requests without a valid proxy secret will result in an authentication error and not receive identification results.
</Note>

<Note>
  **Note: `fpjs_agent_path` and `fpjs_result_path` are required, but their values no longer matter**

  `fpjs_agent_path` and `fpjs_result_path` only affect APIv3 routing. Because this integration supports both APIv3 and APIv4, both variables are still required even if you only use APIv4, terraform fails with a missing-key error if either is absent.

  On APIv4 their values are arbitrary; you can leave them set to `"deprecated-agent"` and `"deprecated-result"` as shown above.
</Note>

## Step 4: Add Fingerprint property rules

1. Go to the integration's [latest releases on GitHub][proxy-latest-release].
2. Download the `terraform-fingerprint-property-rules.json` file.
3. Add it to your Terraform project's `rules` directory as `fingerprint-property-rules.json`.
4. Reference the file in `rules/main.json` like below:

```javascript rules/main.json theme={"theme":"github-dark-dimmed"}
// rules/main.json
{
  "rules": {
    "name": "default",
    "behaviors": [
      // ...
    ],
    "children": [
      // ...other rule files
      // Add the downloaded rules file
      "#include:fingerprint-property-rules.json"
    ],
    // ...
  }
}
```

## Step 5: Add Fingerprint property variables

1. Go to the integration's [latest releases on GitHub][proxy-latest-release].
2. Download the `terraform-fingerprint-property-variables.json` file.
3. Add it to your Terraform project's `rules` directory as `fingerprint-property-variables.json`.
4. Reference the file in `rules/main.json`:

* If you don't have a `variables` field, add the `variables: "#include:fingerprint-property-variables.json"` line.
* If you already have a `variables` field, merge `fingerprint-property-variables.json` with your existing variables file.

```javascript rules/main.json theme={"theme":"github-dark-dimmed"}
// rules/main.json
{
  "rules": {
    "name": "default",
    "behaviors": [
      // ...
    ],
    "children": [
      //...
      "#include:fingerprint-property-rules.json"
    ],
    // Add the downloaded variables file (or merge it with existing variables file)
    "variables": "#include:fingerprint-property-variables.json"
    // ...
  }
}
```

<Note>
  **Property variables vs Terraform variable blocks**

  Note that the Akamai property variables added in Step 5 are different from the Terraform variable blocks added in Step 3.

  * Property variables are used by property rules and you cannot change them.
  * You can change the variable block values (randomized path and the proxy secret) according to your needs.
</Note>

## Step 6: Apply Terraform changes

1. Run `terraform plan` to review your changes.
2. Run `terraform apply`.

After your property deploys, you can access Fingerprint CDN and API through the chosen path on your website.

## Step 7: Configure the client agent

Please see the main Akamai proxy integration guide to [Configure the client agent on your website or mobile app][akamai-configure-agent].

[akamai-configure-agent]: /docs/akamai-proxy-integration#configure-fingerprint-agent

[akamai-guide]: /docs/akamai-proxy-integration

[akamai-papi]: /docs/deploy-akamai-proxy-integration-via-papi

[akamai-rules-template]: https://techdocs.akamai.com/terraform/docs/pm-ds-rules-template

[akamai-step-1]: /docs/akamai-proxy-integration#step-1-issue-a-fingerprint-proxy-secret

[akamai-step-2]: /docs/akamai-proxy-integration#step-2-create-a-path-variable

[cloudflare-proxy]: /docs/cloudflare-integration

[custom-subdomain]: /docs/custom-subdomain-setup

[proxy-latest-release]: https://github.com/fingerprintjs/akamai-proxy/releases/latest

[random-value-generator]: https://www.random.org/strings/?num=3&len=12&digits=on&loweralpha=on&unique=on&format=html&rnd=new

[support]: https://fingerprint.com/support/

[terraform-random-provider]: https://registry.terraform.io/providers/hashicorp/random/latest/docs


# Discord Server
Source: https://docs.fingerprint.com/docs/discord





# DORA
Source: https://docs.fingerprint.com/docs/dora



Compliance with the Digital Operational Resilience Act

This DORA Addendum (this "Addendum") applies between FingerprintJS Inc. ("FingerprintJS") and the customer under the Agreement ("Customer") (each a "Party" and together the "Parties")."

**PREAMBLE**

The Parties have entered into a Customer Terms of Service (including any Service Orders) ("**Agreement**") regarding the provision of services by FingerprintJS ("**Services**").

The Parties wish to amend the Agreement to implement the additional contractual clauses required by the Digital Operational Resilience Act (EU) 2022/2554 ("**DORA**") for the provision of information and communication technology services ("**ICT**") in the European Economic Area.

## 1. Applicability

### 1.1

This Addendum applies where the Customer is a regulated entity as per Art. 2(1) DORA and obligated to comply with DORA. This Addendum applies to the extent FingerprintJS is considered an ICT service provider as per Art. 3(19) DORA. The Parties acknowledge that the Services provided by FingerprintJS under the Agreement and this Addendum do not support critical or important functions of the Customer as per Art. 3(22) DORA. Therefore, the enhanced contractual requirements set out in Art. 30(3) DORA, the associated RTS, and any other requirements applicable to the provision of services supporting critical or important functions shall not apply.

### 1.2

This Addendum supplements the Agreement and shall control in the event of any conflict between the terms of this Addendum and the Agreement, with respect to the subject matter herein.

### 1.3

This Addendum is effective as of the effective date of the Agreement ("**Effective Date**").

## 2. Definitions

### 2.1

Capitalized terms used in this Addendum have the following meanings:

* **2.1.1** "**EEA**" means European Economic Area.
* **2.1.2** "**ESA**" means European Supervisory Authorities including the European Banking Authority, the European Insurance and Occupational Pensions Authority, and the European Securities and Markets Authority.
* **2.1.3** "**ICT**" means information and communication technology services as per Art. 3(21) DORA.
* **2.1.4** "**ICT-related incident**" means unplanned events as per Art. 3(8) DORA.
* **2.1.5** "**Resolution Authority**" means an authority designated by an EU Member State as a resolution authority in accordance with Art. 3 Directive (EU) 2014/59 and the respective EU Member State law transposing the Directive.
* **2.1.6** "**RTS**" means the regulatory technical standards developed by the ESAs which supplement DORA, adopted by the European Commission as delegated acts.

### 2.2

Other capitalized terms used and not defined in this Addendum shall have the meaning given to them in DORA and the Agreement.

## 3. ICT Service Description and Compliance with Applicable Law

### 3.1

**Annex 1** of this Addendum includes a description of all functions and ICT services to be provided. According to such description, the Services do not support critical or important functions of the Customer as per Art. 3(22) DORA.

### 3.2

A service level description, including updates and revisions thereof is included in **Annex 3**, which FingerprintJS may amend from time to time.

## 4. Location of the Services

### 4.1

This Addendum lists in **Annex 2** the locations where the Services will be provided by FingerprintJS and where personal and non-personal data (together “**Data**”) will be stored and processed by FingerprintJS on behalf of the Customer. FingerprintJS will notify the Customer in advance of any change to such locations.

## 5. Right of Instruction

### 5.1

Customer shall use commercially reasonable efforts to inform FingerprintJS in writing as quickly as possible of any legally binding recommendations, regulatory standards or other binding publications received from, or published by the competent authorities (including ESAs) under DORA that would be applicable to FingerprintJS’ performance of the Services under the Agreement.

### 5.2

Both Parties will work together, in good faith, to amend this Addendum as needed to meet any reasonable mandated requirements of Customer’s relevant competent authorities or Resolution Authorities in so far as such changes apply to the provision of the Services to the Customer and are required for Customer to comply with its legal and regulatory obligations under DORA.

## 6. Data Protection and Information Security

### 6.1

The Parties have agreed as part of the Agreement a data processing agreement (“**DPA**”) the terms of which govern the processing of personal data in the context of the delivery of the Services. The provisions in the DPA and its Annex in relation to the availability, authenticity, integrity, and confidentiality of personal data shall herewith be extended to also cover non-personal data, subject to the subsequent restrictions.

### 6.2

Information regarding the technical and organizational measures implemented by FingerprintJS at the time of entering into the Agreement are available at [https://dev.fingerprint.com/docs/dpa-gdpr#technical-and-organisational-security-measures](https://dev.fingerprint.com/docs/dpa-gdpr#technical-and-organisational-security-measures). FingerprintJS will make available significant changes via the referenced site.

### 6.3

In the event of the insolvency, resolution, or discontinuation of the business operations of Customer, where reasonable and necessary, FingerprintJS will return, grant access to, or recover in an easily accessible format relevant Data processed under this Addendum at Customer’s request (by Customer contacting FingerprintJS’ technical support team for download access and instructions), except for Data relating to or constituting FingerprintJS’ confidential information (such as trade secrets) and subject to the time/retrieval periods, limitations, requirements and restrictions set out in the Agreement as regards the Data of Customer. If Customer requests to receive a copy of its Data in any other format than foreseen by FingerprintJS, such format will be at Customer’s cost and the Parties will agree such costs in advance in an order form signed by both Parties. FingerprintJS shall ensure that access, recovery and retrieval of Customer Data is available to Customer for a maximum of one (1) month after any of the mentioned circumstances occur.

## 7. Assistance and Cooperation

### 7.1

In case of an ICT-related incident or in case of an operational or security payment related incident that materially impacts the confidentiality, integrity, or availability of the ICT Service provided to Customer, FingerprintJS shall provide reasonable assistance to the Customer at a cost to be borne by Customer that shall be determined beforehand by the Parties in writing.

### 7.2

FingerprintJS shall fully cooperate with the competent authorities and the Resolution Authorities of the Customer, including their appointed representatives. The Parties shall use commercially reasonable efforts to assist each other in complying with any notification obligation in the event of incidents.

## 8. Security Awareness Programs and Training

### 8.1

Where appropriate and where Customer can, contrary to Sec. 8.3, demonstrate that FingerprintJS’ employees role require interaction with Customer ICT systems, protocols and tools and is not adequately sensitized and trained (i.e., through certificates or trainings performed by FingerprintJS), the Parties will agree on the requirements for Customer to request FingerprintJS to procure that its personnel whose roles require direct interaction with Customer ICT systems when providing ICT Services under the Agreement participate in Customer’s ICT security awareness programs and digital operational resilience training as per Art. 13(6) DORA.

### 8.2

FingerprintJS employees will participate in such training sessions at Customer’s request and cost. Such costs will be agreed by the Parties in writing in a separate order form signed by both Parties.

### 8.3

The Parties acknowledge that except in relation to the implementation of the Services, no FingerprintJS employee is generally dedicated solely to delivering the Services to the Customer. The Parties therefore agree that it is regularly not necessary to include FingerprintJS’ personnel in the relevant training schemes of the Customer.

## 9. Adaption and Termination

### 9.1

The termination rights and the minimum notice periods for the termination of the Agreement can be subject to changes mandated by the competent authorities and Resolution Authorities. If the Parties cannot reach an agreement on the amendments to the Agreement required to reflect the mandatory changes within three (3) months after receipt of a binding instruction by the competent authority or Resolution Authority, either Party shall be entitled to an extraordinary right to terminate the Agreement with a notice period of three (3) months, which shall be the Customer’s sole and exclusive remedy. The Customer shall continue to pay for the Services during any such notice period but will be entitled to a partial refund for any fees paid in advance for the Services affected by the termination.

### 9.2

In addition to the termination rights under the Agreement, and as set out above in Sec. 9.1, Customer shall be entitled to terminate the Agreement by providing thirty (30) days written notice to FingerprintJS in any of the following circumstances:

* **9.2.1** Evidenced significant breach by FingerprintJS of applicable laws, regulations, or the obligations under this Addendum after an unsuccessful passing of a cure period of three (3) months after receiving Customer’s written breach notice.
* **9.2.2** Reasonable, evidenced and substantiated circumstances identified throughout the monitoring of FingerprintJS’ third-party risk that are deemed capable of materially impairing the performance of the functions provided through the Agreement and failure by both Parties to agree to a reasonable remediation plan in respect of such identified circumstances, including material changes that affect the Agreement or the situation of FingerprintJS after an unsuccessful passing of a cure period of three (3) months following receipt of Customer’s written notice.
* **9.2.3** FingerprintJS’ evidenced substantial weakness pertaining to its overall ICT risk management and particularly in the way it ensures the availability, authenticity, integrity, and confidentiality, of Data, which are material in nature and not resolved after an unsuccessful passing of a cure period of three (3) months following receipt of Customer’s written notice of any such identified weaknesses.
* **9.2.4** Where the competent authority of the Customer can no longer effectively supervise the Customer as a result of the conditions of, or circumstances related to, the Agreement, or as otherwise directed by a supervisory authority. To exercise the foregoing right, Customer shall serve a written notice of termination of no less than fourteen (14) business days and provide FingerprintJS with reasonable evidence of the grounds of termination.

### 9.3

In the case of a justified termination under section 9.2, the Customer shall be entitled to a pro-rata refund of pre-paid fees.

## 10. Miscellaneous

### 10.1

This Addendum shall be governed by and construed in accordance with the laws that govern the Agreement.

### 10.2

This Addendum may be executed in multiple counterparts, each of which is an original, but all together constitute the same document. The Parties agree that this Addendum may be executed electronically whereby transmission of an executed counterpart of this Addendum by email (in PDF, JPEG or other common format) shall be constitute delivery of an executed counterpart in this Addendum.

### 10.3

The Parties agree that material changes to the Agreement that fall within the scope of this Addendum are to be formalized in a written document which is dated and signed (at least electronically) by the Parties, and which shall specify the renewal process for the relevant contractual arrangements.

## Annex 1 — Description of ICT Services

FingerprintJS provides to the Customer a cloud-based device intelligence service comprising the following products: Identification and Smart Signals (the “**Service**”)

The Service enables customers to identify and classify devices and sessions interacting with their web and mobile applications. Identification returns a Visitor ID that remains stable over time and across routine software updates. Smart Signals provide additional context for detection and response, including suspect scoring and velocity indicators. The Service is intended for fraud prevention, risk scoring, abuse mitigation (e.g., account takeover, new account fraud, SMS pumping), bot detection, and personalization use cases. The Service does not execute payments, hold customer funds, perform regulated financial services, or provide managed security operations.

FingerprintJS will render the agreed Services in accordance with the terms of the Agreement.

## Annex 2 — Location(s) of the ICT Services Directly Provided by FingerprintJS

| ICT Service Description (only Services directly provided by FingerprintJS) | Location of Provision of Services and Data Processing                                                                   |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Provision of visitor identifier service                                    | The Service is provided in the EU (by FingerprintJS located in the U.S.) and the Data is processed and stored in the EU |

## Annex 3 — Service Level Agreement

### 1. Support Services

During the Subscription Term, FingerprintJS will provide the support services described in this Annex 3 (the “**Support Services Term**”).

### 2. Definitions

“**Downtime**” means a period of time where the Service is unavailable to Customer due to reasons that are within FingerprintJS’ reasonable control. For clarity, “Downtime” does not include periods where the Service is unavailable to Customer due to (a) Customer’s negligence, hardware or software malfunction or other causes beyond the reasonable control of FingerprintJS such as, by way of example and without limitation, generalized telecommunications failures, packet loss, network, or internet problems, or (b) a problem with third party software not licensed through FingerprintJS.

“**Emergency Downtime**” means Downtime due to a short-term emergency condition, provided that: (a) the incident lasts less than three (3) hours; and (b) there have been no prior Emergency Downtime incidents within 90 days before the incident.

“**Error**” means a failure of the Service to conform to the specifications set forth in the Documentation, resulting in the inability to use, or material restriction in the use of, the Service.

“**Excused Downtime**” means any Downtime that is Maintenance Downtime or Emergency Downtime, or Downtime that relates to FingerprintJS’ blocking of data communications or other service in connection with the Service in accordance with its policies.

“**Maintenance Downtime**” means Downtime for maintenance or backup purposes, provided that: (a) the incident is scheduled with Customer at least three (3) business days in advance and (b) the aggregate duration of incidents in any month is less than one (1) hour.

“**Monthly Availability Percentage**” means the percentage of time over the course of each calendar month during the Support Services Term, excluding Excused Downtime, that the Service is available for use by Customer.

“**Start Time**” means the time at which FingerprintJS first becomes aware of an Error.

### 3. Support Services

During the Support Services Term, FingerprintJS shall provide customer support through email during normal business hours, which shall be Monday through Friday, 9 a.m. to 5 p.m. (Central Time) (the “**Support Services**”). All submitted Errors will be classified as “Minimal Business Impact” as described in Table 1 below.

### 4. Service Availability

#### 4.1 Availability

The Service shall have a Monthly Availability Percentage equal to or greater than **99.9%**:

#### 4.2 Downtime Credits

If the Service does not meet the Monthly Availability Percentage, FingerprintJS shall provide Customer with a credit in an amount equal to 0.4% of Subscription Term fees (“**Downtime Credit**”) for each period of Downtime lasting longer than 1 hour that is not an Excused Downtime; provided, however, that no more than one (1) Downtime Credit will accrue per day. In order to receive Downtime Credit, Customer must notify FingerprintJS in writing within 24 hours from the time of Downtime (such notice, a “**Downtime Notice**”). Failure to provide a Downtime Notice will forfeit Customer’s right to receive Downtime Credit for the applicable period of Downtime. For purposes of Downtime Credits, Downtime will begin to accrue as soon as FingerprintJS receives a Downtime Notice, and continues until the availability of the Service is restored. Downtime Credits may not be redeemed for cash. For any one (1) calendar month, Customer can receive a maximum of Downtime Credits equal to one (1) week of Subscription Term fees. FingerprintJS will only apply Downtime Credits to the month in which the incident occurred. Downtime Credits are non-transferable and are not redeemable for cash. Customer will not be entitled to any Downtime Credits if any undisputed invoice is overdue or if Customer is in breach of the Agreement.

#### 4.3 Error Management

FingerprintJS will use its commercially reasonable efforts to adhere to the response and resolution times for Errors as set forth below in <u>Table 1</u>.

#### Table 1 – Error Management

| Error Classification       | Description                                                                                                                                                                                        | Response Time\*                     |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| *Critical Business Impact* | Any Error reported by Customer where the Service is unavailable and for which there is no workaround.                                                                                              | Within 4 hours\* of the Start Time. |
| *Moderate Business Impact* | Any Error reported by Customer where Service performance may be degraded or functions limited, for which a workaround is available, and such Error materially affects Customer’s business.         | Within 8 hours\* of the Start Time. |
| *Minimal Business Impact*  | Any Error reported by Customer where Service performance may be degraded or functions limited, for which a workaround is available, and such Error does NOT materially affect Customer’s business. | Within 8 hours\* of the Start Time. |

\* All times during regular business hours: 9 a.m. – 5 p.m. (Central Time, Monday through Friday).

### 5. Conditions, Exclusions, and Termination of Support Services

#### 5.1 Conditions for Providing Support

FingerprintJS’s obligation to provide Support Services is conditioned upon the following: (a) Customer makes reasonable efforts to solve the problem after consulting with FingerprintJS; (b) Customer provides FingerprintJS with sufficient information and resources to correct the problem, as well as access to the personnel, hardware, and any additional software involved in discovering the problem; and (c) Customer procures, installs and maintains all software, hardware, communication interfaces and other components necessary to use the Service.

#### 5.2 Exclusions from FingerprintJS’s Support Services

FingerprintJS is not obligated to provide Support Services in the following situations: (a) the problem is caused by Customer’s negligence, hardware or software malfunction or other causes beyond the reasonable control of FingerprintJS, (b) the problem is with third party software not licensed through FingerprintJS or (c) Customer is in breach of the Agreement.

#### 5.3 Termination of Support Services

FingerprintJS reserves the right to suspend performance of the Support Services if Customer fails to pay any amount that is payable to FingerprintJS under the Agreement within thirty (30) days after such amount becomes due.


# DPA (GDPR)
Source: https://docs.fingerprint.com/docs/dpa-gdpr



# GDPR Data Processing Agreement

This Data Processing Agreement (“**DPA**”) is an addendum to the Customer Terms of Service (“**Agreement**”) between FingerprintJS Inc. (“**FingerprintJS**”) and the Customer (each a “**Party**” and together the “**Parties**”). This DPA includes and incorporates by reference the annexes and addenda referenced at the bottom of this document. All capitalised terms not defined in this DPA shall have the meanings set forth in the Agreement. Customer enters into this DPA on behalf of itself and, to the extent required under Data Protection Laws, in the name and on behalf of its Authorised Affiliates (defined below).

**The Parties agree as follows:**

## 1. Definitions

“**Additional Services**” means additional model-driven fraud prediction and detection services and access to the DRN, in each case as agreed between the Customer and FingerprintJS.

"**Administration Data**" means:

* **(a)** contact details relating to, and the content of correspondence with, the Customer’s main account holder or administrator; and
* **(b)** support enquiries submitted by the Customer’s authorised users in relation to the Service and Additional Services.

**“Affiliate”** means an entity that directly or indirectly Controls, is Controlled by or is under common Control with an entity.

**“Authorised Affiliate”** means any of Customer Affiliate(s) permitted to or otherwise receiving the benefit of the Service and Additional Services pursuant to the Agreement.

**“Control”** means either (i) an ownership, voting or similar interest representing twenty five (25%) or more of the total interests then outstanding of the entity in question; or (ii) the power to direct or cause the direction and management of an entity's policies in accordance with the acquirer's wishes, whether as a result of the ownership of shares, control of the board of directors, contract or any powers conferred by the entity's articles of association or other constitutional documents. The term **“Controlled”** shall be construed accordingly.

**“Controller”** has the meaning given to it in the GDPR.

"**Controller Clauses**" means Module One (*controller to controller*) of the Standard Contractual Clauses annexed to Commission Implementing Decision (EU) 2021/914.

“**Controller Purposes**" has the meaning given in Section 2.5.

**“Customer Personal Data”** means any Personal Data that FingerprintJS and/or its Affiliates processes in the course of providing the Service and Additional Services to Customer under the Agreement as set out in Schedule 2.

**“Data Protection Laws”** means all data protection and privacy laws and regulations applicable to the processing of Personal Data under the Agreement, including, where applicable, the GDPR and Swiss Data Protection Laws.

"**GDPR**" means Regulation (EU) 2016/679 (the "**EU GDPR**") or, where applicable the "**UK GDPR**" as defined in section 3 of the Data Protection Act 2018.

**“Personal Data”** has the meaning given to it in the GDPR.

**“Processor”** has the meaning given to it in the GDPR.

"**Processor Clauses**" means Module Two (*controller to processor*) of the Standard Contractual Clauses annexed to Commission Implementing Decision (EU) 2021/914.

**“Security Incident”** means any breach of security that leads to the accidental or unlawful destruction, loss, alteration, unauthorised disclosure of or access to Personal Data.

"**Standard Contractual Clauses**" or

“**SCCs**” means the Controller Clauses and the Processor Clauses.

**“Sub-processor”** means any Processor engaged by FingerprintJS or its Affiliates to assist in fulfilling its obligations with respect to providing the Service and Additional Services pursuant to the Agreement or this DPA. Sub-processors may include third parties or any FingerprintJS Affiliate.

"**Swiss Data Protection Laws**" means the Swiss Federal Act on Data Protection of 25 September 2020 ("**FADP**") and the Swiss Data Protection Ordinance of 31 August 2022, and any new or revised version of these laws that may enter into force for time to time; and

“**Usage Data**" means diagnostic, usage and performance information collected by FingerprintJS in relation to the Customer’s and its authorised users' use of the Service.

The terms “**data subject**”, “**processing**” (and **“process”**, **“processes”** and **“processed”**) and “**supervisory authority**” have the meanings given to them in the GDPR.

## 2. Scope and Applicability of this DPA

### 2.1

This DPA applies where and only to the extent that FingerprintJS processes Customer Personal Data in the course of providing the Service and Additional Services and such Customer Personal Data is subject to Data Protection Laws. The Parties agree to comply with the terms and conditions in this DPA in connection with such Customer Personal Data.

### 2.2 Role of the Parties

Save as set out in Section 2.5, the Parties acknowledge and agree that, as between FingerprintJS and Customer, Customer is the Controller of Customer Personal Data and FingerprintJS shall process Customer Personal Data only as a Processor on behalf of Customer.

### 2.3 Customer Obligations

Customer agrees that: (i) it shall comply with its obligations as a Controller under Data Protection Laws in respect of its processing of Customer Personal Data; (ii) it shall ensure that any processing instructions it issues to FingerprintJS with respect to Customer Personal Data shall comply with applicable Data Protection Laws.

### 2.4 Processing of Personal Data

Save as set out in Section 2.5, and notwithstanding clause 8.1 of the Processor Clauses, FingerprintJS shall process Customer Personal Data only for the following purposes: (i) processing to perform the Service and Additional Services in accordance with the Agreement; and (ii) processing to perform any steps necessary for the performance of the Agreement, in each case unless processing is required by applicable law in the UK, Switzerland, the European Union or a Member State of the European Union, in each case to which FingerprintJS is subject, in which case FingerprintJS shall, to the extent permitted by such applicable law, inform the Customer of that legal requirement before processing that Customer Personal Data. The Parties agree that, for the purposes of clause 8.1(a) of the Processor Clauses, the Agreement and this DPA shall be the Customer's instructions for the processing of Customer Personal Data. To the extent that any of the Customer's instructions require processing of Customer Personal Data in a manner that falls outside the scope of the Service and Additional Services, FingerprintJS may:

* **(a)** make the performance of any such instructions subject to the payment by the Customer of any costs and expenses incurred by FingerprintJS or such additional charges as FingerprintJS may reasonably determine; or
* **(b)** terminate the Agreement and the Service and Additional Services.

### 2.5 Controller Purposes

The Parties acknowledge and agree that:

* **(a)** FingerprintJS collects and processes Administration Data and Usage Data as a Controller for legitimate business purposes, including administering its business relationship with Customer, product development and sales and marketing;
* **(b)** FingerprintJS collects Fraud Identification Data as a Controller for the purposes of maintaining and making available the DRN.

(the “**Controller Purposes**”). Where it acts as a Controller, FingerprintJS shall process such data in compliance with Data Protection Laws..

## 3. Standard Contractual Clauses

### 3.1

The Standard Contractual Clauses shall, as further set out at Schedule 5, apply to transfers of Customer Personal Data from Customer to FingerprintJS, and form part of this DPA, to the extent that:

* **(a)** the GDPR or Swiss Data Protection Law applies to Customer's processing of such Customer Personal Data when making the transfer; or
* **(b)** the transfer is an "onward transfer" (as defined in the applicable module of the SCCs).

### 3.2

The Parties agree that:

* **(a)** execution of the Agreement or this DPA shall have the same effect as signing the SCCs; and
* **(b)** in the event of a conflict between the terms of the Agreement, this DPA and the SCCs, the terms of the SCCs shall prevail.

## 4. Sub-processing

### 4.1 Authorised Sub-processors

The Parties agree that, for the purposes of clause 9 of the Standard Contractual Clauses, Customer gives FingerprintJS general authorisation to engage Sub-processors to process Customer Personal Data on Customer's behalf. The Sub-processors currently engaged by FingerprintJS and authorised by Customer are listed in Schedule 4.

### 4.2 Sub-processor Obligations

FingerprintJS shall: (i) enter into a written agreement with the Sub-processor imposing the same data protection obligations on the Sub-processor as set out in this DPA; and (ii) remain responsible for its compliance with the obligations of this DPA and for any acts or omissions of the Sub-processor that cause FingerprintJS to breach any of its obligations under this DPA.

### 4.3 Changes to Sub-processors

FingerprintJS shall provide Customer with fourteen (14) calendar days' notice (for which email shall suffice) of any proposed changes to the Sub-processors, including any information reasonably necessary to enable the Customer to assess the Sub-processor and exercise its right to object.

### 4.4 Objection to Sub-processors

If the Customer objects to FingerprintJS's use of a new Sub-processor (including when exercising its right to object under clause 9(a) of the Standard Contractual Clauses) it shall: (i) notify FingerprintJS of its objection promptly in writing within five (5) calendar days of receipt of FingerprintJS' notice in accordance with Section 4.3; and (ii) provide documentary evidence that reasonably shows that the Sub-processor does not or cannot comply with the requirements in this DPA (including the Standard Contractual Clauses). In such an event, the Parties shall discuss such concerns in good faith with a view to achieving commercially reasonable resolution. If this is not possible, either Party may terminate the applicable Service and Additional Services that cannot be provided by FingerprintJS without the use of the objected-to new Sub-processor by giving to the other Party thirty (30) calendar days' written notice. During such notice period, FingerprintJS may suspend the affected portion of the Service and Additional Services.

## 5. Customer warranties and undertakings

### 5.1

The Customer represents and warrants that:

* **(a)** it has provided all applicable notices to data subjects and, to the extent required, obtained consent from data subjects in each case as required for the lawful processing of Customer Personal Data in accordance with the Agreement and this DPA; and
* **(b)** without prejudice to the generality of clause 8 of the Standard Contractual Clauses (as applicable), taking into account the state of the art, the costs of implementation and the nature, scope, context and purposes of processing as well as the risk of varying likelihood and severity for the rights and freedoms of natural persons, the security measures set out in Schedule 3 are:
  * **(i)** appropriate to ensure the security of the Customer Personal Data, including protection against a Security Incident; and
  * **(ii)** otherwise consistent with the Customer's obligations under Article 32 of the GDPR.

### 5.2

Other than as set out in Section 2.5, the Customer shall be solely responsible for the legality of Customer Personal Data provided to FingerprintJS by Customer or an Authorised Affiliate or collected by FingerprintJS.

## 6. Security and Audits

### 6.1 Security Measures

FingerprintJS shall implement and maintain appropriate technical and organisational security measures to protect Customer Personal Data from Security Incidents and to preserve the security and confidentiality of the Customer Personal Data, in accordance with FingerprintJS' security standards described in Schedule 3 (“Security Measures”).

### 6.2 Confidentiality of Processing

FingerprintJS shall ensure that any person who is authorised by FingerprintJS to process Customer Personal Data (including its staff, agents and subcontractors) shall be under an appropriate obligation of confidentiality (whether a contractual or statutory duty).

### 6.3 Security Incident Response

FingerprintJS will notify Customer in writing without undue delay after becoming aware of any Security Incident, and reasonably cooperate with regards to any obligation of Customer under Data Protection Laws to make any notifications in respect of a Security Incident, such as to individuals, supervisory authorities or other regulatory authorities. FingerprintJS' notification of, or response to, a Security Incident under this Section 6.3 will not be construed as an acknowledgement by FingerprintJS of any fault or liability with respect to the Security Incident.

### 6.4 Updates to Security Measures

Customer acknowledges that the Security Measures are subject to technical progress and development and that FingerprintJS may, by written notice to the Customer, update or modify the Security Measures from time to time following any review by FingerprintJS of the Security Measures (including in accordance with clause 8.6 of the Standard Contractual Clauses), provided that such updates and modifications do not result in the degradation of the overall level of protection afforded to the Customer Personal Data by FingerprintJS under this DPA.

### 6.5 Audits

With respect to any audits conducted under clauses 8.9(c) and (d) of the Standard Contractual Clauses, the Parties agree that:

* **(a)** all such audits shall be conducted:
* **(i)** only once per year, or more frequently if any audit indicates that FingerprintJS is in non-compliance with this DPA;
* **(ii)** on reasonable written notice to FingerprintJS;
* **(iii)** only during FingerprintJS' normal business hours; and
* **(iv)** in a manner that does not disrupt FingerprintJS' business;
* **(v)** by reference to an appropriate and accepted control standard or framework; and
* **(b)** the Customer (or, where applicable, a third party independent auditor appointed by the Customer) shall:
* **(i)** enter into a confidentiality agreement with FingerprintJS prior to conducting the audit in such form as FingerprintJS may request; and
* **(ii)** ensure that its personnel comply with FingerprintJS' and any Sub-processor's policies and procedures when attending FingerprintJS' or Sub-processor's premises, as notified to the Customer by FingerprintJS or Sub-processor.

### 6.6 Reports

FingerprintJS shall provide written responses (on a confidential basis) to all reasonable requests for information made by Customer, including responses to information security and audit questionnaires, that Customer (acting reasonably) considers necessary to confirm FingerprintJS's compliance with this DPA, provided that Customer shall not exercise this right more than once per year.

## 7. Return or Deletion of Data

### 7.1

Upon deactivation of the Service and Additional Services, FingerprintJS shall, subject to Section 7.2: (i) if requested to do so by the Customer within seven (7) days of the date of termination of the Agreement or deactivation of the Service and Additional Services, return a complete copy of all Customer Personal Data by secure file transfer in such a format as notified by the Customer to FingerprintJS; and (ii) delete and use all reasonable efforts to procure the deletion of all other copies of Customer Personal Data processed by FingerprintJS or any Sub-processors.

### 7.2

FingerprintJS may retain Customer Personal Data:

* **(a)** to the extent that such Customer Personal Data is processed for the Controller Purposes;
* **(b)** to the extent required by applicable laws, and only for such period and such purposes as required by applicable laws; or
* **(c)** to the extent that the Customer Personal Data has been archived on back-up systems, provided that FingerprintJS shall securely isolate and protect such Customer Personal Data from any further processing, except to the extent required by applicable law, and purge such Customer Personal Data from the applicable back-up systems in accordance with its normal back-up cycle.

### 7.3

FingerprintJS shall, with respect to any Customer Personal Data retained in accordance with Section 7.2, ensure the confidentiality of all such Customer Personal Data.

## 8. Cooperation

### 8.1

To the extent that Customer is unable to independently access the relevant Customer Personal Data within the Service and Additional Services, FingerprintJS shall (at Customer's expense) taking into account the nature of the processing, provide reasonable cooperation to assist Customer by appropriate technical and organisational measures, in so far as is possible, to respond to any requests from individuals or applicable data protection authorities relating to the processing of Customer Personal Data under the Agreement. Other than in respect of Administration Data, Usage Data and Fraud Identification Data processed for the Controller Purposes, in the event that any such request is made directly to FingerprintJS, FingerprintJS shall not respond to such communication directly without Customer's prior authorisation, unless legally compelled to do so. If FingerprintJS is required to respond to such a request, FingerprintJS shall promptly notify Customer and provide it with a copy of the request unless legally prohibited from doing so.

### 8.2

To the extent FingerprintJS is required under Data Protection Law, FingerprintJS shall (at Customer's expense) provide reasonably requested information regarding FingerprintJS’s processing of Customer Personal Data under the Agreement to enable the Customer to carry out data protection impact assessments or prior consultations with data protection authorities as required by law.

### 8.3

Customer shall promptly inform FingerprintJS of any request received by the Customer from a data subject to assert their rights under the GDPR and Swiss Data Protection Laws in relation to Administration Data, Usage Data or Fraud Identification Data processed by FingerprintJS for the Controller Purposes.

## 9. Costs

### 9.1

The Customer shall pay to FingerprintJS on demand all costs and expenses incurred by FingerprintJS in connection with:

* **(a)** implementing any changes to the Service and Additional Services under Section 4.4;
* **(b)** facilitating and contributing to any audits of FingerprintJS under Section 6.5 or clauses 8.9(c) and (d) of the Standard Contractual Clauses;
* **(c)** facilitating and contributing to any audits of FingerprintJS conducted by a supervisory authority;
* **(d)** responding to queries or requests for information from the Customer relating to the processing of Customer Personal Data under clauses 8.9(a), 8.9(c) or 8.9(e) of the Standard Contractual Clauses;
* **(e)** any assistance provided by FingerprintJS to the Customer with its fulfilment of its obligations to respond to data subjects' requests for the exercise of their rights under the GDPR; and
* **(f)** any assistance provided by FingerprintJS to the Customer with any data protection impact assessments or prior consultation with any supervisory authority of the Customer.

## 10. Miscellaneous

### 10.1

Except for the changes made by this DPA, the Agreement remains unchanged and in full force and effect. Without prejudice to the generality of clause 5 of the Standard Contractual Clauses, in the event of any conflict between the Agreement, this DPA and the Standard Contractual Clauses, the following order of precedence shall apply:

* **(g)** The Standard Contractual Clauses (or, with respect to transfers of Customer Personal Data subject to the UK GDPR or Swiss Data Protection Laws, the Standard Contractual Clauses as amended by Schedule 5).
* **(h)** The main body of this DPA.
* **(i)** The Agreement.

### 10.2

This DPA is a part of and incorporated into the Agreement so references to "Agreement" in the Agreement shall include this DPA.

### 10.3

In no event shall any Party limit its liability with respect to any individual's data protection rights under this DPA or otherwise.

### 10.4

Other than the right of data subjects or not-for-profit bodies, organisations or associations under the conditions set out in Article 80(1) of the GDPR to bring claims under the Standard Contractual Clauses (as applicable), a person who is not a Party to this DPA may not enforce any of its terms.

### 10.5

Notwithstanding the provisions of the Agreement and unless otherwise indicated in Schedule 5, this DPA and the Standard Contractual Clauses shall (to the extent permitted under applicable law) be governed by and construed in accordance with the laws of England and Wales.

### 10.6

Notwithstanding the provisions of the Agreement and unless otherwise indicated in Schedule 5, the Parties submit themselves to the jurisdiction of the courts of England and Wales in respect of any disputes arising under this DPA and the Standard Contractual Clauses.

## Schedule 1 — PARTIES TO THE PROCESSING

| Party:                                               | Customer / data exporter                       | FingerprintJS / data importer                                                                                                 |
| ---------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Role**                                             | **Controller**                                 | **Controller / Processor**                                                                                                    |
| **Contact person (Name, Position, Contact Details)** | The contact details provided with the Account. | Name: Valentin Vasilyev Position: Chief Technology Officer Contact details: [dpo@fingerprint.com](mailto:dpo@fingerprint.com) |
| **Activities / services provided**                   | Receipt of the Service and Additional Services | Provision of the Service and Additional Services                                                                              |
| **Competent supervisory authority**                  | The Data Protection Commission, Ireland        |                                                                                                                               |

## Schedule 2 — Details of processing

### Part 1 — Processing subject to the Processor Clauses

<u>Data subjects</u>

The personal data transferred concern the following categories of data subjects:

* The Customer’s end users who visit the Customer’s sites and services (“**End Users**”).
* The Customer's employees and contractors that the Customer authorises to access and use the Service (“**Authorised Users**”).

<u>Purpose(s) of the data transfer and further processing</u>

The purpose of the data transfer and further processing is the provision and maintenance of FingerprintJS' Service and Additional Services.

<u>Categories of data</u>

The personal data transferred concern the following categories of data:

End Users:

* Personal data contained within Visitor Data, including information relating to an End User's device, operating system, browser, browser configuration, IP address, and approximate location, and IDs associated with successful detections of fraud on the Customer’s sites and services.

Authorised Users:

* account information, including login information;
* payment and transaction information;
* support request information; and
* technical information regarding access to the Service (including IP address, approximate location, pages viewed and log data).

<u>Sensitive data</u>

None.

<u>Frequency of the transfer</u>

The data is transferred on a continuous basis.

<u>Subject matter of the processing</u>

The provision and maintenance of FingerprintJS' Service and Additional Services .

<u>Nature of the processing</u>

Transmitting, collecting, storing and analysing data in order to provide and maintain FingerprintJS' the Service and Additional Services.

<u>Duration</u>

The Personal Data will be retained for the duration of the Agreement, subject to Section 7 of the DPA.

<u>Sub-processor (if applicable)</u>

For transfers to sub-processors, specify subject matter, nature and duration of the processing:

* as set out in Schedule 4

### Part 2 — Processing subject to the Controller Clauses

<u>Data subjects</u>

* Authorised Users.

<u>Purposes of the transfer(s) and further processing</u>

The purpose of the data transfer and further processing is the administration of FingerprintJS' Service and Additional Services and improvement of FingerprintJS' Service, including internal record-keeping, billing, product development and sales and marketing.

<u>Categories of data</u>

The Personal Data transferred concern the following categories of data:

End Users:

* Fraud Identification Data

Authorised Users:

* contact information, including name, address, phone number, email address, login details, employing / engaging organisation;
* payment and transaction information;
* contact preferences, including preference set for notifications, marketing communications;
* comments and opinions; and
* technical information regarding access to the Service (including IP address, approximate location, pages viewed and log data, display and active functionalities).

<u>Sensitive data</u>

None.

<u>Frequency of the transfer</u>

The transfer is carried out on a continuous basis for the duration of the Agreement.

<u>Subject matter of the processing</u>

The subject matter of the processing is:

* Administration of FingerprintJS’s Service and Additional Services.
* Improvement, troubleshooting and testing of FingerprintJS' Service.
* Calculation of charges and fees owed by the Customer to FingerprintJS in respect of the Service and Additional Services.
* Marketing to Customer and their users.

<u>Nature of the processing</u>

The processing of Personal Data in connection with the administration of the Service and Additional Services and improvement of FingerprintJS's Service.

<u>Duration</u>

The Personal Data will be retained for the duration of the Agreement, subject to Section 7 of the DPA.

<u>Sub-processor (if applicable)</u>

For transfers to sub-processors, specify subject matter, nature and duration of the processing:

* as set out in Schedule 4.

## Schedule 3 — Technical and Organisational Security Measures

### 1. Introduction

The data importer employs a combination of policies, procedures, guidelines and technical controls to protect the personal data it processes from accidental loss and unauthorised access, disclosure or destruction.

### 2. Governance and Policies

The data importer has organised leadership and defined policies related to information security to ensure alignment with business objectives to adequately serve clients. These policies are reviewed and approved annually by management and updates are communicated to employees and relevant external parties.

Roles and responsibilities for teams and team members are defined within the data importer’s organisational structure and reporting lines as well as written job descriptions. Management reviews the data importer's organisational structure at least annually as part of strategic planning, and any changes are made as needed based on changing reporting lines, authorities, and responsibilities.

The data importer has following security policies and related processes in place:

* **(a)** Data classification and business impact assessment
* **(b)** Selection, documentation, and implementation of security controls
* **(c)** Assessment of security controls
* **(d)** User access authorisation and provisioning
* **(e)** Removal of user access
* **(f)** Monitoring of security controls
* **(g)** Security management

### 3. Access control

The data importer has implemented role-based access controls that limit access to sensitive information to only those individuals who require access based on job function, active employment, and management approval. The data importer maintains an up-to-date and complete inventory of information technology assets and asset owners.

Administrative level access to the data importer's critical systems (network, application, source code, and related databases) is limited to appropriate individuals based on job function and current employment with the data importer.

Administrative level access to critical system components including (production servers, databases, system infrastructure components, and front-end application level) are restricted to appropriate individuals based on job function and current employment with the data importer.

Access to the Amazon Web Services ("**AWS**") environment is controlled with security groups configured to prevent access based on predefined access control lists. Monitoring tools are in place to monitor the AWS environment and administrators receive notification of issues detected by the system based on pre-defined alert thresholds.

Sensitive authentication data such as service accounts and encryption keys are stored in a key management system. Access to sensitive authentication data is limited to only appropriate individuals based on job function and active employment with the data importer.

Remote access to the data importer's network and system infrastructure requires a unique username, password, and one-time multi-factor authentication code to authenticate. Remote access to the data importer's network and system infrastructure is limited to only appropriate individuals based on job function and active employment with the data importer.

Access to the data importer's systems requires a unique username and password. Password complexity standards within AWS are enforced and include the following:

* **(a)** Minimum password length is 16 characters
* **(b)** Require at least one uppercase letter from Latin alphabet (A–Z)
* **(c)** Require at least one lowercase letter from Latin alphabet (a–z)
* **(d)** Require at least one number
* **(e)** Require at least one non alphanumeric character ! @ # \$ % ^ & \* ( ) \_ + - = \[ ] \{ } | '.
* **(f)** Passwords expires in 90 days
* **(g)** Allow users to change their own password

### 4. Segmentation of personal data

The data importer has logically segmented its network so that unrelated portions of the information system are isolated from each other. All public internet facing systems are segregated from the production network through network segmentation, firewalling, logical access restrictions, and the use of a load balancers which restricts access to production infrastructure. The data importer's information security program prohibits the use of shared user accounts unless approved by management.

### 5. Encryption and Transmission

All data classified as potentially sensitive is encrypted at the database level while at rest. All media containing sensitive data, including electronic, hardcopy, and photocopy, is destroyed when it is no longer needed for business or legal reasons as defined in the data importers' terms of service.

All data in transit is encrypted including the following:

* **(a)** Information transmitted over the public internet (HTTPS)
* **(b)** Data transferred within system components (TLS)
* **(c)** Data transferred between organisations (SFTP)

Access to modify data transmission protocols is limited to appropriate individuals based on job function, current employment status, and inquiry with the data importer's management team.

All authentication and data transmission to the production applications, the operating systems hosting the applications, and associated production databases take place over secure transmission channels (i.e. VPN, SSH, SFTP, TLS). All production databases are encrypted using AES-256 bit encryption.

### 6. Data Backup, Recovery and Availability

The data importer performs incremental backups of its critical information systems on a daily basis, and full backups are performed on at least a weekly basis. The data importer’s management is alerted in the case of a backup failure, and backup failures are tracked to remediation.

Established entity standards exist for infrastructure and software hardening and configurations for key system components and infrastructure. The data importer has established a business continuity plan and disaster recovery plan, both of which are reviewed, tested, and updated on an annual basis.

Customer data is backed up for 90 days in the primary data store, unless otherwise stated in the Customer’s contract. After 90 days, unless otherwise stated in Customer’s contract, it becomes the customer’s responsibility to manage, back up, or otherwise store their data per their use case.

All primary data stores are retained for at least 90 days unless otherwise specified in the customer’s contract.

To ensure data availability and avoid issues with data older than 90 days, customers are advised to configure webhooks in their dashboard account. All data received via webhooks should be backed up securely on their end.

The Data importer is fully responsible for the availability of product and services.

### 7. Incident Management and System Monitoring

The data importer's management team has implemented an incident response plan that outlines the requirements for responding to anomalies that are indicative of malicious acts, natural disasters, and errors affecting the entity's ability to meet its objectives.

Security events are documented, reviewed, and tracked to final remediation by data importer's management team. A root cause analysis is conducted to determine the cause and mitigate the risk of such an incident occurring in the future.

The data importer has security monitoring tools in place to monitor the data importer's production environment and provide an ongoing solution to monitor security threats and unusual system activities. The data importer's management team receives alerts from the tools, based on predefined thresholds, and confirmed security issues are tracked to remediation.

The data importer engages a third-party to perform external penetration tests of the system on an annual basis. Management assesses and prioritises the results of the penetration test and tracks issues of medium criticality or above to final remediation.

### 8. Asset and Software Management

The data importer has implemented a change management policy that outlines the requirements for authorisation, design, development, configuration, documentation, testing, approval, and implementation of changes to infrastructure, data, and software. All system changes are tested, reviewed, and approved prior to implementation to the production environment. Access to make changes to source code is limited to only appropriate individuals based on job function and active employment with the data importer.

Version control software is in place to manage current versions of source code. Audit logs of all commits to source code libraries are maintained.

Source code scans are performed on in-scope application source code to detect potential vulnerabilities prior to the release of source code into the production environment. Any high-risk vulnerabilities are tracked to remediation prior to the promotion of each change into the production environment.

### 9. Physical Security

The data importer has a cloud-based infrastructure in AWS and relies on this subservice organisation to operate physical access controls to the data centres hosting the data importer's infrastructure. Additionally, the data importer does not own any facilities containing information assets which would require physical security controls to be implemented.

### 10. Endpoint Security

The data importer has enforced the following mobile device hardening standards for laptops and mobile phones:

* **(a)** Evidence of device encryption
* **(b)** Enterprise antivirus enabled
* **(c)** Antivirus daily updates
* **(d)** Requirement of user name and password
* **(e)** Patches or regular OS updates

All laptops with access to the data importer's network are configured to enforce hard drive encryption.

The data importer's security policy prohibits the use of removable media storage without prior approval from management.

Anti-virus/anti-malware software is installed on workstations and laptops supporting the system. Antivirus software is configured to receive an updated virus signature at least daily. Network operations receives a report of devices that have not been updated in more than 24 hours and follows up on those devices.

### 11. Service providers

The data importer has written contracts in place with service providers which require them to implement appropriate security measures to protect the personal data to which they have access and to limit the use of personal data in accordance with the data importer's instructions.

### 12. Customer Communications

The data importer has reporting mechanisms in place for reporting security issues and compliance concerns from internal and external system users. Each report is reviewed by appropriate management personnel, based on the nature of the suspected security issues, in accordance with the data importer's Incident Response Policy.

Security incidents and unauthorised disclosures of internal or external user data are communicated to data subjects, relevant legal and regulatory authorities, and others as required by law, contract, or at the advice of legal counsel, per the incident response plan.

Customer responsibilities, which include responsibility for reporting operational failures, incidents, problems, concerns, and complaints, and the process for doing so, are described within customer agreements. The data importer communicates relevant security and privacy commitments, made available on its public-facing website or by written request.

When major changes to security or privacy commitments are made, FingerprintJS communicates these changes to impacted stakeholders via email.

System descriptions are made available to authorised external users that delineate the boundaries of the system and describe relevant system components as well as the purpose and design of the system.

### 13. Staff training and awareness

The data importer maintains security policies and procedures which communicate objectives and responsibilities for internal control, necessary to support the function of internal control. Policies and procedures are made available to employees in the data importer's policy document repository.

The data importer has established standards and guidelines for management's, employees', and contractors' ethical behaviour, as outlined in the data importer's employee handbook. The handbook includes a termination policy for personnel who violate the data importer's policies and procedures, which may include disciplinary action up to and including involuntary termination.

All employees and contractors are required to sign an employment agreement, that requires personnel to adhere to the data importer's code of conduct, security, and confidentiality policies and procedures as part of their initial terms and conditions of employment.

The data importer has implemented a formal disciplinary process to address instances of noncompliance with the data importer's standards of conduct related to security which includes disciplinary measures up to and including termination.

Roles and responsibilities are defined by written job descriptions and communicated to the data importer's employees upon hire, as well as to their managers and supervisors.

Management monitors personnel compliance with the code of conduct through a complaint submission system which serves as a mechanism for reporting deviations from the code of conduct. Any deviations to the code of conduct are addressed immediately in accordance with the employee handbook.

## Schedule 4 — List of Sub-processors

| Name                               | Address                                              | Processing Activities                                                                           |
| ---------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Amazon Web Services, Inc (AWS)** | 410 Terry Avenue North, Seattle, WA 98109-5210       | Our primary provider for data processing infrastructure.                                        |
| **Rollbar, Inc.**                  | 510 Federal Street Suite 401 San Francisco, CA 94107 | Used for error tracking and reporting; may access IP addresses in specific debugging scenarios. |
| **AC PM, LLC (d/b/a Postmark)**    | 1 N Dearborn Street, Suite 500, Chicago, IL 60602    | Our transactional email provider, which has access to account email addresses.                  |
| **WorkOS, Inc.**                   | 548 Market St, PMB 86125, San Francisco, CA 94104    | Provides SAML SSO functionality and also has access to account email addresses.                 |

## Schedule 5 — Standard Contractual Clauses

### 1. EU SCCS

With respect to any transfers referred to in Section 3.1, the Standard Contractual Clauses shall be completed as follows:

#### 1.1

The Controller Clauses will apply with respect to FingerprintJS's processing of Administration Data, Usage Data and Fraud Identification Data for Controller Purposes; otherwise, the Processor Clauses will apply to FingerprintJS’s processing of Customer Personal Data.

#### 1.2

Clause 7 of the Standard Contractual Clauses (*Docking Clause*) does not apply.

#### 1.3

Option 2 of Clause 9(a) (*General written authori**s**ation*) shall apply, and the time period to be specified is determined in Section 4.3 of the DPA.

#### 1.4

The option in Clause 11(a) of the Standard Contractual Clauses *(Independent dispute resolution body*) does not apply.

#### 1.5

With regard to Clause 17 of the Standard Contractual Clauses (*Governing law*), the Parties agree that option 1 will apply and the governing law will be Irish law.

#### 1.6

In Clause 18 of the Standard Contractual Clauses (*Choice of forum and jurisdiction*), the Parties submit themselves to the jurisdiction of the courts of Ireland.

#### 1.7

For the Purpose of Annex I of the Standard Contractual Clauses: (i) Schedule 1 contains the specifications regarding the parties and the competent supervisory authority; and (ii) in respect of the Processor Clauses: Part 1 of Schedule 2, and in respect of the Controller Clauses: Part 2 of Schedule 2, contains the specifications regarding the description of transfer.

#### 1.8

For the Purpose of Annex II of the Standard Contractual Clauses, Schedule 3 of the DPA contains the technical and organisational measures.

### 2. UK Addendum

#### 2.1

This paragraph 2 (*UK Addendum*) shall apply to any transfer of Customer Personal Data from the Customer (as data exporter) to FingerprintJS (as data importer), to the extent that:

* **(a)** the UK Data Protection Laws apply to the Customer when making that transfer; or
* **(b)** the transfer is an "onward transfer" as defined in the Approved Addendum.

#### 2.2

As used in this paragraph 2:

"**Approved Addendum**" means the template addendum, version B.1.0 issued by the UK Information Commissioner under S119A(1) Data Protection Act 2018 and laid before the UK Parliament on 2 February 2022, as it may be revised according to Section 18 of the Approved Addendum.

"**UK Data Protection Laws**" means all laws relating to data protection, the processing of Personal Data, privacy and/or electronic communications in force from time to time in the UK, including the UK GDPR and the Data Protection Act 2018.

#### 2.3

The Approved Addendum will form part of this DPA with respect to any transfers referred to in paragraph 2.1, and execution of the Agreement or this DPA shall have the same effect as signing the Approved Addendum.

#### 2.4

The Approved Addendum shall be deemed completed as follows:

* **(a)** the "Addendum EU SCCs" shall refer to the SCCs as they are incorporated into this Agreement in accordance with Section 3.1 and this Schedule 5;
* **(b)** Table 1 of the Approved Addendum shall be completed with the details in Schedule 1;
* **(c)** the "Appendix Information" shall refer to the information set out in Schedule 1, Schedule 2 (as relevant, with respect to the Controller Clauses and Processor Clauses), Schedule 3 and Schedule 4;
* **(d)** for the purposes of Table 4 of the Approved Addendum, FingerprintJS (as data importer) may end this DPA, to the extent the Approved Addendum applies, in accordance with Section ‎19 of the Approved Addendum; and
* **(e)** Section 16 of the Approved Addendum is not used.

### 3. Swiss addendum

#### 3.1

This Swiss Addendum will apply to any processing of Customer Personal Data that is subject to Swiss Data Protection Laws or to both Swiss Data Protection Laws and the GDPR.

#### 3.2 Interpretation of this Addendum

* **(a)** Where this Addendum uses terms that are defined in the Standard Contractual Clauses, those terms will have the same meaning as in the Standard Contractual Clauses. In addition, the following terms have the following meanings:

"**Addendum**" means this addendum to the Clauses;

"**Clauses**" means the Standard Contractual Clauses as incorporated into this DPA in accordance with Section 3.1 and as further specified in this Schedule 5; and

"**FDPIC**" means the Federal Data Protection and Information Commissioner.

* **(b)** This Addendum shall be read and interpreted in a manner that is consistent with Swiss Data Protection Laws, and so that it fulfils the Parties' obligations under Article 16(2)(d) of the FADP.
* **(c)** This Addendum will not be interpreted in a way that conflicts with rights and obligations provided for in Swiss Data Protection Laws.
* **(d)** Any references to legislation (or specific provisions of legislation) means that legislation (or specific provision) as it may change over time. This includes where that legislation (or specific provision) has been consolidated, re-enacted and/or replaced after this Swiss Addendum has been entered into.
* **(e)** In relation to any processing of Personal Data subject to Swiss Data Protection Laws or to both Swiss Data Protection Laws and the GDPR, this Addendum amends and supplements the Clauses to the extent necessary so they operate:
  * **(i)** for transfers made by the data exporter to the data importer, to the extent that Swiss Data Protection Laws apply to the data exporter’s processing when making that transfer; and
  * **(ii)** as standard data protection clauses approved, issued or recognized by the FDPIC for the purposes of Article 16(2)(d) of the FADP.

#### 3.3 Hierarchy

In the event of a conflict or inconsistency between this Addendum and the provisions of the Clauses or other related agreements between the Parties, existing at the time this Addendum is agreed or entered into thereafter, the provisions which provide the most protection to data subjects will prevail.

#### 3.4

**Changes to the Clauses for transfers exclusively subject to Swiss Data Protection Laws**

To the extent that the data exporter's processing of Personal Data is exclusively subject to Swiss Data Protection Laws, or the transfer of Personal Data from a data exporter to a data importer under the Clauses is an "onward transfer" (as defined in the Clauses, as amended by the remainder of this paragraph 3.4) the following amendments are made to the Clauses:

* **(a)** References to the "Clauses" or the "SCCs" mean this Swiss Addendum as it amends the SCCs.
* **(b)** Clause 6 Description of the transfer(s) is replaced with:

"*The details of the transfer(s), and in particular the categories of Personal Data that are transferred and the purpose(s) for which they are transferred, are those specified in* *Schedule 1* *of this DPA where Swiss Data Protection Laws apply to the data exporter’s* *processing when making that transfer*."

* **(c)** References to "Regulation (EU) 2016/679" or "that Regulation" or ""GDPR" are replaced by "Swiss Data Protection Laws" and references to specific Article(s) of "Regulation (EU) 2016/679" or "GDPR" are replaced with the equivalent Article or Section of Swiss Data Protection Laws extent applicable.
* **(d)** References to Regulation (EU) 2018/1725 are removed.
* **(e)** References to the "European Union", "Union", "EU" and "EU Member State" are all replaced with "Switzerland".
* **(f)** Clause 13(a) and Part 3 of Annex 1.C. are not used; the "competent supervisory authority" is the FDPIC;
* **(g)** Clause 17 is replaced to state: "*These Clauses are governed by the laws of Switzerland*".
* **(h)** Clause 18 is replaced to state: "*Any dispute arising from these Clauses relating to Swiss Data Protection Laws will be resolved by the courts of Switzerland. A* *data* *subject may also bring legal proceedings against the data exporter and/or data importer before the courts of Switzerland in which he/she has his/her habitual residence. The Parties agree to submit themselves to the jurisdiction of such courts*."

#### 3.5

**Supplementary provisions for transfers of Personal data subject to both the GDPR and Swiss Data Protection Laws**

* **(a)** To the extent that the data exporter's processing of Personal Data is subject to both Swiss Data Protection Laws and the GDPR, or the transfer of Personal Data from a data exporter to a data importer under the Clauses is an "onward transfer" under both the Clauses and the Clauses as amended by paragraph 3.4 of this Addendum:
  * **(i)** for the purposes of Clause 13(a) and Annex I.C.:
    * **(A)** the FDPIC shall act as competent supervisory authority with respect to any transfers of Personal Data to the extent Swiss Data Protection Laws apply to the data exporter's processing when making that transfer, or such transfer is an "onward transfer" as defined in the Clauses (as amended by paragraph 3.4 of this Addendum); and
    * **(B)** subject to the provisions of paragraph 2 of this Schedule 5 (UK Addendum), the supervisory authority identified in Schedule 1 shall act as competent supervisory authority with respect to any transfers of Personal Data to the extent the GDPR applies to the data exporter's processing, or such transfer is an "onward transfer" as defined in the Clauses.
* **(b)** The terms "European Union", "Union", "EU", and "EU Member State" shall not be interpreted in a way that excludes the ability of data subjects in Switzerland bringing a claim in their place of habitual residence in accordance with Clause 18(c) of the Clauses.

What’s Next

* [Start your free subscription now](https://dashboard.fingerprintjs.com/signup/)


# DPA (US SPL)
Source: https://docs.fingerprint.com/docs/dpa-usspl

US State Privacy Laws Data Processing Addendum

# US State Privacy Laws Data Processing Addendum

This is an addendum to the Customer Terms of Service or other electronic or mutually executed written agreement between FingerprintJS Inc. (“**FingerprintJS**”) and Customer (each a “**Party**”; collectively the “**Parties**”) that references it (“**Agreement**”). This Addendum shall only apply and bind the Parties if and to the extent the US State Privacy Laws apply to the Processing of Customer Personal Information (each as defined below). All capitalized terms not defined in this Addendum shall have the meanings set forth in the Agreement. This Addendum prevails over any conflicting terms of the Agreement, but does not otherwise modify the Agreement. Customer enters into this Addendum on behalf of itself and, to the extent required under the US Data Protection Laws, in the name and on behalf of its Authorized Affiliates (defined below).

**The Parties agree as follows:**

## 1. Definitions

“**Additional Services**” means additional model-driven fraud prediction and detection services and access to the DRN, in each case as agreed between the Customer and FingerprintJS.

“**Affiliate**” means an entity that directly or indirectly Controls, is Controlled by or is under common Control with an entity.

“**Authorized Affiliate**” means any of Customers’ Affiliate(s) permitted to or otherwise receiving the benefit of the Service and Additional Services pursuant to the Agreement.

"**Controller**" has the meaning, or equivalent meaning given to such term, or equivalent terms, under the US Data Protection Laws including a "Business" under the CCPA.

“**CCPA**” means the California Consumer Privacy Act of 2018, Cal. Civ. Code § 1798.100 et seq., as amended, including its implementing regulations and the California Privacy Rights Act of 2020.

“**Control**” or

“**Controlled**” means the possession, directly or indirectly, of the power to direct or cause the direction of management and policies of an entity, whether through the ability to exercise voting power, by contract or otherwise.

“**Customer**” shall have the meaning ascribed to it in the Agreement.

“**Customer Personal Information**” means any Personal Information that FingerprintJS and/or its Affiliates Processes in the course of providing the Service and Additional Services to Customer under the Agreement as set out in Schedule 1.

"**Data Subject**" means an individual to whom Personal Information relates.

"**Deidentified Data**" means data created using Customer Personal Information that cannot reasonably be linked to such Customer Personal Information, directly or indirectly.

“**Personal Information**” means “personal information”, “personal data”, “personally identifiable information” or similarly defined data or information under US Data Protection Laws.

"**Processing**" means any operation or set of operations (including storage) that is performed on Personal Information or on sets of Personal Information, whether or not by automated means. "Process", "Processes" and "Processed" will be interpreted accordingly.

“**Processor**” has the meaning, or equivalent meaning given to such term, or equivalent terms, under the US Data Protection Laws including "Service Provider" under the CCPA.

"**Security Incident**" means any breach of security that leads to the accidental or unlawful destruction, loss, alteration, unauthorised disclosure of or access to Personal Information.

"**Sub-processor**" means a Processor instructed to Process Personal Information on behalf of another Processor.

"**US Data Protection Laws**" means all applicable federal and state laws rules, regulations, and governmental requirements relating to data protection, the Processing of Personal Information, privacy and/or data protection in force from time to time in the United States, including (without limitation) the CCPA.

## 2. Scope and Applicability of this Addendum

### 2.1

This DPA applies where and only to the extent that FingerprintJS Processes Customer Personal Information in the course of providing the Service and Additional Services and such Processing of Customer Personal Information is subject to US Data Protection Laws. The Parties agree to comply with the terms and conditions in this DPA in connection with the Processing of such Customer Personal Information.

### 2.2

Customer is a Controller and appoints FingerprintJS as a Processor to Process the Customer Personal Information on behalf of Customer.

## 3. Instructions for information processing

### 3.1

FingerprintJS will only Process Customer Personal Information on behalf of and under the instructions of Customer and in accordance with US Data Protection Laws. The Agreement and this DPA shall constitute the instructions to FingerprintJS for the Processing of Customer Personal Information by FingerprintJS. The Customer may issue further written instructions in accordance with this DPA.

### 3.2

The details of the Processing of Customer Personal Information under the Agreement and this DPA, including the type of data subject, nature and purpose and duration of Processing are described in the Agreement and in Schedule 1.

### 3.3

FingerprintJS is prohibited from:

* **(a)** selling Customer Personal Information or otherwise making Customer Personal Information available to any third party for monetary or other valuable consideration;
* **(b)** sharing Customer Personal Information with any third party for cross-context behavioral advertising;
* **(c)** retaining, using, or disclosing Customer Personal Information for any purpose other than for the business purposes specified in the Agreement or as otherwise permitted by US Data Protection Laws;
* **(d)** retaining, using, or disclosing Customer Personal Information outside of the direct business relationship between the Parties, unless permitted by US Data Protection Laws; and
* **(e)** except as otherwise permitted by US Data Protection Laws, combining Customer Personal Information with Personal Information that FingerprintJS receives from or on behalf of another person or persons, or collects from FingerprintJS’ own interaction with the applicable Data Subject.

### 3.4

Without limiting the foregoing, FingerprintJS may retain, use or disclose Personal Information:

* **(a)** for internal use by FingerprintJS to build or improve the quality of its Service and Additional Services, even if this business purpose is not specified in the Agreement;
* **(b)** to prevent, detect, or investigate data security incidents or protect against malicious, deceptive, fraudulent or illegal activity, even if this business purpose is not specified in the Agreement; or
* **(c)** for the purposes set out in US Data Protection Laws, including in California Civil Code section 1798.145, subdivisions (a)(1) through (a)(7).

## 4. Compliance and notice

### 4.1

Each Party agrees to comply with applicable obligations under US Data Protection Laws, and shall provide the same level of privacy protection to Personal Information as required by US Data Protection Laws.

### 4.2

Customer represents and warrants that:

* **(a)** it has provided notice to Data Subjects, as required under US Data Protection Laws for a Controller, that the Personal Information is being used or shared as set forth in the Agreement;
* **(b)** it has, solely to the extent required under US Data Protection Laws, obtained consent from Data Subjects for the lawful processing of Personal Information as set forth in the Agreement; and
* **(c)** taking into account the state of the art, the costs of implementation and the nature, scope, context and purposes of Processing as well as the risk of varying likelihood and severity for the rights and freedoms of natural persons, the security measures set out in Schedule 2 are:
  * **(i)** appropriate to ensure the security of the Customer Personal Information, including protection against a Security Incident; and
  * **(ii)** otherwise consistent with the Customer's obligations US Data Protection Laws.

## 5. Sub-processors

### 5.1

FingerprintJS shall: (i) enter into a written agreement with any Sub-processor Processing Customer Personal Information imposing the same data protection obligations on the Sub-processor as set out in this DPA; and (ii) remain responsible for its compliance with the obligations of this DPA and for any acts or omissions of the Sub-processor that cause FingerprintJS to breach any of its obligations under this DPA.

### 5.2

FingerprintJS shall provide Customer with fourteen (14) calendar days' notice (for which email shall suffice) of the appointment of any Sub-processors, including any information reasonably necessary to enable the Customer to assess the Sub-processor and exercise its right to object.

### 5.3

If the Customer objects to FingerprintJS' use of a new Sub-processor it shall: (i) notify FingerprintJS of its objection promptly in writing within five (5) calendar days of receipt of FingerprintJS' notice in accordance with Section 5.2; and (ii) provide documentary evidence that reasonably shows that the Sub-processor does not or cannot comply with the requirements in this DPA. In such an event, the Parties shall discuss such concerns in good faith with a view to achieving commercially reasonable resolution. If this is not possible, either Party may terminate the applicable Service and Additional Services that cannot be provided by FingerprintJS without the use of the objected-to new Sub-processor by giving to the other Party thirty (30) calendar days' written notice. During such notice period, FingerprintJS may suspend the affected portion of the Service and Additional Services.

## 6. Security and audits

### 6.1

FingerprintJS shall implement and maintain appropriate technical and organisational security measures to protect Customer Personal Information from Security Incidents and preserve the security and confidentiality of the Customer Personal Information, in accordance with FingerprintJS' security standards described in Schedule 2 (the “**Security Measures**”).

### 6.2

Customer acknowledges that the Security Measures are subject to technical progress and development and that FingerprintJS may, by written notice to the Customer, update or modify the Security Measures from time to time following any review by FingerprintJS of the Security Measures, provided that such updates and modifications do not result in the degradation of the overall level of protection afforded to the Customer Personal Information by FingerprintJS under this DPA.

### 6.3

FingerprintJS will notify Customer in writing without undue delay after becoming aware of any Security Incident, and reasonably cooperate with regards to any obligation of Customer under US Data Protection Laws to make any notifications in respect of a Security Incident, such as to individuals, supervisory authorities or other regulatory authorities.

### 6.4

FingerprintJS' notification of, or response to, a Security Incident under this Section 6 will not be construed as an acknowledgement by FingerprintJS of any fault or liability with respect to the Security Incident.

### 6.5

FingerprintJS shall ensure that any person who is authorised by FingerprintJS to Process Customer Personal Information (including its staff, agents and subcontractors) shall be under an appropriate obligation of confidentiality (whether a contractual or statutory duty).

### 6.6

Customer shall have the right to take reasonable and appropriate steps to help ensure that FingerprintJS uses the Customer Personal Information collected pursuant to the Agreement in a manner consistent with its obligations under US Data Protection Laws. Customer may, upon notice to FingerprintJS, take reasonable and appropriate steps to stop and remediate unauthorized use of Customer Personal Information.

### 6.7

FingerprintJS shall allow, cooperate with and contribute to, reasonable assessments, audits or inspections by Customer (or its designated assessor or auditor, or an independent assessor) of FingerprintJS' policies and technical and organizational security measures with respect to Customer Personal Information.

### 6.8

With respect to any assessments, audits or inspections conducted under Section 6.7, the Parties agree that:

* **(a)** all such assessments, audits or inspections shall be conducted:
  * **(i)** only once per year, or more frequently if any audit indicates that FingerprintJS is in non-compliance with this DPA;
  * **(ii)** on reasonable written notice to FingerprintJS;
  * **(iii)** only during FingerprintJS' normal business hours;
  * **(iv)** in a manner that does not disrupt FingerprintJS' business; and
  * **(v)** by reference to an appropriate and accepted control standard or framework; and
* **(b)** the Customer (or, where applicable, a third-party independent auditor appointed by the Customer) shall:
  * **(i)** enter into a confidentiality agreement with FingerprintJS prior to conducting the audit in such form as FingerprintJS may request; and
  * **(ii)** ensure that its personnel comply with FingerprintJS' and any Sub-processor's policies and procedures when attending FingerprintJS' or Sub-processor's premises, as notified to the Customer by FingerprintJS or Sub-processor.

### 6.9

FingerprintJS shall provide written responses (on a confidential basis) to all reasonable requests for information made by Customer, including responses to information security and audit questionnaires, that Customer (acting reasonably) considers necessary to confirm FingerprintJS' compliance with this DPA, provided that Customer shall not exercise this right more than once per year.

### 6.10

FingerprintJS shall notify Customer if it makes a determination that it can no longer meet its obligations under US Data Protection Laws.

## 7. Data Subject requests

### 7.1

If FingerprintJS receives a request made pursuant to US Data Protection Laws directly from a Data Subject with respect to Customer Personal Information, then FingerprintJS shall either act on behalf of Customer or in accordance with Customer’s instructions in responding to the request or inform the Data Subject that the request cannot be acted upon because the request has been sent to a Processor. FingerprintJS is not required to comply with a request submitted by the Data Subject directly to FingerprintJS to the extent FingerprintJS has collected, used, Processed or retained the Customer Personal Information in its role as a Processor to the Controller.

### 7.2

FingerprintJS shall provide reasonable assistance to Customer in facilitating compliance with verifiable Data Subject rights requests, including but not limited to providing the Controller the Data Subject’s Customer Personal Information in FingerprintJS’ possession, which FingerprintJS obtained as a result of providing the Service to Customer, and by correcting inaccurate information, or by enabling Customer to do the same. In the event FingerprintJS has collected Customer Personal Information pursuant to a written contract with Customer, FingerprintJS shall assist Customer through appropriate technical and organizational measures complying with requirements under US Data Protection Laws, including the requirements of subdivisions (d) through (f) of Cal. Civ. Code 1798.100, taking into account the nature of the Processing.

## 8. Deidentified data

### 8.1

If FingerprintJS receives Deidentified Data from or on behalf of Customer, or creates Deidentified Data, FingerprintJS shall:

* **(a)** take reasonable measures to ensure the information cannot be associated with a Data Subject;
* **(b)** publicly commit to Process the Deidentified Data solely in deidentified form and not to attempt to reidentify the information; and
* **(c)** contractually obligate any recipients of the Deidentified Data to comply with the foregoing requirements and Data Protection Laws.

## 9. Return and deletion

### 9.1

Upon deactivation of the Service and Additional Services, FingerprintJS shall, subject to Section 9.2: (i) if requested to do so by the Customer within seven (7) days of the date of termination of the Agreement or deactivation of the Service and Additional Services, return a complete copy of all Customer Personal Information by secure file transfer in such a format as notified by the Customer to FingerprintJS; and (ii) delete and use all reasonable efforts to procure the deletion of all other copies of Customer Personal Information Processed by FingerprintJS or any Sub-processors.

### 9.2

FingerprintJS may retain Customer Personal Information:

* **(a)** to the extent required or permitted by applicable laws, and only for such period and such purposes as required or permitted by applicable laws; or
* **(b)** to the extent that the Customer Personal Information has been archived on back-up systems, provided that FingerprintJS shall securely isolate and protect such Customer Personal Information from any further Processing, except to the extent required by applicable law, and purge such Customer Personal Information from the applicable back-up systems in accordance with its normal back-up cycle.

### 9.3

FingerprintJS shall, with respect to any Customer Personal Information retained in accordance with Section 9.2 continue to comply with its obligations to protect such Customer Personal Information as set forth in this DPA.

## 10. Costs

### 10.1

The Customer shall pay to FingerprintJS on demand all costs and expenses incurred by FingerprintJS in connection with:

* **(a)** implementing any changes to the Service and Additional Services under Section 5.3;
* **(b)** facilitating and contributing to any audits of FingerprintJS under Section 6;
* **(c)** facilitating and contributing to any audits of FingerprintJS conducted by a supervisory authority; and
* **(d)** any assistance provided by FingerprintJS to the Customer with its fulfilment of its obligations to respond to Data Subjects' requests under Section 7.

## 11. Miscellaneous

### 11.1

Except for the changes made by this DPA, the Agreement remains unchanged and in full force and effect. In the event of any conflict between the Agreement and this DPA, this DPA shall take precedence.

### 11.2

This DPA is a part of and incorporated into the Agreement so references to "Agreement" in the Agreement shall include this DPA.

### 11.3

In no event shall any Party limit its liability with respect to any individual's data protection rights under this DPA or otherwise.

## Schedule 1 — Details of processing

<u>Data subjects</u>

The personal data transferred concern the following categories of data subjects:

* The Customer’s end users who visit the Customer’s sites and services (“**End Users**”).
* The Customer's employees and contractors that the Customer authorises to access and use the Service (“**Authorised Users**”).

<u>Nature and Purpose(s) of the data Processing</u>

The purpose of the data transfer and further Processing is the provision and maintenance of FingerprintJS' Service and Additional Services, including internal record-keeping, billing, product development and sales and marketing.

<u>Duration</u>

The Personal Information will be retained for the duration of the Agreement, subject to Section 9 of the DPA.

<u>Categories of data</u>

The Personal Information transferred concern the following categories of data:

End Users:

* Personal Information contained within Visitor Data, including information relating to an End User's device, operating system, browser, browser configuration, IP address, and approximate location, and IDs associated with successful detections of fraud on the Customer’s sites and services.

Authorised Users:

* contact information, including name, address, phone number, email address, login details, employing / engaging organisation;
* account information, including login information;
* payment and transaction information;
* support request information;
* contact preferences, including preference set for notifications, marketing communications;
* comments and opinions; and
* technical information regarding access to the Service (including IP address, approximate location, pages viewed and log data, display and active functionalities).

<u>Sensitive data</u>

None.

## Schedule 2 — Technical and organisational security measures

### 1. Introduction

FingerprintJS employs a combination of policies, procedures, guidelines and technical controls to protect the personal data it Processes from accidental loss and unauthorised access, disclosure or destruction.

### 2. Governance and Policies

FingerprintJS has organised leadership and defined policies related to information security to ensure alignment with business objectives to adequately serve clients. These policies are reviewed and approved annually by management and updates are communicated to employees and relevant external parties.

Roles and responsibilities for teams and team members are defined within FingerprintJS’ organisational structure and reporting lines as well as written job descriptions. Management reviews FingerprintJS’ organisational structure at least annually as part of strategic planning, and any changes are made as needed based on changing reporting lines, authorities, and responsibilities.

FingerprintJS has the following security policies and related Processes in place:

* **(a)** Data classification and business impact assessment
* **(b)** Selection, documentation, and implementation of security controls
* **(c)** Assessment of security controls
* **(d)** User access authorisation and provisioning
* **(e)** Removal of user access
* **(f)** Monitoring of security controls
* **(g)** Security management

### 3. Access control

FingerprintJS has implemented role-based access controls that limit access to sensitive information to only those individuals who require access based on job function, active employment, and management approval. FingerprintJS maintains an up-to-date and complete inventory of information technology assets and asset owners.

Administrative level access to FingerprintJS’ critical systems (network, application, source code, and related databases) is limited to appropriate individuals based on job function and current employment with FingerprintJS.

Administrative level access to critical system components including (production servers, databases, system infrastructure components, and front-end application level) are restricted to appropriate individuals based on job function and current employment with FingerprintJS.

Access to the Amazon Web Services ("**AWS**") environment is controlled with security groups configured to prevent access based on predefined access control lists. Monitoring tools are in place to monitor the AWS environment and administrators receive notification of issues detected by the system based on pre-defined alert thresholds.

Sensitive authentication data such as service accounts and encryption keys are stored in a key management system. Access to sensitive authentication data is limited to only appropriate individuals based on job function and active employment with FingerprintJS.

Remote access to FingerprintJS' network and system infrastructure requires a unique username, password, and one-time multi-factor authentication code to authenticate. Remote access to FingerprintJS' network and system infrastructure is limited to only appropriate individuals based on job function and active employment with FingerprintJS.

Access to FingerprintJS' systems requires a unique username and password. Password complexity standards within AWS are enforced and include the following:

* **(a)** Minimum password length is 16 characters
* **(b)** Require at least one uppercase letter from Latin alphabet (A–Z)
* **(c)** Require at least one lowercase letter from Latin alphabet (a–z)
* **(d)** Require at least one number
* **(e)** Require at least one non alphanumeric character ! @ # \$ % ^ & \* ( ) \_ + - = \[ ] \{ } | '.
* **(f)** Passwords expires in 90 days
* **(g)** Allow users to change their own password

### 4. Segmentation of personal data

FingerprintJS has logically segmented its network so that unrelated portions of the information system are isolated from each other. All public internet facing systems are segregated from the production network through network segmentation, firewalling, logical access restrictions, and the use of a load balancers which restricts access to production infrastructure. FingerprintJS' information security program prohibits the use of shared user accounts unless approved by management.

### 5. Encryption and Transmission

All data classified as potentially sensitive is encrypted at the database level while at rest. All media containing sensitive data, including electronic, hardcopy, and photocopy, is destroyed when it is no longer needed for business or legal reasons as defined in FingerprintJS' terms of service.

All data in transit is encrypted including the following:

* **(a)** Information transmitted over the public internet (HTTPS)
* **(b)** Data transferred within system components (TLS)
* **(c)** Data transferred between organisations (SFTP)

Access to modify data transmission protocols is limited to appropriate individuals based on job function, current employment status, and inquiry with FingerprintJS' management team.

All authentication and data transmission to the production applications, the operating systems hosting the applications, and associated production databases take place over secure transmission channels (i.e. VPN, SSH, SFTP, TLS). All production databases are encrypted using AES-256 bit encryption.

### 6. Data Backup, Recovery and Availability

FingerprintJS performs incremental backups of its critical information systems on a daily basis, and full backups are performed on at least a weekly basis. FingerprintJS’ management is alerted in the case of a backup failure, and backup failures are tracked to remediation.

Established entity standards exist for infrastructure and software hardening and configurations for key system components and infrastructure. FingerprintJS has established a business continuity plan and disaster recovery plan, both of which are reviewed, tested, and updated on an annual basis.

Customer data is backed up for 90 days in the primary data store, unless otherwise stated in the Customer’s contract. After 90 days, unless otherwise stated in Customer’s contract, it becomes the customer’s responsibility to manage, back up, or otherwise store their data per their use case.

All primary data stores are retained for at least 90 days unless otherwise specified in the customer’s contract.

To ensure data availability and avoid issues with data older than 90 days, customers are advised to configure webhooks in their dashboard account. All data received via webhooks should be backed up securely on their end.

FingerprintJS is fully responsible for the availability of product and services.

### 7. Incident Management and System Monitoring

FingerprintJS' management team has implemented an incident response plan that outlines the requirements for responding to anomalies that are indicative of malicious acts, natural disasters, and errors affecting the entity's ability to meet its objectives.

Security events are documented, reviewed, and tracked to final remediation by data importer's management team. A root cause analysis is conducted to determine the cause and mitigate the risk of such an incident occurring in the future.

FingerprintJS has security monitoring tools in place to monitor FingerprintJS' production environment and provide an ongoing solution to monitor security threats and unusual system activities. FingerprintJS' management team receives alerts from the tools, based on predefined thresholds, and confirmed security issues are tracked to remediation.

FingerprintJS engages a third-party to perform external penetration tests of the system on an annual basis. Management assesses and prioritises the results of the penetration test and tracks issues of medium criticality or above to final remediation.

### 8. Asset and Software Management

FingerprintJS has implemented a change management policy that outlines the requirements for authorisation, design, development, configuration, documentation, testing, approval, and implementation of changes to infrastructure, data, and software. All system changes are tested, reviewed, and approved prior to implementation to the production environment. Access to make changes to source code is limited to only appropriate individuals based on job function and active employment with FingerprintJS.

Version control software is in place to manage current versions of source code. Audit logs of all commits to source code libraries are maintained.

Source code scans are performed on in-scope application source code to detect potential vulnerabilities prior to the release of source code into the production environment. Any high-risk vulnerabilities are tracked to remediation prior to the promotion of each change into the production environment.

### 9. Physical Security

FingerprintJS has a cloud-based infrastructure in AWS and relies on this subservice organisation to operate physical access controls to the data centres hosting FingerprintJS' infrastructure. Additionally, FingerprintJS does not own any facilities containing information assets which would require physical security controls to be implemented.

### 10. Endpoint Security

FingerprintJS has enforced the following mobile device hardening standards for laptops and mobile phones:

* **(a)** Evidence of device encryption
* **(b)** Enterprise antivirus enabled
* **(c)** Antivirus daily updates
* **(d)** Requirement of user name and password
* **(e)** Patches or regular OS updates

All laptops with access to FingerprintJS' network are configured to enforce hard drive encryption.

FingerprintJS' security policy prohibits the use of removable media storage without prior approval from management.

Anti-virus/anti-malware software is installed on workstations and laptops supporting the system. Antivirus software is configured to receive an updated virus signature at least daily. Network operations receives a report of devices that have not been updated in more than 24 hours and follows up on those devices.

### 11. Service providers

FingerprintJS has written contracts in place with service providers which require them to implement appropriate security measures to protect the personal data to which they have access and to limit the use of personal data in accordance with FingerprintJS' instructions.

### 12. Customer Communications

FingerprintJS has reporting mechanisms in place for reporting security issues and compliance concerns from internal and external system users. Each report is reviewed by appropriate management personnel, based on the nature of the suspected security issues, in accordance with FingerprintJS' Incident Response Policy.

Security incidents and unauthorised disclosures of internal or external user data are communicated to data subjects, relevant legal and regulatory authorities, and others as required by law, contract, or at the advice of legal counsel, per the incident response plan.

Customer responsibilities, which include responsibility for reporting operational failures, incidents, problems, concerns, and complaints, and the process for doing so, are described within customer agreements. FingerprintJS communicates relevant security and privacy commitments, made available on its public-facing website or by written request.

When major changes to security or privacy commitments are made, FingerprintJS communicates these changes to impacted stakeholders via email.

System descriptions are made available to authorised external users that delineate the boundaries of the system and describe relevant system components as well as the purpose and design of the system.

### 13. Staff training and awareness

FingerprintJS maintains security policies and procedures which communicate objectives and responsibilities for internal control, necessary to support the function of internal control. Policies and procedures are made available to employees in FingerprintJS' policy document repository.

FingerprintJS has established standards and guidelines for management's, employees', and contractors' ethical behaviour, as outlined in FingerprintJS' employee handbook. The handbook includes a termination policy for personnel who violate FingerprintJS' policies and procedures, which may include disciplinary action up to and including involuntary termination.

All employees and contractors are required to sign an employment agreement, that requires personnel to adhere to FingerprintJS' code of conduct, security, and confidentiality policies and procedures as part of their initial terms and conditions of employment.

FingerprintJS has implemented a formal disciplinary process to address instances of noncompliance with FingerprintJS' standards of conduct related to security which includes disciplinary measures up to and including termination.

Roles and responsibilities are defined by written job descriptions and communicated to FingerprintJS' employees upon hire, as well as to their managers and supervisors.

Management monitors personnel compliance with the code of conduct through a complaint submission system which serves as a mechanism for reporting deviations from the code of conduct. Any deviations to the code of conduct are addressed immediately in accordance with the employee handbook.

***

What’s Next

* [Start your free subscription now](https://dashboard.fingerprintjs.com/signup/)


# Overview
Source: https://docs.fingerprint.com/docs/drn-overview



Fingerprint identifies millions of Android devices globally every month.

For each identified Android device, we generate and store a unique visitor ID and a collection of Smart Signals. When a device is identified again, additional Smart Signal data is added to the existing dataset. Often, when companies identify an Android device using our Android SDK, that device has already been recognized by other companies.

Since Fingerprint has a global database of Android device intelligence, we're offering it through our new Device Reputation Network (DRN) API. With this API, you can query our network using the visitor ID from a device you've identified. Unlike our [event-based Server API](/reference/server-api-get-event) , the DRN provides globally aggregated Smart Signals.

The DRN API is free to use, but is rate limited to prevent abuse. If you want to request a higher rate limit, contact us at `drn@fingerprint.com`.

<Tip>
  **DRN API requests do not count toward your monthly plan and are not billed.**
</Tip>

## Before you use the DRN

To get started, you’ll need to use our [Android SDK](/docs/native-android-integration#fingerprint-identification-sdk-for-android).

Please note, the iOS SDK and JavaScript agent SDK are not supported at this time.

After creating a Fingerprint account, integrate the Android SDK into your app to start identifying devices. For detailed instructions, refer to our Android integration guide. Once a device is identified, you can retrieve the visitor ID directly on the device, or if you're using our Zero Trust Mode and don't trust the devices, you can obtain it through a server-side API call.

With the Android device's visitor ID, you're ready to make an API call to the DRN.

## Making your first DRN API call

Ensure you have your secret API key and visitor ID, then make the following request:

#### `GET https://drn-api.fpjs.io/drn/{visitor_id}?signals={signals}`

Replace `{visitor_id}` with the visitor ID and provide signals you want. We support one or more signals in the `signals` query parameter. Use a comma separated list for the signal list.

In version `2024-09-01`, the DRN supports three global signals: **`regional_activity`**, **`suspect_score`**, and **`timestamps`**. More details about each signal are in the sections below.

If you want to request all three signals and your visitor ID is **`NSBNxrgR3h9hVkhR5mkc`**, the request will look like this:

```shell cURL theme={"theme":"github-dark-dimmed"}
curl --request GET \
  --url 'https://drn-api.fpjs.io/drn/NSBNxrgR3h9hVkhR5mkc?signals=regional_activity,suspect_score,timestamps' \
  --header 'Authorization: Bearer {secret-api-key}' \
  --header 'X-API-Version: 2024-09-01'
```

Make sure you provide your secret API key in the `Authorization` HTTP header. You can read all the details in our [DRN API reference](/reference/drn-api-overview).

## Global DRN signals

As of version `2024-09-01`, DRN supports three global signals:  **`regional_activity`,`suspect_score`, and`timestamps`** .

Additionally, DRN supports **chargeback and payment disputes reporting**. Using this feature, you can get a detailed information if an Android device is linked to chargebacks reported by other Fingerprint customers.

### regional\_activity

Represents a list of countries where the identified device was active in the last 30 days together with the level of activity in each country. Level of activity is a number between 0 and 1 and represents the percentage of activity in the country. For example if a device was active in a specific country 60% of the time, the level of activity will be `0.6`. [API reference](/reference/drn-api-get-by-visitor-id) . Note that the level of activity is scoped to a detector type.

We support two detector types: `ip` and `origin`. The `ip` detector detects a country code by the IP address at the moment of making an API call using the Android SDK. If a device is using a VPN, the `ip` detector will return the VPN exit node country.

The `origin` detector detects a real location of the device, utilizing our `originCountry` [feature](/docs/smart-signals-reference#vpn_origin_country)  of the mobile SDK VPN detection, regardless of the IP address location or attempts to hide the location using VPN. The `origin` detector does not require geolocation permissions from the user.

**Examples of different`activityPercentage` scenarios:**

| Real location country | Using VPN? | VPN IP country |
| :-------------------- | :--------- | :------------- |
| USA                   | no         | n/a            |

```json theme={"theme":"github-dark-dimmed"}
{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0},
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}
```

| Real location country | Using VPN? | VPN IP country        |
| :-------------------- | :--------- | :-------------------- |
| USA                   | yes        | USA, 100% of the time |

```json theme={"theme":"github-dark-dimmed"}
{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0},
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}
```

| Real location country | Using VPN? | VPN IP country        |
| :-------------------- | :--------- | :-------------------- |
| **Russia**            | yes        | USA, 100% of the time |

```json theme={"theme":"github-dark-dimmed"}
{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0}
      ]
    },
    {
      "code": "RU",
      "detectors": [
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}
```

| Real location country | Using VPN? | VPN IP country          |
| :-------------------- | :--------- | :---------------------- |
| **Russia**            | yes        | USA, 60% of the time    |
| **Russia**            | yes        | Canada, 40% of the time |

```json theme={"theme":"github-dark-dimmed"}
{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 0.6}
      ]
    },
    {
      "code": "CA",
      "detectors": [
        {"type": "ip", "activityPercentage": 0.4}
      ]
    },
    {
      "code": "RU",
      "detectors": [
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}
```

Regional activity gives a clear understanding where a device was physically located during the last 30 days and also where it wanted to **appear to be located**. Analyzing the detector types and the origin country helps prevent geo-related fraud.

**Output format**:

[API reference available in this document](/reference/drn-api-get-by-visitor-id).

```json theme={"theme":"github-dark-dimmed"}
"regionalActivity": [
  // RFC 3339 format, goes 30 days back from the time request received on the server in UTC
  "startDate": "2023-12-16T23:12:59Z",
  // The time the request was received on the server in UTC
  "endDate": "2024-01-16T23:12:59Z",
  // One country object per country of activity. 
  // One or two detectors are possible in each country.
  "countries": [
    {
      // Country codes are capitalized as defined in the ISO 3166-1 alpha 2 standard
      "code": "US" | "GB" | ...,
      "detectors": [
        {
          // Two detector types: "ip" and "origin"
          // "ip"-when the country is detected by IP address
          // "origin"-when the country is detected by "originCountry" feature of our VPN detection.
          // "origin" represents the country of real location
          "type": "ip" | "origin",
          // A number that's always > 0 and <= 1.
          "activityPercentage": Number
        }]
    }]
}
```

**Output example**:

```javascript theme={"theme":"github-dark-dimmed"}
// Device is physically based in Mexico and is also active in the US 20% of the time via VPN.
// Its response could look like this, 
// assuming the originCountry is available 
// (if the device is using the supported version of Android SDK).
// Note that one API call response can have both "origin" and "ip" at the same time, 
// because even when the originCountry is available, we should also use the IP country 
// (to capture the fact of the VPN usage).
"regionalActivity": {
  // Use RFC 3339 format, goes 30 days back from the time request received on the server.
  // UTC time zone
  "startDate": "2023-12-16T23:12:59Z",
    // The time the request was received on the server in UTC timezone
    "endDate": "2024-01-16T23:12:59Z",
    "countries": [
        // it's clear device is based in MX physically
        {
          "code": "MX",
          "detectors": [
            { "type": "origin", "activityPercentage": 1 },
            { "type": "ip", "activityPercentage": 0.8 }
          ]
        },
        // but 20% of the time makes VPN calls out of the US IP address
        { "code": "US", "detectors": [{ "type": "ip", "activityPercentage": 0.2 }] }
      ]
}
```

### suspect\_score

Suspect Score is a single value representing how many suspicious Smart Signals were in a particular request. You can read more in this [Smart Signals Guide](/docs/suspect-score) . The suspect score is  calculated for each Fingerprint API request that your application makes with Android SDK.

The DRN version of the `suspect_score`  is powerful, as it represents the minimum and maximum suspect scores we captured from the identified device in the last 30 days **globally** across the entire Fingerprint device network.

The maximum value contains a zero-excluded percentile, that makes it easy to see how suspicious that device was compared to **other suspicious devices**. For example if the percentile of the maximum suspect score is 0.95, it means that device was more suspicious than 95% of **other suspicious devices** in the same 30-day time period.

**Output format** :

You can find the reference in this [API reference document](/reference/drn-api-get-by-visitor-id).

**Output example**:

```javascript theme={"theme":"github-dark-dimmed"}
"suspectScore": {
  // Time in RFC 3339 format, goes 30 days back from the time request received on the server in UTC
  "startDate": "2023-12-16T23:12:59Z",
  // The time the request was received on the server in UTC
  "endDate": "2024-01-16T23:12:59Z",
  // Minimum suspect score we captured globally for the identified Android device
  "minimum": {
    // Almost always will be zero, cannot be negative.
    // In rare cases will be > 0, 
    // when this device consistently generated a suspect score value greater than zero.
    // In this case, this device used a proxy all the time.
    "value": 3,
      // The signals object lists all the Smart Signals that contributed to the suspect score
      "signals": {
      "proxy": 3
    }
  },
  // Maximum suspect score we captured globally for the identified Android device
  "maximum": {
    // Most of the time will be 0, but sometimes will be > 0 for suspicious devices.
    // When you see a particularly high maximum value for a device, you need to review this device's activity
    "value": 20,
      // Zero-excluded percentile
      // E.g. a .75 value means the max suspect score is higher than 75% of
      // non-zero max suspect scores.
      // You can use this number to understand how high this max suspect score is
      // compared to other suspicious devices with non-zero maximum scores.
      // Can take four possible values: 0.25, 0.5, 0.75, and 0.95.
    "percentile": 0.75
      // The list of signals that contributed to the maximum captured suspect_score value.
      // Only the signal names with non-zero contribution will be used, together with their respective values.
      // Signal names and values are at the time of capturing the suspect score.
      // For a full reference for all possible values, see: /reference/server-api-get-event
    "signals": {
        // Nested Smart Signals can be used, compatible with the Server API response.
        "ipBlockList": 12,
          "vpn": {
          "publicVPN": 5
        },
        "proxy": 3
      }
  }
}
```

### timestamps

Represents timestamps when we first and last saw this device on the Fingerprint device network. Knowing when a device was first seen can be useful as the devices that appeared recently (a few minutes ago) are suspicious. Output format is described in the [API reference.](/reference/drn-api-get-by-visitor-id)

**Output example**:

```javascript theme={"theme":"github-dark-dimmed"}
"timestamps": {
  "firstSeenAt": "2023-12-29T23:12:00Z" // RFC3339 formatted UTC time with minute precision
  "lastSeenAt": "2023-12-29T23:12:00Z" // RFC3339 formatted UTC time with minute precision
}
```

### Payment dispute reporting

You can query the DRN for payment dispute information, associated with each Android device. This information is submitted by other companies, using the DRN.

Report  format:

```json json theme={"theme":"github-dark-dimmed"}
{
  "data": {
    "reports": [
      {
        "type": "card_dispute",
        "startDate": "2023-12-16T23:12:59Z",
        "endDate": "2024-12-16T23:12:59Z",
        "count": 20,
        "activityPercentile": .25 | .5 | .75 | .95,
        "amounts": [
          { "currency": "INR", "avgAmount": 270.15 },
          { "currency": "AED", "avgAmount": 650.19 },
          {"currency": "USD", "avgAmount": 45.6 },
        ]
      }
    ]
  }
}
```

To access the DRN payment dispute report API, please submit your inquiry to [drn@fingerprint.com](mailto:drn@fingerprint.com)

## Smart Signal aggregation notes

When you use the DRN API, you will always use the device's visitor ID value to query the network. Sometimes a device is only identified by Fingerprint through your workspace, and sometimes a device is identified by Fingerprint through multiple workspaces that belong to multiple companies.

### Multiple companies

When multiple companies use Fingerprint API to identify a device, DRN will aggregate the data from multiple companies' data sets. For example, if Company A identified a device on 2023-01-01, and Company B identified the same device on 2024-01-01, the information from both Smart Signals will be available, but the aggregations will go only 30 days back.

### Single company

If only one company identifies a device, the data will be aggregated only from that single company data set.


# Google Tag Manager
Source: https://docs.fingerprint.com/docs/fingerprintjs-pro-google-tag-manager



[The Fingerprint Google Tag Manager integration](https://github.com/fingerprintjs/gtm-integration) is an open-source [tag template][template-link] you can manually import into [Google Tag Manager](https://support.google.com/tagmanager/answer/6102821). It allows you to add and manage the Fingerprint [JavaScript agent](/reference/js-agent) on your website without changing the website code or redeploying it.

* Supports all standard functionality of the JavaScript agent.
* Pushes data to the [GTM's data layer](https://developers.google.com/tag-platform/tag-manager/web/datalayer) which can be processed by other tags or by JavaScript code on your website.

<Warning>
  **Note: Google Analytics does not allow using browser fingerprints**

  The Google Analytics terms of service contain a [policy against using browser fingerprints](https://support.google.com/analytics/answer/9682282?hl=en\&ref_topic=2919631\&sjid=9027453856798034060-EU):

  *"You must not use device fingerprints or locally shared objects (e.g. Flash cookies, Browser Helper Objects, HTML5 local storage) other than HTTP cookies, or user-resettable device identifiers designed for use in measurement or advertising, in connection with Google Analytics."*

  Breaching the policy can lead to [suspending or terminating your access to Google services](https://policies.google.com/terms?hl=en-US#toc-problems). You can use the visitor ID provided by Fingerprint in other 3rd party tags and tools, but we advise against using it inside Google Analytics.
</Warning>

Assuming you have already [signed up for Fingerprint](https://dashboard.fingerprint.com/signup/) and your website already has Google Tag Manager [installed](https://developers.google.com/tag-platform/tag-manager/web), here is how to add a Fingerprint tag:

## 1. Import the Fingerprint GTM template

You can install the template manually from the integration's [GitHub repository][template-link].

1. [Download the template][template-link] and make sure it is saved as `template.tpl` not `template.tpl.txt`.
2. Open the Google Tag Manager workspace of your website.
3. Go to **Templates** and click **New** to create a new template.
4. To [import](https://developers.google.com/tag-platform/tag-manager/templates#export_and_import) the template, click the **More actions (⋮)** button in the top right corner, select **Import** and pick the downloaded `template.tpl` file.
5. Click **Save**.

## 2. Add a Fingerprint tag to your website

1. Go to **Tags** and click **New** to create a new tag.
2. Click **Choose a tag type** and under **Custom**, pick your imported **Fingerprint** template.
3. Configure the tag:
   1. Choose your **Tag type**.  **Start and Identify** loads the script and identifies the visitor right after the tag is triggered. This is the recommended option if you want to identify visitors on page initialization.
      > Note: If you want to identify visitors after an event (e.g. form submission) with minimum latency, you might want to separate starting the JavaScript agent from the identification request. In that case, you can create two separate Fingerprint tags:
      >
      > * First, with tag type **Start**, which is triggered on page initialization.
      > * Second, with tag type **Identify** which is triggered by another event. You can create your own [custom event trigger](https://support.google.com/tagmanager/answer/7679219?hl=en) and then fire it from a 3rd party tag or from your JavaScript code: `dataLayer.push({'event': 'identifyVisitor'});`
   2. Enter your [`public API key`](/reference/js-agent-start-function#apikey) and [`region`](/reference/js-agent-start-function#region).
   3. In the **Additional fields** section, you can optionally configure the [`endpoints`](/reference/js-agent-start-function#endpoints), [`tags`](/reference/js-agent-get-function#tags), [`linkedId`](/reference/js-agent-get-function#linkedid). You can change **Result custom name** to change the name of the `result` object in the *dataLayer*.
      <img alt="screenshot of tag configuration" />
4. In the **Triggering** section, add a new trigger, for example:  **Initialization**.\\
   <img alt="screenshot of trigger section" />
5. Click **Save** to save your tag.
6. Click **Submit** and publish your workspace changes to your website.

If the tag is configured correctly, you will see identification events on your [Fingerprint dashboard](https://dashboard.fingerprint.com/).

## Using the Fingerprint result in custom JavaScript code

Fingerprint data can be accessed through the GTM's [`dataLayer`](https://developers.google.com/tag-platform/tag-manager/web/datalayer) API in your JavaScript code. It's important to check if the result data (specified by *Result custom name*) is already present in the data layer.

```javascript theme={"theme":"github-dark-dimmed"}
window.dataLayer.push(function () {
  if (this.get("FingerprintResult")) { // Make sure the page has already received result data
    const result = this.get("FingerprintResult");
    console.log(JSON.stringify(result)); // Use Fingerprint result
  }
});
```

## Using the Fingerprint result in a custom variable

You can expose every property of the [`result`](/reference/js-agent-get-function#get-response-fields) object as a [user-defined variable](https://support.google.com/tagmanager/answer/7683362?hl=en) and use it in the configuration fields of other tags. For example, you can reference the [`visitor_id`](/reference/js-agent-get-function#visitor_id) as a variable in another tag.

1. Inside Google Tag Manager, go to **Variables**, and click **New** to create a new user-defined variable.

2. Select the **Data Layer Variable** type.

3. Name your variable, for example `VisitorID`.

4. Set **Data Layer Variable Name** to `FingerprintResult.visitor_id`. The data layer properties format follows the [result format](/reference/js-agent-get-function#get-response-fields) provided by the JavaScript agent.

5. Click **Save** to create the variable.

<img alt="screenshot of variable configuration" />

Now you can use the `{{VisitorID}}` variable in the configuration of 3rd party tags within your container. However, the tags need to wait for the Fingerprint `result` data:

1. Add a new Trigger to the 3rd party tag.
2. In the tag's configuration, add a new *Firing Trigger*, choose *Custom Event*, and enter `Fingerprint.identified`.

<img alt="screenshot of trigger configuration" />

For testing purposes, you can create a [Custom HTML tag](https://support.google.com/tagmanager/answer/6107167?hl=en#) to log the variable to the console:

```html theme={"theme":"github-dark-dimmed"}
<script>
  console.log({{VisitorID}}) // You can use the variable inside the configuration of any tag
</script>
```

## Code and documentation

You can find the [code and technical documentation](https://github.com/fingerprintjs/gtm-integration) in the official GitHub repository.

## Limitations

* Some advanced JavaScript agent properties ([`storageKeyPrefix`](/reference/js-agent-start-function#storagekeyprefix), [`urlHashing`](/reference/js-agent-start-function#urlhashing), [`cache`](/reference/js-agent-start-function#cache)) are not currently supported.  If you need to use these features, please contact [support](mailto:support@fingerprintjs.com).
* Ad-blocking browser extensions such as AdBlock, uBlock Origin, etc., can block all scripts served by Google Tag Manager, including Fingerprint. If this is a problem for your use case, see Google Tag Manager documentation for [Server-side tagging](https://developers.google.com/tag-platform/tag-manager/server-side) and [Custom domain configuration](https://developers.google.com/tag-platform/tag-manager/server-side/custom-domain).

## Migration guide for Google Tag Manager integration v2.0.0

Version 2.0.0 of the Google Tag Manager integration switches from JavaScript agent v3 to [JavaScript agent v4](/reference/migrating-from-v3-to-v4).
To migrate to version 2.0.0 from version 1.1.0 and earlier, you will need to:

1. Update your JavaScript code using the Fingerprint result
2. Update your Fingerprint tags to use the new [tag template][template-link]
3. Update user-defined variables referencing the Fingerprint result
4. Update triggers using Fingerprint custom events
5. Preview, test, and publish your changes

### 1. Update your JavaScript code using the Fingerprint result

If you have JavaScript code that is accessing the `FingerprintJSProResult`, you will need to update that code to use the new [`dataLayer`](https://developers.google.com/tag-platform/tag-manager/web/datalayer) result variable, named `FingerprintResult` by default.
Refer to the [JavaScript agent v4 reference](/reference/js-agent-get-function#get-response-fields) for the result format provided by the JavaScript agent.

To allow your JavaScript code to be updated before the new tags are created and published, you can support both agent v3 results and agent v4 results with the same code, using an approach similar to the code below:

```javascript theme={"theme":"github-dark-dimmed"}
window.dataLayer.push(function () {
  if (this.get("FingerprintJSProResult")) {
    const v3Result = this.get("FingerprintJSProResult");
    console.log(v3Result.visitorId); // Use Fingerprint result
// [!code ++]
  } else if (this.get("FingerprintResult")) {
    const v4Result = this.get("FingerprintResult");// [!code ++]
    console.log(v4Result.visitor_id);// [!code ++]
  }
});
```

### 2. Update your Fingerprint tags to use the new tag template

First, follow the steps in the [Import the Fingerprint GTM template](#1-import-the-fingerprint-gtm-template) section to create the tag type for the version 2.0.0 Fingerprint tag.
The default name for the custom tag type, `Fingerprint`, differs from previous versions to avoid conflicts.

Next, update your tags by opening each tag for editing, taking note of the tags current parameter values, and then changing the tag type from the previous version, named `Fingerprint Pro` by default, to the new `Fingerprint` tag type.
Changing the tag type will reset the tag to its default state, and the parameter values you noted will need to be re-entered.

As you update your tags, you'll need to account for the following changes to the tag type's parameters:

* The `Tag type` parameter's values have changed from `Load and identify` and `Load` to `Start and identify` and `Start`, respectively.
* The `Script Url Pattern` and `Endpoint` parameters have been replaced by the `Endpoints` list. If you are using a custom subdomain or proxy integration, add an item to the `Endpoints` list with the endpoint URL for the integration.
* The `Extended result` parameter is no longer needed and has been removed.
* The default value for the `Result custom name` has changed from `FingerprintJSProResult` to `FingerprintResult`.
  If the downstream usages of the result are not referencing individual properties, you might choose to use the previous `FingerprintJSProResult` name to limit the number of downstream updates you need to make.

After entering the parameter values, click **Save** to save your changes to the tag.
In step 5, you'll preview and test your changes before publishing to ensure a seamless migration to the new version without downtime.

### 3. Update user-defined variables referencing the Fingerprint result

Because the Fingerprint result format has changed with the migration to JavaScript agent v4, you will need to update each data layer variable that references the Fingerprint result values.

To update a variable, select the variable and edit the **Data Layer Variable Name** to use the new name for the value from the Fingerprint result.

When updating the data layer variable, take into account the value of the `Result custom name` parameter defined on the tag in the previous step. It defaults to `FingerprintResult` in version 2.0.0.

### 4. Update triggers using Fingerprint custom events

You will need to update triggers using custom events published by the Fingerprint tag, to account for changes to the names of these events in version 2.0.0.

Use the following mapping when updating your triggers:

| Previous event name        | 2.0.0 event name         |
| -------------------------- | ------------------------ |
| `FingerprintJS.loaded`     | `Fingerprint.started`    |
| `FingerprintJS.identified` | `Fingerprint.identified` |

### 5. Preview, test, and publish your changes

After creating the new tags and updating data layer variables to use JavaScript agent v4, use [Google Tag Manager Preview Mode](https://support.google.com/tagmanager/answer/6107056?hl=en) to test your changes before publishing.

Once you are satisfied with your changes, click **Publish** from the main workspace page to complete the migration.

[template-link]: https://github.com/fingerprintjs/gtm-integration/releases/latest/download/template.tpl


# Get server side intelligence
Source: https://docs.fingerprint.com/docs/get-server-side-intelligence



Fingerprint client agents (for example, the [JavaScript agent](/reference/js-agent)) allow you to get the visitor ID on the client. However, client-side code can always be tampered with, so we recommend processing Fingerprint results securely on your server. Fingerprint also intentionally limits the information available in the [client response](/reference/js-agent-get-function#get-response). Information related to fraud protection like [Smart Signals](/docs/smart-signals-introduction) is only available on the server.

Fingerprint offers three methods for getting device intelligence to your server:

* [Sealed Client results](#sealed-client-results) (real-time processing)
* [Events API](#events-api) (near real-time processing)
* [Webhooks](#webhooks) (asynchronous processing)

All methods provide the same information but have different trade-offs in latency and implementation complexity. Read below to choose the best method for your use case.

<Note>
  **Server integrations are free**

  Getting device intelligence to your server is *free*. Querying for an event through our APIs or receiving a webhook does not come at any additional cost.
</Note>

## Sealed Client Results

If your application needs to make a decision or take action as soon as Fingerprint results are available, your best option is to use [Sealed Client Results](/docs/sealed-client-results).

* Using this method, Fingerprint sends the full encrypted payload to the client.
* The encryption ensures that it cannot be altered by malicious actors.
* Your client forwards the payload to your server where you can decrypt and process it without any additional API calls.

Compared to the [Events API](/reference/server-api-get-event), integrating Sealed Client Results involves additional steps like creating and managing decryption keys. But if you want to get the best end-to-end performance, they should be your first choice.

## Events API

A simpler alternative for real-time processing is to use our [Server API](/reference/server-api).

* Using this method, your client sends the  `event_id` from the Fingerprint client agent to your server.
* On the server, you can use the Server API  [`/v4/events/:event_id`](/reference/server-api-get-event)  endpoint to get the full device intelligence result.

Compared to [Sealed Client Results](/docs/sealed-client-results), this setup requires one additional API call which might translate into higher latency.

## Webhooks

If real-time processing is not required, we offer [Webhooks](/docs/webhooks) to send the device intelligence results to you automatically and asynchronously.

* Using this method, you give Fingerprint a URL of your server endpoint for processing webhooks.
* For every identified visitor, Fingerprint will send the full device intelligence result to your server endpoint.

Typical applications of Webhooks include storing a copy of every result for further processing or increasing security through the [Zero Trust Mode](/docs/zero-trust-mode).

## Protecting from tampering and replay attacks

None of the mechanisms above protect from replay attacks. It's up to you to implement it separately on your backend.

See [Protecting from client-side tampering and replay attacks](/docs/protecting-from-client-side-tampering) to learn about additional security measures you can take to protect your Fingerprint implementation.

## Multiple environments

If you use multiple environments to separate your Fingerprint setup for different domains or apps, you might want to get events to your server also separated by environments - in case you have different servers processing events for different environments.

All methods mentioned above (Sealed Client Results, Events API, Webhooks) fully support multiple environments.

* You can issue a dedicated **Encryption key** per environment, enabling Sealed Client Results only on selected environments.
* **Secret keys** used to authenticate with Server API can be scoped to environment, making `/v4/events` endpoints returning only events associated with the same environment.
* When creating **webhooks**, you can scope them to an environment, making the webhook send only events associated with the same environment.

See the guide on [multiple environments](/docs/multiple-environments) to learn how to set up environment-scoped resources.


# Glossary
Source: https://docs.fingerprint.com/docs/glossary



## Android agent

A native Android SDK that collects multiple device signals and sends them to the Identification API for processing and identification.

## BotD

BotD is an open-source [library](https://github.com/fingerprintjs/botd) that we created to make it easy for every developer to detect basic bots in their web apps. BotD is available under a permissive MIT license and will always be free for developers.

## Bot Detection

Fingerprint Bot Detection is a production-grade bot detection API product that detects automated activity on your website. This product can detect a wide range of bots, headless browsers, and automation tools — and distinguish bad bots from useful ones, for example, search engine crawlers.

## Fingerprinting

The process of generating a unique and stable identifier of a browser or a device from a combination of its software and hardware attributes. On the web, Fingerprint Identification issues a visitor identifier tied to the browser. On Android and iOS, the identifier is tied to the visitor’s device.

## FingerprintJS

FingerprintJS is an open-source client-side browser fingerprinting library available on GitHub. This library uses only browser-related attributes to generate a fingerprint; hence, it has a lower accuracy than Fingerprint Identification. See how [FingerprintJS differs from Fingerprint Identification](https://fingerprint.com/github).

## Fingerprint Workspace

A Fingerprint workspace represents a project that uses the Fingerprint client agent (for example, the [JavaScript agent](/reference/js-agent)) to identify browsers and devices. The Fingerprint workspace may contain one or more web apps and/or mobile apps.

* Every Fingerprint workspace contains a unique set of API keys that the project can use to identify a device or to make requests to the [Server API](/reference/server-api).
* Identification of browsers is scoped to a Fingerprint Workspace. When a browser visits any web app within that Fingerprint workspace, it will receive the same visitor ID. On the other hand, when a browser visits two different web apps that belong to two different Fingerprint workspaces, it will receive two different visitor IDs.
* From your Fingerprint account, you can create multiple Fingerprint workspaces. You can use the API keys of a single Fingerprint workspace to identify visitors on multiple websites or mobile apps.

## Fingerprint Identification

Fingerprint Identification is a commercial device identification platform designed for fraud detection, user identification, marketing attribution, and analytics. Compared to FingerprintJS, it has [numerous advantages](https://fingerprint.com/github).

## Identification API

A part of our platform that is responsible for identifying devices or browsers. It performs the analysis of your visitors that you can later query using Server API. It is used by our JavaScript and Native agents. Requests count towards your plan billing.

## Incognito mode

Incognito or private browsing is a privacy feature in some web browsers. When operating in such a mode, the browser creates a temporary session that is isolated from the browser's main session and user data.

## iOS Agent

A native iOS SDK that collects multiple device signals and sends them to the Identification API for processing and identification.

## JavaScript agent

The client-side agent is a high-performance JavaScript agent that collects multiple device and browser signals and sends them to the Identification API for processing, identification, and bot detection.

## Fingerprint Plans

The Fingerprint Platform consists of three plans: [Pro Plus and Enterprise](https://fingerprint.com/pricing/?utm_source=/docs/quick-start-guide).

> Check out our [Pricing & Packaging](https://fingerprint.com/pricing/) to learn which plan is best for your needs.

## Proxy cloud integration

The practice of routing Identification API and agent-download requests through a proxy on a specific cloud provider. Direct requests to Identification API and our CDN can be blocked by browsers and privacy extensions. Using a proxy cloud integration, the requests are considered "same-site", greatly increasing identification accuracy.

## Proxy Secret

A Proxy Pre-Shared Secret is a secret key used to authenticate with third-party integrations. For example, when using a [CloudFront](/docs/cloudfront-proxy-integration-v2) proxy integration, you use this key in your AWS configuration. You can find and manage your secret API keys in the Dashboard -> API Keys.

## Public API Key

The public API key associated with your workspace. Use this API key to load the JavaScript or mobile agent and make requests to Identification API. You can manage your public API keys in the Dashboard -> API Keys. The key is exposed to the public as it must be used in the client-side code of your website. To prevent its misuse, you can use [Request filtering](/docs/request-filtering) to only allow Fingerprint Identification API requests from your website's origin.

## Regions

Fingerprint Identification is available in the following regions: Global (US), EU, and Asia. Usually, you should select the region from which most of your site traffic originates.

## Request Filtering

A Fingerprint Identification feature that allows you to filter out unwanted visitor identification requests by origin or HTTP headers. This can prevent bad actors from misusing your public API key and making requests to the Identification API using your account.

## event\_id

Unique identifier for every request made to our API by our JavaScript or native agent. It is usually used in further server-side event processing, using our Server API.

## requestId

Old name for `event_id`, used with the previous version of Fingerprint APIs.

## Secret API Key

The secret API key associated with your workspace. Use this API key to make requests to the [Server API](/reference/server-api). Do not expose this key to the public, only call the Server API from the server-side code. You can find and manage your secret API keys in the Dashboard -> API Keys.

## Server API

Fingerprint Platform Server API allows you to get information about visitors and individual events in a server environment. This API can be used for data exports, decision-making, and data analysis scenarios. Requests do not count towards your plan billing.

## Subdomain setup

The practice of routing Identification API requests through a proxy on the site’s subdomain. Direct requests to Identification API can be blocked by browsers and privacy extensions. Using a subdomain proxy, the requests are considered “same-site”, greatly increasing identification accuracy. Using some form of subdomain proxy is required for correct identification when using Fingerprint.

## Webhooks

A webhook is when Fingerprint makes an HTTP POST request to your application’s API when a visitor identification event occurs. It is an alternative to actively requesting data from the Server API. Webhooks are asynchronous and don't incur performance overhead when enabled.

## visitor\_id

Unique and stable identifier calculated by the Fingerprint Identification product. When Fingerprint Identification is used in browsers through one of our JavaScript libraries, it identifies the specific browser environment. In the native mobile contexts (iOS and Android), this identifier is scoped to the device.

## Zero Trust mode

Mode of running the identification without exposing the visitor ID to the visitor. Instead, you get back a random event ID value that you can use later to read the actual visitor ID using our Server API. Zero Trust Mode is implemented internally by identification result hiding and strict origin-checking features.


# Identification using pseudonymized IP Address
Source: https://docs.fingerprint.com/docs/identification-using-pseudonymized-ip-address



The originating event's IP address is an important signal that Fingerprint Identification relies upon to accurately identify browsers and mobile devices. Normally, Fingerprint Identification stores the IP address as plain text and uses it in its identification algorithms.

Several regulatory frameworks (e.g. [GDPR](https://gdpr-info.eu/), US Privacy Laws, including [CCPA](https://oag.ca.gov/privacy/ccpa)) have classified IP addresses as Personally Identifiable Information (PII). When you use Fingerprint Identification for purposes with a [legitimate interest](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/legal-grounds-processing-data_en#legitimate-interests-of-the-controller:~:text=A%20company/organisation%20may,of%20its%20IT%20systems.), these frameworks allow you to store these IP addresses (PII) as plain text.

On the other hand, if you use Fingerprint Identification for purposes that do not fall under *legitimate interest*, then these frameworks recommend using [pseudonymized](https://en.wikipedia.org/wiki/Pseudonymization) IP addresses as an alternative to comply with regulations.

Accordingly, we have introduced a new form of Identification that uses pseudonymized IP addresses. In this approach, the original IP address is combined with other metadata and then cryptographically transformed into an unrecognizable, binary value after which it is used by our identification algorithms. It is impossible to retrieve the original IP address from this unrecognizable binary value.

Identification using pseudonymized IP addresses is a worthwhile alternative to experience the core capabilities of the Fingerprint Device Intelligence platform without compromising on identification accuracy and regulatory compliance.

## Identification using regular IP address vs. pseudonymized IP address

Several features in Fingerprint’s Device Intelligence platform that rely on the IP address being available in plain text will not be available when using a pseudonymized IP address. For example, IP Geolocation and several Smart Signals (e.g. `vpn`, `ipInfo`) will not be available. The table below outlines the differences between the two approaches:

| Feature                                                                                                                                                       | Identification using regular IP address | Identification using pseudonymized IP address                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How is the IP address stored?                                                                                                                                 | It is stored as plain text.             | It is combined with other metadata, transformed into an unrecognizable binary value, and then stored.                                                                                                                                                                                                                                                                                                                                                                          |
| Can the original IP address be retrieved?                                                                                                                     | Yes, in identifiable clear text.        | **No**. It is impossible to retrieve the original IP address from the binary value.                                                                                                                                                                                                                                                                                                                                                                                            |
| How does the IP address appear in responses to JavaScript agent / SDK requests, [Server API ](/reference/server-api)requests, and [Webhooks](/docs/webhooks)? | Original, unmodified IP address.        | **0.0.0.0**                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Is [IP Geolocation](/docs/smart-signals-reference#ip-geolocation) available in responses?                                                                     | Yes                                     | **No**                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Are all [Smart Signals](/docs/smart-signals-reference) available?                                                                                             | Yes                                     | **No**. [Browser Bot Detection](/docs/smart-signals-reference#browser-bot-detection), [IP Geolocation](/docs/smart-signals-reference#ip-geolocation), [IP Blocklist Matching](/docs/smart-signals-reference#ip-blocklist-matching), [Proxy Detection](/docs/smart-signals-reference#proxy-detection), [Velocity Signals](/docs/smart-signals-reference#velocity-signals), and [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-browsers) will not be available. |

## Enabling pseudonymized IP addresses for your workspace

When pseudonymized IP addresses are enabled for your workspace:

* You can continue to use the same workspace.
* Your users will continue to be identified using the same visitor ID as before.
* Identification accuracy, when compared to standard identification, can be slightly lower.

If you would like to try this feature for your workspace, please [contact our support team](https://fingerprint.com/support/).


# Identifying in-app browsers for iOS
Source: https://docs.fingerprint.com/docs/identifying-in-app-browsers-for-ios



An in-app browser is a browser that is “embedded” within a mobile app. It allows your iOS app to display web content without requiring your app to open a separate browser.

For iOS, in-app browsers are typically implemented using one of the following:

1. [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview)
2. [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller)
3. [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)

This article will help you understand how

* Fingerprint identifies each of these in-app browsers
* Fingerprint Identification can be influenced by the different options available to configure these in-app browsers

# In-app browsers at a glance

1. **WKWebView**
   1. You can configure it with either a
      1. [Default data store](https://developer.apple.com/documentation/webkit/wkwebsitedatastore/1532937-default) that allows you to save website data to a disk. (OR)
      2. [Non-persistent data store](https://developer.apple.com/documentation/webkit/wkwebsitedatastore/1532934-nonpersistent) that allows you to save the website data to memory. Typically, private browsing sessions are implemented using this type of data store.
   2. It does not share website data and sessions with Safari.
2. **SFSafariViewController**
   1. Unlike WKWebView, there aren’t any options for configuring the data store.
   2. It does not share website data and sessions with Safari.
3. **ASWebAuthenticationSession**
   1. You can request to share cookies and other browsing data from this session with the user’s default browser. See [`prefersEphemeralWebBrowserSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession/3237231-prefersephemeralwebbrowsersessio) to learn more.

# Fingerprint Identification across in-app and web browsers

The three listed in-app browsers do not share cookies and website data. Fingerprint can still generate the same visitor ID using alternate identification methods that do not rely on cookies and website data (aka *probabilistic identification*) for a few combinations where cookies and website data are unavailable.

In this section, we will enumerate several scenarios to help you understand the cases where Fingerprint Identification will produce the same visitor ID and those where it will not.

## Scenario 1: In-app browsers vs. web browsers

If you would like to identify your users across your app and your website, here are a few things to remember:

* The visitor ID generated for a WKWebView, irrespective of how its data store is configured, is **different** from the visitor ID generated for your web browser.
* SFSafariViewController does not share cookies and website data with the Safari browser. Even then, Fingerprint in most cases will be able to generate the same visitor ID for these two browsers.
* An ephemeral ASWebAuthenticationSession or a WKWebview session configured with a non-persistent data store is always treated as a private browsing session. Such in-app browser sessions can only be *probabilistically* identified.

### Cheat sheet

* The header column represents the various in-app browsers.
* The header row represents a few of the web browsers. Let’s assume Safari is the user’s default web browser.
* ✅ indicates that the visitor ID remains the same between the specified in-app browser and the web browser.
* ❌ indicates that the visitor ID is different between the specified in-app browser and the web browser.

<img alt="" />

## Scenario 2: Your app launches several types of in-app browsers

In general,

* If your app uses the **same type of in-app browser** (e.g. `ASWebAuthenticationSession`) in two different places, then irrespective of how they are configured, Fingerprint will be able to generate the same visitor ID for both these browsers.
* The visitor ID generated for a `WKWebView` will always be different from the visitor ID generated for the other in-app browsers.

The cheat sheet below will serve as a good reference for how the different configurations that you use to create these in-app browsers can influence Fingerprint Identification.

### Cheat sheet

* The header column represents cases where the specified in-app browser is a first-time browser.
* The header row represents cases where the specified in-app browser is a returning browser.
* ✅ indicates that the returning in-app browser was given the same visitor ID as the first-time browser.
* ❌ indicates that the returning in-app browser was given a visitor ID different from that of the first-time browser.

<img alt="" />

## Scenario 3:  Your SDK launches several types of in-app browsers

If you implement several types of these in-app browsers in your SDK, the cheat sheet below will help you understand the different combinations of in-app browsers that will yield the same visitor ID across different apps.

### Cheat sheet

* The header column represents cases where the specified in-app browser is launched from App A.
* The header row represents cases where the specified in-app browser is launched from App B.
* ✅ indicates that the visitor ID remains the same between the specified in-app browsers across apps A and B.
* ❌ indicates that the visitor ID is different between the specified in-app browsers across apps A and B.

<img alt="" />


# Identifying users in hybrid app frameworks
Source: https://docs.fingerprint.com/docs/identifying-users-in-hybrid-app-frameworks



## User identification in Capacitor, Cordova, PhoneGap, and other hybrid app frameworks

Fingerprint was designed for fraud detection in the browser, but Fingerprint Identification can also accurately identify users in apps built with Adobe PhoneGap, Ionic Capacitor, Apache Cordova, and other hybrid app development frameworks.

## How to Install Fingerprint on a Hybrid App

**1** - Sign up for a [free trial](https://dashboard.fingerprint.com/signup/), or [log in](https://dashboard.fingerprint.com/login/) to your Fingerprint account if you have one.\
**2** - Follow the directions on our [quick start guide](/docs/quick-start-guide) to install our Javascript agent using the NPM package method but NOT the CDN method. The agent needs to be added to your JavaScript, not to an HTML page.\
**3** - Copy/paste this terminal command to add our NPM package to your project:

```shell theme={"theme":"github-dark-dimmed"}
npm install @fingerprint/agent
```

If you use Yarn it will look like this:

```shell theme={"theme":"github-dark-dimmed"}
yarn add @fingerprint/agent
```

**4** - Add the JavaScript agent code to your JavaScript codebase. It will pull identification signals from your app’s web view interface:

<CodeGroup>
  ```javascript ECMAScript theme={"theme":"github-dark-dimmed"}
  import Fingerprint from '@fingerprint/agent'

  const fp = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' })

  // When you need the visitor identifier:
  fp.get()
    .then(result => console.log(result.visitor_id))
  ```

  ```javascript CommonJS theme={"theme":"github-dark-dimmed"}
  const Fingerprint = require('@fingerprint/agent')

  const fp = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' })

  // When you need the visitor identifier:
  fp.get()
    .then(result => console.log(result.visitor_id))
  ```
</CodeGroup>

Note that you should replace `PUBLIC_API_KEY` with the alphanumeric public API key code from your customer dashboard:

<img alt="Screenshot of where to find your Public API keys" />

**5** - Continue the quick start guide instructions for the Custom subdomain, webhooks, server API queries, and tagging requests. There are no special considerations for enabling these features in hybrid apps.

## Fingerprint Identification features that are compatible with hybrid apps

Apps that work through hybrid environments use web views, which are similar to browsers in that they use HTML, CSS, and JavaScript to show content and controls to the user. The Fingerprint JavaScript agent can collect enough attributes through web views for us to create a visitor ID. Most Fingerprint functions, like webhooks and geolocation, work as expected in this environment.

## Other considerations

* If one of your API keys is stolen, [request filtering](/docs/request-filtering) cannot stop a thief from using that API key on their own app. This is because our filtering system checks requests against a blocklist of suspect origins or a limited safelist of acceptable origins, and the default origin in many hybrid app web views is "localhost." So from our perspective, all requests look like they’re coming from the same origin. We also filter HTTP headers using specified rules, but like origins, the headers of different web views look the same, so the rules aren’t effective. A developer can change the web view origin or header, but then the thief can do the same. If you suspect your API key was stolen, reach out to [our support team](https://fingerprint.com/support/).
* Fingerprint Identification needs an internet connection to create and match visitor IDs. We cannot store information while the device is offline and send it to our server when the device turns the Internet back on.
* The app’s webview and the device’s browser are separate environments. In cases where the web view and browser share many attributes, our system can assign a single visitorID to both environments, but we cannot guarantee a consistent match.

## Compliance and support

Fingerprint is fully compliant with GDPR and US Privacy Laws (including CCPA) when used to detect and prevent fraud.

For specific questions about how Fingerprint could work for your hybrid app, reach out to [our support team](https://fingerprint.com/support/).


# iOS SDK Changelog
Source: https://docs.fingerprint.com/docs/ios-sdk-changelog





# Management API
Source: https://docs.fingerprint.com/docs/management-api





# Matomo / Piwik
Source: https://docs.fingerprint.com/docs/matomo-piwik

Learn how to use Matomo (formerly Piwik) with Fingerprint to identify visitors.

### Why use Matomo with Fingerprint

Matomo uses cookies to identify visitors. When cookies are not available or visitors use incognito mode, Matomo will create multiple visitors for one actual visitor. Depending on your website traffic, this can pose a significant issue as it will incorrectly count your visitors.

Fingerprint makes it easy to identify your website visitors with Matomo by linking them to the Fingerprint's `visitorID` value.

Matomo has a limitation, which doesn't allow to replace their cookie-based identifier, but it has a `userID` [functionality](https://matomo.org/docs/user-id/), that can be used to link Matomo visitors with Fingerprint visitors.

To do this, you would need to use a slightly different configuration for Matomo [JavaScript tracking client](https://developer.matomo.org/guides/tracking-javascript-guide).

### Configuration

Here is a full working example that will link Fingerprint's visitorID with Matomo visitorID using userID functionality:

```ts HTML theme={"theme":"github-dark-dimmed"}
<head>
  <script>
  // This is the Matomo tracking client JavaScript snippet
  // with two modifications, wrapped in a function.
  // (the rest of the configuration is the default one)
  var initMatomo = function (fpjsVisitorId) {
    var _paq = window._paq || [];
    // Modification #1 (one new line).
    // Note, how we set the userID with "setUserId" configuration here
    _paq.push(['setUserId', fpjsVisitorId]);
    _paq.push(['trackPageView']);
    _paq.push(['enableLinkTracking']);
    // Modification #2 (one new line).
    // An important step is to attach the _paq to "window". 
    // Otherwise, the Matomo client will not find this "_paq" array.
    window._paq = _paq;
    (function () {
      var u = "https://your.matomo.cloud/";
      _paq.push(['setTrackerUrl', u + 'matomo.php']);
      _paq.push(['setSiteId', '1']);
      var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
      g.type = 'text/javascript'; g.async = true; g.defer = true; g.src = '//cdn.matomo.cloud/your.matomo.cloud/matomo.js'; s.parentNode.insertBefore(g, s);
    })();
  }

  // Now, the Fingerprint configuration
  import('https://fpjscdn.net/v4/PUBLIC_API_KEY')
    .then(Fingerprint => Fingerprint.start())
    .then(fp => fp.get())
    .then(result => initMatomo(result.visitor_id))
    .catch(error => {
      // use your favorite error reporting tool
      reportError(error);
    })
    .finally(function () {
      // optional
      // do some guaranteed post-processing here
    });
  </script>
</head>
```

After you have configured it, you will start seeing UserID values in Matomo dashboard:

<img alt="Screenshot of a correctly configured Matomo instance with token" />

It's also possible to add additional information from Fingerprint to Matomo visits, such as incognito mode detection.


# Migrating from FingerprintJS to Fingerprint
Source: https://docs.fingerprint.com/docs/migrating-from-fingerprintjs-to-fingerprint-pro



To migrate your implementation from FingerprintJS to Fingerprint Identification:

1. Determine your FingerprintJS version if you are not sure.
2. Follow the migration instructions below specific to your version.

## Determine your FingerprintJS version

### NPM installation

If you installed FingerprintJS using `npm`, then your application's `package.json` will include an entry for either `@fingerprintjs/fingerprintjs` or `@fingerprintjs/fingerprintjs2` along with the exact version that is being used.

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  "dependencies": {
    "@fingerprintjs/fingerprintjs": "^x.y.z"
  }
  ```
</CodeGroup>

### CDN installation

If your application loads FingerprintJS using CDN, then the path specified in `script` or `import` will contain the version of FingerprintJS that is being used.

#### FingerprintJS v2.x

If the path in the script tag includes `/fingerprintjs2@2/`, then your application uses FingerprintJS v2.x.

<CodeGroup>
  ```html CDN theme={"theme":"github-dark-dimmed"}
  <script src="https://cdn.jsdelivr.net/npm/fingerprintjs2@2/dist/fingerprint2.min.js"></script>
  ```
</CodeGroup>

#### FingerprintJS v3.x and higher

The path segment `/vN/` in `script` or `import` statements indicates the version of FingerprintJS that is being used. In the below example, the version used is **v5**.

<CodeGroup>
  ```js CDN (v5) theme={"theme":"github-dark-dimmed"}
  const fpPromise = import('https://openfpcdn.io/fingerprintjs/v5');
  ```

  ```js CDN (v4) theme={"theme":"github-dark-dimmed"}
  const fpPromise = import('https://openfpcdn.io/fingerprintjs/v4');
  ```

  ```js CDN (v3 variant 1) theme={"theme":"github-dark-dimmed"}
  script.src = 'https://openfpcdn.io/fingerprintjs/v3/iife.min.js';
  ```

  ```html CDN (v3 variant 2) theme={"theme":"github-dark-dimmed"}
  <script src="https://openfpcdn.io/fingerprintjs/v3/iife.min.js"></script>
  ```
</CodeGroup>

## Migrating from FingerprintJS v5 and above (open-source) to Fingerprint Identification

You can migrate from [FingerprintJS v5 and above](https://github.com/fingerprintjs/fingerprintjs) to Fingerprint Identification in 30 seconds:

1. Sign up on [dashboard.fingerprint.com/signup](https://dashboard.fingerprint.com/signup), create an account, and get your [Public API key](https://dashboard.fingerprint.com/api-keys?type=browser).
2. In your `package.json` or `import` statement, change the `@fingerprintjs/fingerprintjs` package to `@fingerprint/agent`:

<CodeGroup>
  ```diff NPM theme={"theme":"github-dark-dimmed"}
  Run:
  npm uninstall @fingerprintjs/fingerprintjs
  npm install @fingerprint/agent

  And replace the package name in your JavaScript/TypeScript code:
  - import FingerprintJS from '@fingerprintjs/fingerprintjs'
  + import Fingerprint from '@fingerprint/agent'
  ```

  ```diff Yarn theme={"theme":"github-dark-dimmed"}
  Run:
  yarn remove @fingerprintjs/fingerprintjs
  yarn add @fingerprint/agent

  And replace the package name in your JavaScript/TypeScript code:
  - import FingerprintJS from '@fingerprintjs/fingerprintjs'
  + import Fingerprint from '@fingerprint/agent'
  ```

  ```ts CDN theme={"theme":"github-dark-dimmed"}
  <script>
    const fpPromise = import('https://openfpcdn.io/fingerprintjs/v5') // [!code --]
    const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY') // [!code ++]
      .then(Fingerprint => Fingerprint.start())
      // ...
  </script>
  ```

  ```ts CDN (legacy variant 1) theme={"theme":"github-dark-dimmed"}
  <script>
  // Initialize the agent at application startup.
  const fpPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.onload = resolve;
    script.onerror = reject;
    script.async = true;
    script.src = 'https://openfpcdn.io/fingerprintjs/v5/iife.min.js'; // [!code --]
    script.src = 'https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js'; // [!code ++]
    document.head.appendChild(script);
  })
    .then(() => Fingerprint.start());
  // ...
  </script>
  ```

  ```ts CDN (legacy variant 2) theme={"theme":"github-dark-dimmed"}
  <!-- Change the script URL: -->
  <script src="https://openfpcdn.io/fingerprintjs/v5/iife.min.js"></script> // [!code --]
  <script src="https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js"></script> // [!code ++]
  <script>
    // ...
  </script>
  ```
</CodeGroup>

3. Add the public API key to the `Fingerprint.start()` configuration:

<CodeGroup>
  ```javascript NPM/Yarn theme={"theme":"github-dark-dimmed"}
  FingerprintJS.load() // [!code --]
  Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' }) // [!code ++]
  ```

  ```text CDN theme={"theme":"github-dark-dimmed"}
  Add your key to the agent script URL, for example:
  https://fpjscdn.net/v4/PUBLIC_API_KEY
  https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js
  ```
</CodeGroup>

That's it, you can now identify browsers with industry-leading accuracy.

## Migrating from FingerprintJS v4 (source-available) to Fingerprint Identification

You can migrate from [FingerprintJS v4](https://github.com/fingerprintjs/fingerprintjs/tree/v4) to Fingerprint Identification in 30 seconds:

1. Sign up on [dashboard.fingerprint.com/signup](https://dashboard.fingerprint.com/signup), create an account, and get your [Public API key](https://dashboard.fingerprint.com/api-keys?type=browser).
2. In your `package.json` or `import` statement, change the `@fingerprintjs/fingerprintjs` package to `@fingerprint/agent`:

<CodeGroup>
  ```diff NPM theme={"theme":"github-dark-dimmed"}
  Run:
  npm uninstall @fingerprintjs/fingerprintjs
  npm install @fingerprint/agent

  And replace the package name in your JavaScript/TypeScript code:
  - import FingerprintJS from '@fingerprintjs/fingerprintjs'
  + import Fingerprint from '@fingerprint/agent'
  ```

  ```diff Yarn theme={"theme":"github-dark-dimmed"}
  Run:
  yarn remove @fingerprintjs/fingerprintjs
  yarn add @fingerprint/agent

  And replace the package name in your JavaScript/TypeScript code:
  - import FingerprintJS from '@fingerprintjs/fingerprintjs'
  + import Fingerprint from '@fingerprint/agent'
  ```

  ```ts CDN theme={"theme":"github-dark-dimmed"}
  <script>
    const fpPromise = import('https://openfpcdn.io/fingerprintjs/v4') // [!code --]
    const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY') // [!code ++]
      .then(Fingerprint => Fingerprint.start())
      // ...
  </script>
  ```

  ```ts CDN (legacy variant 1) theme={"theme":"github-dark-dimmed"}
  <script>
  // Initialize the agent at application startup.
  const fpPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.onload = resolve;
    script.onerror = reject;
    script.async = true;
    script.src = 'https://openfpcdn.io/fingerprintjs/v4/iife.min.js'; // [!code --]
    script.src = 'https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js'; // [!code ++]
    document.head.appendChild(script);
  })
    .then(() => Fingerprint.start());
  // ...
  </script>
  ```

  ```ts CDN (legacy variant 2) theme={"theme":"github-dark-dimmed"}
  <!-- Change the script URL: -->
  <script src="https://openfpcdn.io/fingerprintjs/v4/iife.min.js"></script> // [!code --]
  <script src="https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js"></script> // [!code ++]
  <script>
    // ...
  </script>
  ```
</CodeGroup>

3. Add the public API key to the `Fingerprint.start()` configuration:

<CodeGroup>
  ```javascript NPM/Yarn theme={"theme":"github-dark-dimmed"}
  FingerprintJS.load() // [!code --]
  Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' }) // [!code ++]
  ```

  ```text CDN theme={"theme":"github-dark-dimmed"}
  Add your key to the agent script URL, for example:
  https://fpjscdn.net/v4/PUBLIC_API_KEY
  https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js
  ```
</CodeGroup>

That's it, you can now identify browsers with industry-leading accuracy.

## Migrating from FingerprintJS v3 (open-source) to Fingerprint Identification

You can migrate from [FingerprintJS v3](https://github.com/fingerprintjs/fingerprintjs/tree/v3) to Fingerprint Identification in 30 seconds:

1. Sign up on [dashboard.fingerprint.com/signup](https://dashboard.fingerprint.com/signup), create an account, and get your [Public API key](https://dashboard.fingerprint.com/api-keys?type=browser).
2. In your `package.json` or `import` statement, change the `@fingerprintjs/fingerprintjs` package to `@fingerprint/agent`:

<CodeGroup>
  ```diff NPM theme={"theme":"github-dark-dimmed"}
  Run:
  npm uninstall @fingerprintjs/fingerprintjs
  npm install @fingerprint/agent

  And replace the package name in your JavaScript/TypeScript code:
  - import FingerprintJS from '@fingerprintjs/fingerprintjs'
  + import Fingerprint from '@fingerprint/agent'
  ```

  ```diff Yarn theme={"theme":"github-dark-dimmed"}
  Run:
  yarn remove @fingerprintjs/fingerprintjs
  yarn add @fingerprint/agent

  And replace the package name in your JavaScript/TypeScript code:
  - import FingerprintJS from '@fingerprintjs/fingerprintjs'
  + import Fingerprint from '@fingerprint/agent'
  ```

  ```ts CDN theme={"theme":"github-dark-dimmed"}
  <script>
    const fpPromise = import('https://openfpcdn.io/fingerprintjs/v3') // [!code --]
    const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY') // [!code ++]
      .then(Fingerprint => Fingerprint.start())
      // ...
  </script>
  ```

  ```ts CDN (legacy variant 1) theme={"theme":"github-dark-dimmed"}
  <script>
  // Initialize the agent at application startup.
  const fpPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.onload = resolve;
    script.onerror = reject;
    script.async = true;
    script.src = 'https://openfpcdn.io/fingerprintjs/v3/iife.min.js'; // [!code --]
    script.src = 'https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js'; // [!code ++]
    document.head.appendChild(script);
  })
    .then(() => Fingerprint.start());
  // ...
  </script>
  ```

  ```ts CDN (legacy variant 2) theme={"theme":"github-dark-dimmed"}
  <!-- Change the script URL: -->
  <script src="https://openfpcdn.io/fingerprintjs/v3/iife.min.js"></script> // [!code --]
  <script src="https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js"></script> // [!code ++]
  <script>
    // ...
  </script>
  ```
</CodeGroup>

3. Add the public API key to the `Fingerprint.start()` configuration:

<CodeGroup>
  ```javascript NPM/Yarn theme={"theme":"github-dark-dimmed"}
  FingerprintJS.load() // [!code --]
  Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' }) // [!code ++]
  ```

  ```text CDN theme={"theme":"github-dark-dimmed"}
  Add your key to the agent script URL, for example:
  https://fpjscdn.net/v4/PUBLIC_API_KEY
  https://fpjscdn.net/v4/PUBLIC_API_KEY/iife.min.js
  ```
</CodeGroup>

That's it, you can now identify browsers with industry-leading accuracy.

## Migrating from FingerprintJS v2 to Fingerprint Identification

Please see Migrating from [FingerprintJS v2 to Fingerprint Identification](/docs/migrating-from-open-source-v2).

## What's next

As a Fingerprint Identification user, you now have access to various resources not available for FingerprintJS:

* Use the [Server API](/reference/server-api), [Webhooks](/docs/webhooks), or [Sealed results](/docs/sealed-client-results) to securely process Fingerprint results in a server environment.
* Explore Fingerprint [frontend libraries](/docs/frontend-libraries) and [backend libraries](/reference/server-sdks).
* Identify [iOS](/docs/ios) and [Android](/docs/native-android-integration) devices.
* Use [Smart Signals](/docs/smart-signals-reference) to detect bots, VPN users, browser tampering, incognito mode, and more.


# Request filtering for mobile apps
Source: https://docs.fingerprint.com/docs/mobile-app-filtering



To prevent malicious actors from misusing your public API key, you can [filter out unwanted identification requests](/docs/request-filtering). These requests are not billed and will receive an error instead of the identification result.

This page covers filtering requests made from mobile apps. You can filter requests by mobile app **package name** (Android) or **bundle ID** (iOS). To block requests from web browsers, see [Request filtering for websites](/docs/request-filtering-for-websites).

<Note>
  **Availability**

  Filtering requests from mobile app requires [Android SDK v2.4.0+](https://github.com/fingerprintjs/fingerprintjs-pro-android/releases/tag/v2.4.0) and [iOS SDK v2.4.0+](https://github.com/fingerprintjs/fingerprintjs-pro-ios/releases/tag/2.4.0)
</Note>

## Configuration

You can create mobile request filtering rules from the Fingerprint dashboard by specifying the *package names* (Android) or *bundle IDs* (iOS) of the blocked or allowed applications.

1. Navigate to the  **Dashboard** > **[Security](https://dashboard.fingerprint.com/traffic-rules)** > **Mobile Apps**.
2. Click **Configure**.
3. Choose the **Default behavior**:
   1. `Allow all except the ones listed below`: Fingerprint will **block the specified apps** from making identification requests. Requests from all other apps will be allowed.
   2. `Forbid all except the ones listed below`: Fingerprint will **allow only the specified apps** to make identification requests. Requests from all other apps will be blocked.
4. Fill in the **Exceptions** with the package names (Android) or bundle IDs (iOS) of the mobile app you want to allow or block. Wild cards are accepted.
5. Click **Save**.

<img alt="" />

<img alt="" />

## Error handling

Filtered-out requests are not billed and will receive a `PackageNotAuthorized`error instead of the identification result.

For more information on handling errors, see [Handling errors in Android SDK](/docs/android-sdk#handling-errors) and [Handling errors in the iOS SDK](/docs/ios-sdk#handling-errors).


# Multiple environments
Source: https://docs.fingerprint.com/docs/multiple-environments



Create and use multiple environments.

* If you need to use different setups for different domains, either within your organization or for your clients, consider using an environment for each domain.
* Control changes to your production environment with separate environments for development and testing.

<Warning>
  **Limitations**

  * Event identification is not separated by environment, meaning the same device will get the same `visitor_id` in all environments.

  If this is something you would like to use, let us know by leaving feedback on our [public roadmap](https://roadmap.fingerprint.com/tabs/1-under-consideration/submit-idea).
</Warning>

# Managing environments

To manage your environments, navigate to **Settings** → **[Environments](https://dashboard.fingerprint.com/environments)**.

Here you can create new environments, or delete existing ones.

<img alt="" />

Your application will always have a default environment which cannot be removed.

# Event identification

Event identification is not separated by environment, meaning the same device will get the same `visitor_id` in all environments.

### Configuring monthly usage limits

When managing environments, you can adjust monthly usage limit for each environment. This is useful when you don't want your testing environment, or an environment dedicated to an external team, to make excessive number of API calls.

You can configure the usage threshold and what happens when the threshold is reached.

* Selecting *Notify* turns on email notification when the environment reaches the set limit.
* Selecting *Restrict* turns on email notification, and will prevent any further calls to be made from this environment when the limit is reached. Restricting usage is available to Enterprise customers only.

The usage limit is reset every month on your billing date. For enterprise customers, this happens at the start of calendar month.

# Public API keys

When creating new public API keys, you can assign them to a specific environment. By doing this, identification events registered with a specific environment can then be filtered by different set of request filtering rules.

<img alt="" />

To create a new API key for specific environment, go to **[API Keys](https://dashboard.fingerprint.com/api-keys)**. Changing environment for an existing key is not supported.

<img alt="" />

# Server API keys

When creating secret API keys to be used with **[Server API](/reference/server-api)**, you can optionally choose to limit the scope to only specific environment. For environment-scoped keys, Server API will operate only with identification events with a matching environment. On the other hand, workspace-scoped keys allow you to utilize Server API with events from any environment.

To create a new API key for specific environment, go to **[API Keys](https://dashboard.fingerprint.com/api-keys)**. Changing environment for an existing key is not supported.

# Request filtering

When setting up request filtering rules, you can assign them to a specific environment. In combination with API keys, you can create different request filtering rules for each environment, ensuring that you don’t accidentally allow traffic from unwanted origins.

To manage environment specific request filtering rules, go to **[Security](https://dashboard.fingerprint.com/traffic-rules)**. On top of the page, you can select the environment you're configuring filtering rules for.

<img alt="" />

# Webhooks

When creating webhooks, you can optionally limit their scope to a specific environment. An environment-scoped webhook will only report identification events from the matching environment. On the other hand, workspace-scoped webhook will report all identification events from the workspace.

To manage webhooks, go to **[Webhooks](https://dashboard.fingerprint.com/webhooks)**.

<img alt="" />

# Sealed Client Results

When creating Encryption keys in order to enable [Sealed Client Results](/docs/sealed-client-results), you can assign them to specific environment. This will result in client-side payload being encrypted for this particular environment. Other environments will remain unaffected and their payloads will not be encrypted.

To manage Encryption keys, go to **[API Keys](https://dashboard.fingerprint.com/api-keys)** and look for **Encryption keys** section.

<img alt="" />

# Proxy integrations and proxy secrets

Deploying a proxy integration requires creating a proxy secret to authenticate requests coming through the integration. You can create a proxy secret that works in all environments (**workspace-scoped**), or you can assign a proxy secret to a specific environment (**environment-scoped**).

If you create an environment-scoped proxy secret, the proxy integration will only work for identification requests made using a [public API key](#public-api-keys) from the same environment.

Recommended setups include:

* Using a single, workspace-scoped proxy integration (proxy secret) which can be used with all environments.
  * For example, you can have one workspace-scoped AWS CloudFront integration used for both production and staging environments.
  * This will appear in the Dashboard as a single "All environments" integration status page. Inside the status page, you can still filter request statistics by their public API key environment.
* Using multiple environment-scoped proxy integrations (proxy secrets), one for each environment.
  * For example, if you maintain Fingerprint setups for multiple clients within your workspace, you can have environments like Client A, Client B, Client C and deploy a separate Cloudflare integration (proxy secret) for each environment.
  * This will appear in the Dashboard as 3 separate integration status pages, one for each environment.

<img alt="" />

<Note>
  **Limitations and best practices**

  We recommend using one of the setups recommended above.

  * Deploying one workspace-scoped and one environment-scoped integration of the same type (e.g., Cloudflare) is possible only to ease the transition from one setup to the other. Note that identification requests will show up on **one or the other status page** based on the **proxy secret environment scope** (not the public API key environment).
  * We do not recommend using multiple integrations of the same type (e.g. multiple Fastly VCL integrations) in a single environment. That setup would make the integrations harder to monitor and troubleshoot. Requests from both integrations would have the same proxy secret environment, so they would be pooled to a single status page in the Dashboard.
  * For proxy integrations managed through the Fingerprint Dashboard (Cloudflare and AWS CloudFront), you can only connect one Cloudflare/AWS CloudFront integration per environment and one workspace-scoped integration.
</Note>


# Network request filtering
Source: https://docs.fingerprint.com/docs/network-request-filtering

Filter unwanted traffic based on a list of source IP addresses

Some unwanted traffic can be identified based on a set of IP addresses. Typical examples can be short-lived bot attacks or exclusion of testing requests.

## Configuration

To filter requests by an **IP address** (or **IP address ranges**):

1. Navigate to the **[Security](https://dashboard.fingerprint.com/traffic-rules)** > **Network** tab.

<img alt="" />

2. Under **No IP address rules**, click **Configure**.
3. To create an IP *Blocklist*, set **Default behavior** to  `Allow all besides the IP addresses listed below`. Then fill in the **Exceptions** field with your list of blocked IP addresses.

<img alt="" />

4. Click **Save**.

## IP address format

The configuration accepts both single IP addresses in the form of `192.168.1.1/32` and IP address ranges defined by their [CIDR representation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation) (e.g. `192.168.1.1/16`).


# Privacy policy
Source: https://docs.fingerprint.com/docs/privacy-policy

Effective date: November 1, 2026. | [Archived Versions](/docs/legal-archive)

## 1. Introduction

FingerprintJS Inc. (“Fingerprint”, “us”, “we”, or “our”) operates [https://fingerprintjs.com](https://fingerprintjs.com/) and API services available at [https://fpjs.io](https://fpjs.io/) (including subdomains) (hereinafter referred to as “**Service**”).

Our Privacy Policy governs your visit to [https://fingerprintjs.com](https://fingerprintjs.com/) or usage of our API services, available at [https://fpjs.io](https://fpjs.io/) (including subdomains), and explains how we collect, safeguard and disclose information that results from your use of our Service.

Where we refer to “**Personal Information**” in this Privacy Policy, this means personal data or personally identifiable information that can be used to contact or identify you.

Data protection laws sometimes differentiate between “controllers” and “processors” of Personal Information. A “controller” determines the purposes and means (the why and how) of processing Personal Information. A “processor” processes Personal Information on behalf of a controller subject to the controller’s instructions. We provide our Service to business customers that operate sites or services you may visit. Where we process Personal Information of our business customers’ end users during the provision of our Service, we generally act as a processor and our business customer (i.e. the site or service operator) acts as a controller.

If you are accessing our Service from the European Economic Area, Switzerland or the United Kingdom, please refer to the additional disclosures in Annex 1.

We use your Personal Information to provide and improve Service. Unless otherwise defined in this Privacy Policy, the terms used in this Privacy Policy have the same meanings as in our Terms and Conditions.

Our Terms and Conditions (“**Terms**”), [https://docs.fingerprint.com/docs/terms-of-service](https://docs.fingerprint.com/docs/terms-of-service), govern all use of our Service and together with the Privacy Policy constitutes your agreement with us (“**agreement**”).

## 2. Definitions

**SERVICE** means the [https://fingerprintjs.com](https://fingerprintjs.com/) website or [https://fpjs.io](https://fpjs.io/) (including subdomains) services operated by FingerprintJS Inc.

**USAGE DATA** is data collected automatically either generated by the use of Service or from Service infrastructure itself (for example, the duration of a page visit).

**COOKIES** are small files stored on your device (computer or mobile device).

**THE USER** is the individual using our Service (i.e. our customers or those acting on behalf of our customers).

**THE CUSTOMER END USER** is the end user of our customers.

## 3. Information Collection and Use

We collect several different types of information for various purposes to provide and improve our Service to you.

## 4. Types of Data Collected

### Personal Information

While using our Service, we may ask you to provide us with Personal Information . Personal Information may include, but is not limited to:

(a) Users’ name, address, phone number, email address and password

(b) Users’ payment and transaction related information where personal payment information is provided (see section titled “Payments” below)

(c) Tracking Cookies Data and Usage Data (including IP address)

We may use your Personal Information to contact you with newsletters, marketing or promotional materials and other information that may be of interest to you. You may opt out of receiving any, or all, of these communications from us by following the unsubscribe link.

### Usage Data

We may also collect information that your browser sends whenever you visit our Service or when you access Service by or through a mobile device (“**Usage Data**”).

This Usage Data may include information such as your computer's Internet Protocol address (e.g. IP address), browser type, browser version, the pages of our Service that you visit, the time and date of your visit, the time spent on those pages, unique device identifiers and other diagnostic data.

When you access Service with a mobile device, this Usage Data may include information such as the type of mobile device you use, your mobile device unique ID, the IP address of your mobile device, your mobile operating system, the type of mobile Internet browser you use, unique device identifiers and other diagnostic data.

### Tracking Cookies Data

We use cookies and similar tracking technologies to track the activity on our Service and we hold certain information.

Cookies are files with a small amount of data which may include an anonymous unique identifier. Cookies are sent to your browser from a website and stored on your device. Other tracking technologies are also used such as beacons, tags and scripts to collect and track information and to improve and analyze our Service.

Examples of Cookies we use:

**(a) Session Cookies:** We use Session Cookies to operate our Service.

**(b) Preference Cookies:** We use Preference Cookies to remember your preferences and various settings.

**(c) Security Cookies:** We use Security Cookies for security purposes.

If you would prefer not to accept cookies, most browsers will allow you to (i) change your browser settings to notify you when you receive a cookie, which lets you choose whether or not to accept it; (ii) disable existing cookies; or (iii) set your browser to automatically reject cookies. Please note that not accepting cookies may negatively impact your experience using the Service, as some features and services on our Service may not work properly. Depending on your operating system, you may not be able to delete or block all cookies and you may not be able to block non-cookie technologies and these browser settings that block cookies may have no effect on such techniques. You may also set your e-mail options to prevent the automatic downloading of images that may contain technologies that would allow us to know whether you have accessed our e-mail and performed certain functions with it.

<u>Do Not Track Signals</u>. Although we do our best to honor the privacy preferences of our users, we are unable to respond to Do Not Track signals set by your browser at this time.

We may use third-party Service Providers to monitor and analyze the use of our Service.

<u>Google Analytics</u>. Google Analytics is a web analytics service offered by Google that tracks and reports website traffic. Google uses the data collected to track and monitor the use of our Service. This data is shared with other Google services. Google may use the collected data to contextualize and personalize the ads of its own advertising network.

For more information on the privacy practices of Google, please visit the Google Privacy Terms web page: [https://policies.google.com/privacy?hl=en](https://policies.google.com/privacy?hl=en)

We also encourage you to review the Google's policy for safeguarding your data: [https://support.google.com/analytics/answer/6004245](https://support.google.com/analytics/answer/6004245).

## 5. Use of Data

FingerprintJS Inc. uses the collected data for various purposes:

(a) to provide and maintain our Service;

(b) to notify you about changes to our Service;

(c) to allow you to participate in interactive features of our Service when you choose to do so;

(d) to provide customer support;

(e) to gather analysis or valuable information so that we can improve our Service;

(f) to monitor the usage of our Service;

(g) to detect, prevent and address technical issues;

(h) to fulfill any other purpose for which you provide it;

(i) to carry out our obligations and enforce our rights arising from any contracts entered into between you and us, including for billing and collection;

(j) to provide you with notices about your account and/or subscription, including expiration and renewal notices, email-instructions, etc.;

(k) to provide you with news, special offers and general information about other goods, services and events which we offer that are similar to those that you have already purchased or enquired about unless you have opted not to receive such information;

(l) in any other way we may describe when you provide the information;

(m) for any other purpose with your consent.

## 6. Retention of Information

We will retain your Personal Information only for as long as is necessary for the purposes set out in this Privacy Policy. We will retain and use your Personal Information to the extent necessary to comply with our legal obligations (for example, if we are required to retain your data to comply with applicable laws), resolve disputes, and enforce our legal agreements and policies. Any Customer End User information that we have access to shall be retained according to our agreement with our business customer.

We will retain Usage Data for internal analysis purposes and to improve our Service. Usage Data is generally retained for a shorter period, except when this information is used to strengthen the security or to improve the functionality of our Service, or we are legally obligated to retain this information for longer time periods.

## 7. Disclosure of Information

We may disclose Personal Information that we collect, or you provide as follows:

### (a) Third-Party Vendors and Other Service Providers.

We may share your Personal Information with Service Providers who perform services on our behalf, as needed to carry out their work for us, which may include, for example, payment providers to successfully process payments. These third parties have access to your Personal Information only to perform these tasks on our behalf and are obligated not to disclose or use it for any other purpose.

### (b) Other Companies and Brands Owned Or Controlled by FingerprintJS.

We may disclose your Personal Information with other companies owned by or under common ownership as FingerprintJS, which also includes our subsidiaries (i.e., any organization we own or control) or our ultimate holding company (i.e., any organization that owns or controls us) and any subsidiaries it owns. These companies will use your personal information in the same way as we can under this Privacy Policy,

### (c) Disclosure for Law Enforcement.

Under certain circumstances, we may be required to disclose your Personal Information with third parties as required by law or subpoena or if we reasonably believe that such action is necessary to (a) comply with the law and the reasonable requests of law enforcement; (b) to enforce our Terms and Conditions or to protect the security or integrity of our Service; and/or (c) to exercise or protect the rights, property, or personal safety of FingerprintJS, our visitors, or others.

### (d) Business Transaction.

We may disclose your Personal Information with other parties in connection with a company transaction, such as a merger, sale of company assets or shares, reorganization, financing, change of control or acquisition of all or a portion of our business by another company or third party, or in the event of a bankruptcy or related or similar proceedings.

## 8. Security of Information

The security of your information is important to us but remember that no method of transmission over the Internet or method of electronic storage is 100% secure. While we strive to use commercially acceptable means to protect your Personal Information, we cannot guarantee its absolute security.

## 9. CI/CD tools

We may use third-party Service Providers to automate the development process of our Service.

### GitHub

GitHub is provided by GitHub, Inc.

GitHub is a development platform to host and review code, manage projects, and build software.

For more information on what data GitHub collects for what purpose and how the protection of the data is ensured, please visit GitHub Privacy Policy page: [https://help.github.com/en/articles/github-privacy-statement](https://help.github.com/en/articles/github-privacy-statement)

### GitLab CI/CD

GitLab CI/CD is provided by GitLab, Inc.

GitLab CI (Continuous Integration) service is a part of GitLab that build and test the software whenever developer pushes code to application.

GitLab CD (Continuous Deployment) is a software service that places the changes of every code in the production which results in every day deployment of production.

For more information on what data GitLab CI/CD collects for what purpose and how the protection of the data is ensured, please visit GitLab CI/CD Privacy Policy page: [https://about.gitlab.com/privacy/](https://about.gitlab.com/privacy/).

## 10. Payments

We may provide paid products and/or services within Service. In that case, we use third-party services for payment processing (e.g. payment processors).

We will not store or collect your payment card details. That information is provided directly to our third-party payment processors whose use of your personal information is governed by their Privacy Policy. These payment processors adhere to the standards set by PCI-DSS as managed by the PCI Security Standards Council, which is a joint effort of brands like Visa, Mastercard, American Express and Discover. PCI-DSS requirements help ensure the secure handling of payment information.

The payment processors we work with are:

Stripe:

We use Stripe for payment, analytics, and other business services. Stripe collects identifying information about the devices that connect to its services. Stripe uses this information to operate and improve the services it provides to us, including for fraud detection. You can learn more about Stripe and read its privacy policy at [https://stripe.com/privacy](https://stripe.com/privacy).

## 11. Links to Other Sites

Our Service may contain links to other sites that are not operated by us. If you click a third party link, you will be directed to that third party's site. We strongly advise you to review the Privacy Policy of every site you visit.

We have no control over and assume no responsibility for the content, privacy policies or practices of any third party sites or services.

## 12. Children's Privacy

Our Services are not intended for use by children under the age of 13 (“**Children**”).

We do not knowingly collect Personal Information from Children under 13. If you become aware that a Child has provided us with Personal Information, please contact us at the information provided below. If we become aware that have collected Personal Information from Children without parental consent, we take steps to remove that information from our servers.

## 13. Changes to This Privacy Policy

We may update our Privacy Policy from time to time. We will notify you of any changes by posting the new Privacy Policy on this page.

We will let you know via email and/or a prominent notice on our Service, prior to the change becoming effective and update “effective date” at the top of this Privacy Policy.

You are advised to review this Privacy Policy periodically for any changes. Changes to this Privacy Policy are effective when they are posted on this page.

## 14. Contact Us

If you have any questions about this Privacy Policy, please contact us:

By email: [support@fingerprint.com](mailto:support@fingerprint.com).

## Annex 1 - EEA, SWISS AND UK DISCLOSURES

This Annex 1 (the "**European Data Annex**") sets out how we collect, store, process, transfer, share and use data that identifies or is associated with you ("**personal data**") when you access our Service from the European Economic Area, Switzerland or the United Kingdom.

This European Data Annex was last updated on October 1, 2026.

### 1. Who is responsible for the use of your personal data

There are various ways in which we collect and receive personal data about you when you use the Service, and our role with respect to your personal data will vary depending on our relationship with you, how we collect this personal data and how we use it.

In certain circumstances we will act as the controller of your personal data, which means we determine and are responsible for how that personal data is used.

In other circumstances we act as a processor on behalf of another person, meaning that our use of this personal data is governed by our Terms of Service [https://docs.fingerprint.com/docs/terms-of-service](https://docs.fingerprint.com/docs/terms-of-service) and, where applicable, the data processing addendum [https://docs.fingerprint.com/docs/dpa-gdpr](https://docs.fingerprint.com/docs/dpa-gdpr) and [https://docs.fingerprint.com/docs/dpa-usspl](https://docs.fingerprint.com/docs/dpa-usspl)

The following summarizes where we believe we act as a controller and where we would consider ourselves to act as a processor:

* **When you subscribe to the Service and set up an account**, whether on your own behalf or on behalf of your employer, we will be the controller of your personal data that you provide to us, such as your name and other contact details, your payment details and transaction details (including the details of the type of service you have purchased).
* **When someone else sets up an account on the Service (the "Customer") and gives you access to the Service (and makes you an "Authorised User")**, such as your employer, we will process the personal data about you (such as your contact details) that they submit to us as a processor on their behalf.
* **When you access and use the Service**, we will be a controller in respect of any information about your usage of the Service, such as the pages you access and functionalities you use, as well as information about the type of device you use to access the Service.
* **When you submit support requests to us**, we will process any personal data contained in that support request as a processor on behalf of the relevant Customer.
* **When you submit comments and opinions to us**, and we use those comments and opinions to improve the Service or develop new products, we will be the controller of the personal data contained in those comments and opinions; and
* **With respect to Customer End User Data**, we generally act as a processor on behalf of the relevant Customer, other than in the limited circumstances set out below.

This European Data Annex applies to our use of your personal data when we act as a controller of that personal data.

### 2. Personal data we collect from you directly and how we use it

The following table sets out the categories of personal data that we collect from you directly when you subscribe to and use the Service and when you correspond with us. It also sets out the purposes for which we will process this personal data and the lawful basis we rely on to do so.

We will indicate to you where the provision of certain personal data is required in order for us to provide you certain features of the Service. If you choose not to provide such personal data, we may not be able to provide those parts of the Service to you or respond to your other requests.

| Category of personal data                                                                                                                                              | How we use it                                                                                                                                                                                                                                                  | Legal basis for the processing                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to set up and authenticate your account.                                                                                                                                                                                               | If you are the Customer, the processing is necessary for the performance of a contract with you and to take steps prior to entering into a contract with you.<br />If you subscribe to the Service on behalf of a Customer, the processing is necessary for the Customer's legitimate interests, namely setting up and administering the Customer's account.                                                               |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to deal with enquiries and complaints made by you relating to the Service.                                                                                                                                                             | The processing is necessary for our legitimate interests, namely administering the Service, and for communicating with you effectively to respond to your queries or complaints.                                                                                                                                                                                                                                           |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to communicate with you, including sending service-related communications.                                                                                                                                                             | If you are the Customer, the processing is necessary for the performance of a contract with you.<br />If you subscribe to the Service on behalf of a Customer, the processing is necessary for our legitimate interests, namely providing service related information and updates.                                                                                                                                         |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to send you unsolicited marketing communications in accordance with your preferences.                                                                                                                                                  | If you are the Customer, or sign up and create an account on behalf of the Customer, the processing is necessary for our legitimate interests, namely promoting certain features of our Service and our similar products and services to you.<br />If you have been granted access to the Service as an Authorized User, we will only use your personal data in this way to the extent you have given us consent to do so. |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to identify and prevent fraud.                                                                                                                                                                                                         | The processing is necessary for our legitimate interests, namely identifying and preventing fraud.                                                                                                                                                                                                                                                                                                                         |
| **Payment and transaction information**, such as your credit or debit card and billing address.                                                                        | We use this information to process the payments you make through the Service.                                                                                                                                                                                  | If you are the Customer, the processing is necessary for the performance of a contract with you and to take steps prior to entering into a contract with you.<br />If you subscribe to the Service on behalf of a Customer, the processing is necessary for our legitimate interests, namely billing the Customer in respect of their use of the Service.                                                                  |
| **Payment and transaction information**, such as your credit or debit card and billing address.                                                                        | We use this information to determine products and services that may be of interest to you for marketing purposes                                                                                                                                               | The processing is necessary for our legitimate interests, namely to inform our marketing activities.                                                                                                                                                                                                                                                                                                                       |
| **Chat, comments and opinions.** When you contact us directly, e.g. by email or phone, we will record your comments and opinions.                                      | We use this information to address your questions, issues and concerns.                                                                                                                                                                                        | The processing is necessary for our legitimate interests, namely communicating with users and responding to queries, complaints and concerns.                                                                                                                                                                                                                                                                              |
| **Chat, comments and opinions.** When you contact us directly, e.g. by email or phone, we will record your comments and opinions.                                      | We use this information to develop new products and features available through the Service or otherwise improve the Service.                                                                                                                                   | The processing is necessary for our legitimate interests, namely developing and improving the Service.                                                                                                                                                                                                                                                                                                                     |
| **Your preferences**, such as preferences set for notifications, marketing communications, how the Service is displayed and the active functionalities on the Service. | We use this information to provide notifications, send news, alerts and marketing communications and provide the Service in accordance with your choices.                                                                                                      | The processing is necessary for our legitimate interest, namely ensuring the user receives the correct marketing and other communications, and that the Service is displayed in accordance with the user's preferences.                                                                                                                                                                                                    |
| **Your preferences**, such as preferences set for notifications, marketing communications, how the Service is displayed and the active functionalities on the Service. | We use this information to ensure that we comply with our legal obligation to send only those marketing communications to which you have consented.                                                                                                            | The processing is necessary for compliance with a legal obligation to which we are subject.                                                                                                                                                                                                                                                                                                                                |
| **All personal data set out above.**                                                                                                                                   | We may use all the personal data we collect to operate, maintain and provide to you the features and functionality of the Service, to communicate with you, to monitor and improve the Service and business, and to help us develop new products and services. | The processing is necessary for our legitimate interests, namely to administer and improve the Service.                                                                                                                                                                                                                                                                                                                    |

### 3. Personal data we collect about you automatically

#### 3.1

If you are a User, we also collect personal data about you automatically when you use the Service. The following table sets out the categories of personal data that we collect about Users in this way. It also sets out the purposes for which we will process this personal data and the lawful basis we rely on to do so.

| Category of personal data                                                                                                                                                                                                                                                                                                                                                                                                                                              | How we may use it                                                                                                                                                                                                                                                                                                                                  | Legal basis for the processing                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Approximate location information.** Other than information you choose to provide to us, we do not collect information about your precise location. Your device’s IP address may however help us determine an approximate location.                                                                                                                                                                                                                                   | Where relevant and where permitted under applicable law, we use this information to resolve issues, monitor and detect fraud or suspicious activity in relation to your or a Customer's account and to identify potential risk or unlawful behavior including fraud detection, theft prevention, emergency response purposes and legal compliance. | The processing is necessary for our legitimate interests, namely identifying and mitigating the risk of unlawful behavior to protect the Service, Fingerprint and its Customers. |
| **Approximate location information.** Other than information you choose to provide to us, we do not collect information about your precise location. Your device’s IP address may however help us determine an approximate location.                                                                                                                                                                                                                                   | We use information you provide to us about your location to inform and plan our marketing strategy.                                                                                                                                                                                                                                                | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Approximate location information.** Other than information you choose to provide to us, we do not collect information about your precise location. Your device’s IP address may however help us determine an approximate location.                                                                                                                                                                                                                                   | We use this information to tailor how the Service is displayed to you (such as the content that is provided to you through the Service and/or the language in which it is provided to you).                                                                                                                                                        | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | We use information about how you use and connect to the Service to present the Service to you on your device.                                                                                                                                                                                                                                      | The processing is necessary for our legitimate interests, namely presenting the Service to our users so they can access and use our Service.                                     |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | We use this information to tailor how the Service is displayed to you (such as the content that is provided to you through the Service and/or the language in which it is provided to you).                                                                                                                                                        | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | Where relevant and where permitted under applicable law, we use this information to resolve issues, monitor and detect fraud or suspicious activity in relation to your or a Customer's account and to identify potential risk or unlawful behavior including fraud detection, theft prevention, emergency response purposes and legal compliance. | The processing is necessary for our legitimate interests, namely identifying and mitigating the risk of unlawful behavior to protect the Service, Fingerprint and its Customers. |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | We use this information to determine products and services that may be of interest to you for marketing purposes.                                                                                                                                                                                                                                  | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | We use this information to monitor and improve the Service and business, and to inform the development of new products and services.                                                                                                                                                                                                               | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | We use information about how you use and connect to the Service to present the Service to you on your device.                                                                                                                                                                                                                                      | The processing is necessary for our legitimate interests, namely presenting the Service to our users so they can access and use our Service.                                     |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | Where relevant and where permitted under applicable law, we use this information to resolve issues, monitor and detect fraud or suspicious activity in relation to your or a Customer's account and to identify potential risk or unlawful behavior including fraud detection, theft prevention, emergency response purposes and legal compliance. | The processing is necessary for our legitimate interests, namely identifying and mitigating the risk of unlawful behavior to protect the Service, Fingerprint and its Customers. |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | We use this information to tailor how the Service is displayed to you (such as the content that is provided to you through the Service and/or the language in which it is provided to you).                                                                                                                                                        | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | We use this information to determine products and services that may be of interest to you for marketing purposes.                                                                                                                                                                                                                                  | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | We use this information to monitor and improve the Service and business, and to inform the development of new products and services.                                                                                                                                                                                                               | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |

### 4. Customer End User Data

We mostly only process personal data relating to Customer End Users to provide our services to the relevant Customer as a processor on behalf of the relevant Customer. However, where a Customer opts in to using our Device Reputation Network product, we will process the following personal data as a controller:

| Category of personal data                                                                                                                                                                                                                                                                 | How we may use it                                                                                                                                                                                                                  | Legal basis for the processing                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fraud flags.** Where Customers identify that a device is being used fraudulently, we will retain the device identifier generated by the Service and the fact that the device has been flagged for fraud, together with the number of times it has been flagged and when it was flagged. | We make this information available to Customers who opt in to use the Device Reputation Network feature of our Service, which enables Customers to identify devices previously flagged for, and therefore at higher risk of fraud. | The processing is necessary for our legitimate interests, namely providing the Device Reputation Network fraud risk feature of our Service. |

### 5. Anonymization and aggregation of information

In connection with the purposes and data uses described above, we may anonymize and aggregate any of the information we collect (so that it does not directly identify you). We may use such anonymized information for purposes that include testing our IT systems, research, data analysis, improving the Service and developing new products and features.

### 6. Recipients of your personal data

We may share your personal data with the parties and for the purposes set out in paragraph 7 (**Disclosure of Data**), paragraph 10 (**CI/CD tools**) and paragraph 11 (**Payments**) of the main body of this Privacy Policy.

We may provide third parties with aggregate statistical information and analytics about users of the Service but we will make sure no one can be identified from this information before we disclose it.

### 7. How long we store your personal data

Paragraph 6 (**Retention of Data**) of the main body of this Privacy Policy sets out how long we will retain your personal data. We retain fraud flags in connection with the provision of the Device Reputation Network, as described in paragraph 4 above, for 2 years.

### 8. Marketing and Advertising

From time to time we may send you emails about our products, services and features available on the Service. For some marketing messages, we may use personal information we collect about you to help us determine the most relevant marketing information to share with you.

We will give you the opportunity to opt out of these promotional messages when you sign up and create an account on the Service.

You can also withdraw your consent at a later date by clicking on the unsubscribe link at the bottom of our marketing emails or by updating your preferences through the Service.

We will not send you these messages if you opt out from receiving them, or if you do not give us your consent. We will, however, still need to contact you with non-promotional, technical service-related information about the Service.

### 9. Cookies

Our Service uses cookies and similar technologies such as pixels and JavaScript tags and Local Storage Objects (together "**cookies**") to distinguish you from other users. The cookies we use are necessary for the operation of certain features of our Service. We also use them to detect errors on our Service and apply security settings.

The following table sets out information about the cookies we use on our Service:

| Cookie             | Type of cookie | When is the cookie set                                  | How long does the cookie last      | Purpose of the cookie                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | -------------- | ------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Google Tags        | Functional     | On first visiting the fingerprint.com site (our "Site") | Until you finish browsing our Site | This tag allows us to integrate analytics, such as Google Analytics, and similar products that track and monitor website traffic into our Site. This enables us to see how the Site is performing in order to identify errors or features that users find confusing.<br />This data will not, however, be shared with other Google services or used for contextualizing or personalizing the advertising displayed to you.<br />You can learn more about Google’s practices at [http://www.google.com/policies/privacy/partners](http://www.google.com/policies/privacy/partners), and view its currently available opt-out options at [https://tools.google.com/dlpage/gaoptout](https://tools.google.com/dlpage/gaoptout) |
| \_vid\_t, \_vid\_i | Functional     | On first visiting the Site                              | 1 year                             | This cookie allows us to demonstrate the functionality of our Service to visitors of the Site.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| \_vid\_lr          | Functional     | On first visiting the Site                              | 1 year                             | This cookie is used to diagnose latency and performance issues                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| \_cfduiud          | Functional     | On first visiting the dev.fingerprint.com site          | 1 month                            | This cookie is used to identify individual clients behind a shared IP address and apply settings on a per-client basis. We use it in connection with ensuring the Site is presented to you in the correct language, and to identify trusted web traffic and apply security settings on a per-client basis.                                                                                                                                                                                                                                                                                                                                                                                                                  |

Other than cookies that are necessary for the operation of our Site, you will only receive cookies when you have given us your consent to do so. In addition, if you do not wish to receive cookies, most browsers allow you to change your cookie settings.

Depending on your device and operating system, you may not be able to delete or block all cookies. Please note that if you choose to refuse all cookies you may not be able to use the full functionality of our Service.

These settings will typically be found in the "options" or "preferences" menu of your browser. In order to understand these settings, the following links may be helpful, otherwise you should use the "Help" option in your browser for more details.

* **(a)** [Cookie settings in Internet Explorer](https://support.microsoft.com/en-gb/help/278835/how-to-delete-cookie-files-in-internet-explorer) and [Edge](https://support.microsoft.com/en-us/windows/microsoft-edge-browsing-data-and-privacy-bb8174ba-9d73-dcf2-9b4a-c582b4e640dd)
* **(b)** [Cookie settings in Firefox](http://support.mozilla.org/en-US/kb/cookies)
* **(c)** [Cookie settings in Chrome](https://support.google.com/chrome/answer/95647?hl=en)
* **(d)** [Cookie settings in Opera](https://help.opera.com/en/latest/web-preferences/)
* **(e)** [Cookies settings in Safari web](https://support.apple.com/en-gb/guide/safari/manage-cookies-and-website-data-sfri11471/mac) and [iOS](https://support.apple.com/en-gb/HT201265).

If you would like to find out more about cookies and other similar technologies, please visit [www.allaboutcookies.org](http://www.allaboutcookies.org) or the Network Advertising Initiative's online sources at [www.networkadvertising.org](http://www.networkadvertising.org).

### 10. Transfer of Data

Your personal data may be transferred to – and maintained on – computers located outside of your state, province, country or other governmental jurisdiction where the data protection laws may differ from those of your jurisdiction.

If you choose to provide information to us, please note that we are located in the United States and your personal data will be transferred to, and processed in, the United States. We may also further transfer your personal data to other entities within the United States or other countries outside of the United Kingdom, Switzerland or the EEA to process it there. Where this is the case, we typically rely on either (i) an “adequacy decision” (where (as applicable) the European Commission, UK Secretary of State or Swiss Federal Council has deemed a country or international organisation to adequately safeguard personal information), (ii) standard contractual clauses adopted by (as applicable) the European Commission, UK Secretary of State or Federal Data Protection and Information Commissioner; or (iii) certification to the EU-U.S., Swiss-U.S. Data Privacy Framework and UK Extension (“DPF”) (a framework designed by the U.S. Department of Commerce and the European Commission (and respectively the Swiss Federal Council and UK Secretary of State) to ensure adequate protection for personal information transferred to a company participating in the DPF) as the appropriate safeguard in relation to such transfers.

FingerprintJS Inc. will take all the steps reasonably necessary to ensure that your data is treated securely and in accordance with this European Data Annex, including implementing adequate safeguards with respect to the security and handling of your personal data.

If you wish to enquire further about the safeguards we use, please contact us using the contact details in paragraph 15 (**Contact Us**) in the main body of this Privacy Policy.

### 11. Your Data Protection Rights

In accordance with applicable privacy law you have the following rights in respect of your personal data that we hold:

* **(a)** **Right of access**. You have the right to obtain:
* **(i)** confirmation of whether, and where, we are processing your personal data;
* **(ii)** information about the categories of personal data we are processing, the purposes for which we process your personal data and information as to how we determine applicable retention periods;
* **(iii)** information about the categories of recipients with whom we may share your personal data; and
* **(iv)** a copy of the personal data we hold about you.
* **(b)** **Right of portability**. You have the right, in certain circumstances, to receive a copy of the personal data you have provided to us in a structured, commonly used, machine-readable format that supports re-use, or to request the transfer of your personal data to another person.
* **(c)** **Right to rectification**. You have the right to obtain rectification of any inaccurate or incomplete personal data we hold about you without undue delay.
* **(d)** **Right to erasure**. You have the right, in some circumstances, to require us to erase your personal data without undue delay if the continued processing of that personal data is not justified.
* **(e)** **Right to restriction**. You have the right, in some circumstances, to require us to limit the purposes for which we process your personal data if the continued processing of the personal data in this way is not justified, such as where the accuracy of the personal data is contested by you.
* **(f)** **Right to withdraw consent**. If you have provided consent for the processing of your personal data, you have the right to withdraw your consent. If you withdraw your consent, this will not affect the lawfulness of our use of your personal data before your withdrawal.

**You have a right to object to any processing based on our legitimate interests. There may, depending on the particular circumstances, be compelling reasons for continuing to process your personal data despite your objection, and we will assess and inform you if that is the case. You can object to marketing activities for any reason.**

If you wish to exercise one of these rights, please contact us using the contact details in paragraph 15 (**Contact Us**) in the main body of this Privacy Policy.

You also have the right to lodge a complaint to your national data protection authority.

If you are in the UK, the relevant authority is the Information Commissioner's Office – please visit [https://ico.org.uk/make-a-complaint/](https://ico.org.uk/make-a-complaint/) for more information. You also have the right to submit a complaint directly to us.

If you are in the EEA, further information about how to contact your local data protection authority is available at [http://ec.europa.eu/justice/data-protection/bodies/authorities/index\_en.htm](http://ec.europa.eu/justice/data-protection/bodies/authorities/index_en.htm).

If you are in Switzerland, please visit [https://www.edoeb.admin.ch/edoeb/en/home/the-fdpic/links/data-protection---switzerland.html](https://www.edoeb.admin.ch/edoeb/en/home/the-fdpic/links/data-protection---switzerland.html) for more information.

### 12. Links to third party sites

The Service may, from time to time, contain links to and from third party websites, including those of other users, our partner networks, advertisers, partner merchants, news publications, retailers and affiliates. If you follow a link to any of these websites, please note that these websites have their own privacy policies and that we do not accept any responsibility or liability for their policies. Please check the individual policies before you submit any information to those websites.

### 13. Our Policy towards children

The Service is not directed at persons under 18 and we do not knowingly collect personal data from children under 18. If you become aware that your child has provided us with personal data, without your consent, then please contact us using the contact details in paragraph 15 (**Contact Us**) in the main body of this Privacy Policy so that we can take steps to remove such information as quickly as possible.

### 14. Changes to this policy

We may update this European Data Annex from time to time and so you should review this page periodically. When we change this European Data Annex in a material way, we will update the "last modified" date at the beginning of this European Data Annex. Changes to this European Data Annex are effective when they are posted on this page.

### 15. Notice to you

If we need to provide you with information about something, whether for legal, marketing or other business related purposes, we will select what we believe is the best way to get in contact with you. We will usually do this through email. The fact that we may send notices to you will not stop you from being able to opt out of certain types of contact as described in this European Data Annex.

What’s Next

* [Start your free subscription now](https://dashboard.fingerprintjs.com/signup/)


# Product Roadmap
Source: https://docs.fingerprint.com/docs/product-roadmap





# Protecting from client-side tampering and replay attacks
Source: https://docs.fingerprint.com/docs/protecting-from-client-side-tampering

Prevent malicious users from bypassing Fingerprint by integrating it with your server and checking the identification results for freshness and consistency with the associated HTTP requests.

Fingerprint provides you with device intelligence about the *client environment* of your users — browsers visiting your website or mobile devices using your mobile app.

Fingerprint needs to run on the client to analyze it. But in most cases, you *shouldn't use the provided visitor ID directly in the client* nor send it in plain text from the client to the server. Client environments (browsers and mobile devices) can be tampered with and any functionality or security measures relying on client-side logic or data can be bypassed.

In this guide, we will start with a bad example of a Fingerprint implementation vulnerable to client-side tampering. Then you will learn how to receive, validate, and use Fingerprint results in the safety of your server environment. We will use a website as an example, but the same principles also apply to mobile apps.

<Info>
  **Request vs. response replay attacks**

  This guide is designed to prevent replay attacks against your own server endpoints, where the attacker reuses something from the Fingerprint API **response** (`event_id` or `visitor_id`). To prevent **payload** replay attacks targeted against the Fingerprint API, see [Protecting from payload replay attacks](/docs/protecting-from-payload-replay-attacks).
</Info>

## How NOT to integrate Fingerprint

Imagine you are running a survey on your website and you don't want to accept more than one submission from a single browser. A simple implementation vulnerable to client-side tampering might look like this:

<CodeGroup>
  ```html Client theme={"theme":"github-dark-dimmed"}
  <script>
    // Load the Fingerprint JavaScript agent
    const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY').then((Fingerprint) =>
      Fingerprint.start(),
    );

    document
      .getElementById('surveyForm')
      .addEventListener('submit', function (e) {
        e.preventDefault();
        const data = Object.fromEntries(new FormData(e.target));

        // ❌ EXAMPLE OF UNSECURE PRACTICE
        // When the form is submitted, get the visitor ID and
        // send it to the server for processing alongside the form
        fpPromise
          .then((fp) => fp.get())
          .then((result) => {
            console.log(result.visitor_id);

            fetch(`/api/survey`, {
              method: 'POST',
              headers: {
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({
                data,
                visitor_id: result.visitor_id,
              }),
            });
          });
    });
  </script>
  ```

  ```javascript Server theme={"theme":"github-dark-dimmed"}
  export async function POST(request) {
    /**
     * ❌ EXAMPLE OF UNSECURE PRACTICE
     * The visitor_id provided from the client could have been spoofed
     */
    const { visitor_id, data } = (await request.json());
    if (await submissionsDatabase.has(visitor_id)) {
      return Response.json(
        {
          message: 'This browser already participated in the survey',
        },
        { status: 403 },
      );
    }

    submissionsDatabase.set(visitor_id, data);
    return Response.json({ status: 'OK' });
  }
  ```
</CodeGroup>

* A person trying to submit hundreds of votes can bypass your website completely and simply spam requests to `yourwebsite.com/api/survey` using an HTTP library like `cURL` and supplying a random visitor ID with each request.
* Even if you limit your endpoint to only accept requests from your website's origin, an attacker can use a [browser extension](https://chromewebstore.google.com/search/modify%20http%20request) to intercept and modify the in-browser request.

To ensure your server is using a visitor ID generated by Fingerprint, get the identification result securely. The JavaScript agent and mobile SDKs return a limited result. The full set of [Smart Signals](/docs/smart-signals-reference) is available through the delivery mechanisms below.

## Getting the Fingerprint results to your server securely

You have three options to get the Fingerprint results to your server safely:

* **Server API**

  * Pass only the `event_id` from the JavaScript agent to your server, use it to retrieve the full identification event from the [Server API](/reference/server-api).
  * The result authenticity is ensured by direct server-to-server communication.

* **Webhooks**

  * Pass only the `event_id` from the JavaScript agent to your server, use it to wait for the corresponding identification event [Webhook](/docs/webhooks) from Fingerprint.
  * The result authenticity is ensured by direct server-to-server communication.
  * This implementation is the least common. It is usually more complex and has higher latency than Server API or Sealed results. Webhooks are typically used for [event storage](/docs/regions#data-retention).

* **Sealed results**

  * Receive the full identification event in the JavaScript agent as an encrypted [Sealed result](/docs/sealed-client-results). Send it encrypted to your server and decrypt it there using a secret key generated using the Fingerprint Dashboard.
  * The result authenticity is ensured by symmetric encryption.
  * This implementation is faster than Webhooks and Server API (it requires one less HTTP request). It is available for the JavaScript agent and mobile SDKs.

Here is the example from before, now using the [Server API `GET /v4/events/:event_id` endpoint](/reference/server-api-get-event) to safely retrieve the full identification result. For the other alternatives, see [Webhooks](/docs/webhooks) or [Sealed results](/docs/sealed-client-results).

<CodeGroup>
  ```html Client theme={"theme":"github-dark-dimmed"}
  <script>
    const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY').then(
      (Fingerprint) => Fingerprint.start(),
    );

    document
      .getElementById('surveyForm')
      .addEventListener('submit', function (e) {
        e.preventDefault();
        const data = Object.fromEntries(new FormData(e.target));

        /**
         * ✅ EXAMPLE OF GOOD PRACTICE
         * Send only the `event_id` to the server
         */
        fpPromise
          .then((fp) => fp.get())
          .then((result) => {
            fetch(`/api/survey`, {
              method: 'POST',
              headers: {
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({
                data,
                event_id: result.event_id,
              }),
            });
          });
      });
  </script>
  ```

  ```javascript Server theme={"theme":"github-dark-dimmed"}
  export async function POST(request) {
    /**
     * ✅ EXAMPLE OF GOOD PRACTICE
     * Get only the `event_id` from the client and use it
     * to retrieve the full identification event from Server API
     */
    const { event_id, data } = (await request.json());
    const identificationEvent = await (
      await fetch(`https://eu.api.fpjs.io/v4/events/${event_id}`, {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${SUBS.main.serverApiKey}`,
        },
      })
    ).json();

    const visitorId = identificationEvent?.identification?.visitor_id;
    if (!visitorId) {
      throw new Error('Could not retrieve visitor ID.');
    }

    if (await submissionsDatabase.has(visitorId)) {
      return Response.json(
        {
          message: 'You already submitted this survey',
        },
        { status: 403 },
      );
    }

    submissionsDatabase.set(visitorId, data);
    return Response.json({ status: 'OK' });
  }
  ```
</CodeGroup>

At this point, you know you are dealing with a real visitor ID generated by Fingerprint for your application. However, you still need to verify that the event ID belongs to this specific survey submission request. An attacker might have intercepted previously issued event IDs or generated their own using your Public API key. This is known as a "replay attack". They can be prevented by the freshness and consistency checks described below.

<Info>
  **Related: Hiding the Visitor ID from the client completely**

  Hiding the Visitor ID from the client payload makes it harder for malicious actors to reverse-engineer your implementation. You have two options available:

  * Using [Sealed results](/docs/sealed-client-results) to encrypt the payload returned to the JavaScript agent completely.
  * Using [Zero Trust Mode](/docs/zero-trust-mode) to omit the visitor ID and other metadata from the JavaScript agent payload while keeping `event_id` available. Zero Trust Mode requires the [Enterprise plan](https://fingerprint.com/pricing/).
</Info>

## Preventing replay attacks

During a replay attack, an attacker intercepts and retransmits data previously exchanged between Fingerprint and your server.

* When using Webhooks, you can verify that a Webhook request came from Fingerprint using [Basic authentication](/docs/webhooks#legacy-webhook-security) or [Webhook signatures](/docs/webhooks#webhook-signatures). This prevents replay attacks.
* When using Sealed results, an attacker can intercept the sealed result your client sends to your server.
* When using the Server API, an attacker can intercept previously issued event IDs or generate their own using your Public API key.

An attacker can include the intercepted event ID or sealed result with their HTTP request to your server. This would allow them to spoof the visitor ID and other Smart Signals associated with their malicious action. To prevent replay attacks, you have two approaches to choose from (or even combine):

* a) Save all event IDs received from the client (sealed or not) or webhooks into a database. When a new event ID comes in that is already present in the database, reject the request.
* b) Check the freshness of the retrieved identification event and its consistency with the HTTP request itself.

### A) Saving all event IDs to a database

Here is a simplified example of saving the received event ID into a database and processing only previously unseen event IDs.

<CodeGroup>
  ```javascript Server theme={"theme":"github-dark-dimmed"}
    export async function POST(request: Request) {
      /** Get the `event_id` from the request payload (sealed or not) */
      const { event_id } = parseEventId(await request.json());

      // Only process the request if it hasn't been processed before
      if (await eventIdDatabase.has(event_id)) {
        return Response.json(
          { message: 'Already processed this event ID, potential replay attack' },
          { status: 403 },
        );
      }

      await eventIdDatabase.set(event_id, true);
      // Continue processing the request
    }
  ```
</CodeGroup>

> Note: If you are using Sealed results, it's a good idea to pass the unencrypted event ID alongside the sealed result to your server as a fallback. The event ID decrypted from the sealed result must match the one sent without encryption. See [Sealed results](/docs/sealed-client-results) for more details.

### B) Checking the freshness and consistency of the identification result

The code snippets below are simplified for readability, but you can find the full example as used in our use case demos [on GitHub](https://github.com/fingerprintjs/fingerprintjs-pro-use-cases/blob/0589bdd38ba636c897b11fff8d9d9992417b763f/src/server/checks.ts#L186). These are common good practices that you might need to adjust according to your specific use case.

<CodeGroup>
  ```javascript validateFingerprintResult.js theme={"theme":"github-dark-dimmed"}
  /**
   * Validates the consistency of the Fingerprint identification result with the associated HTTP request
   *
   * @param {EventResponse} identificationEvent - The event retrieved from Server API or Sealed result
   * @param {Request} request - The HTTP request (for example, the survey submission request)
   * @returns {{ okay: boolean, error?: string} } - An object indicating the validation result.
   */
  function validateFingerprintResult(identificationEvent, request) {
    const identification = identificationEvent.identification;

    // The expected data might be missing completely.
    if (!identification) {
      return { okay: false, error: 'Identification event not found, potential spoofing attack.' };
    }
    
    // More checks to follow...
    
    return { okay: true };
  }
  ```

  ```javascript validateFingerprintResult.js theme={"theme":"github-dark-dimmed"}
  export async function POST(request: Request) {
    const { event_id, data } = (await request.json()) as Payload;
    const identificationEvent = await (
      await fetch(`https://eu.api.fpjs.io/v4/events/${event_id}`, {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${SUBS.main.serverApiKey}`,
        },
      })
    ).json();

    /**
     * ✅ EXAMPLE OF GOOD PRACTICE
     * Validate the consistency of the Fingerprint identification result with the associated HTTP request
     * Check timestamps, IP, origin and other metadata to prevent replay attacks
     */
    const { okay, error } = validateFingerprintResult(
      identificationEvent,
      request,
    );
    if (!okay) {
      return Response.json({ error }, { status: 403 });
    }

    const visitorId =
      identificationEvent?.identification?.visitor_id;
    if (await submissionsDatabase.has(visitorId)) {
      return Response.json({ message: 'Already submitted' }, { status: 403 });
    }

    submissionsDatabase.set(visitorId, data);
    return Response.json({ status: 'OK' });
  }
  ```
</CodeGroup>

### 1. Check the timestamp

If the identification request associated with the survey submission is too old, reject the request. Pick a time limit suitable for your infrastructure setup and use case.

<CodeGroup>
  ```javascript validateFingerprintResult.js theme={"theme":"github-dark-dimmed"}
    // Check freshness of the identification request to prevent replay attacks.
    const ALLOWED_REQUEST_TIMESTAMP_DIFF_MS = 3000;
    if (Date.now() - identificationEvent.timestamp > ALLOWED_REQUEST_TIMESTAMP_DIFF_MS) {
      return { okay: false, error: 'Old identification request, potential replay attack.' };
    }
  ```
</CodeGroup>

### 2. Check the origin

Both the Fingerprint identification request and the survey submission request should be coming from your website.

<CodeGroup>
  ```javascript validateFingerprintResult.js theme={"theme":"github-dark-dimmed"}
    const identificationOrigin = new URL(identificationEvent.url).origin;
    const requestOrigin = request.headers.get('origin');
    if (
      identificationOrigin !== requestOrigin ||
      identificationOrigin !== 'https://yourwebsite.com' ||
      requestOrigin !== 'https://yourwebsite.com'
    ) {
      return { okay: false, error: 'Unexpected origin, potential replay attack.' };
    }
  ```
</CodeGroup>

> Note: This check assumes the `origin` header is present on the request, which is [not the case](https://fetch.spec.whatwg.org/#origin-header) for `GET` and `HEAD` requests. We recommend omitting the check for these requests.

### 3. Check the IP address

The Fingerprint identification request and the survey submission request should be coming from the same IP address.

<CodeGroup>
  ```javascript validateFingerprintResult.js theme={"theme":"github-dark-dimmed"}
    /**
     * Note: Parsing the user IP from `x-forwarded-for` can be unreliable as
     * any proxy between your server and the visitor can overwrite or spoof the header.
     * In most cases, using the right-most external IP is more appropriate
     * than the left-most one. You might need to adjust or skip
     * this check depending on your use case and server configuration.
     * You can learn more at:
     * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For
     * https://adam-p.ca/blog/2022/03/x-forwarded-for/.
     */
    const parseIp = (request) => {
      const xForwardedFor = request.headers.get('x-forwarded-for');
      const requestIp = Array.isArray(xForwardedFor)
        ? xForwardedFor[0]
        : xForwardedFor?.split(',')[0] ?? '';
      return requestIp;
    };

    const identificationIp = identificationEvent.ip_address;
    const requestIp = parseIp(request);

    // This check currently works only for IPv4 addresses.
    if (IPv4_REGEX.test(requestIp) && identificationIp !== requestIp) {
      return {
        okay: false,
        error: 'Unexpected IP address, potential replay attack.',
      };
    }
  ```
</CodeGroup>

### 4. Optional: Check the confidence score

A confidence score indicates how confident Fingerprint is that the browser (or device) in the request has not been misidentified for another existing browser (or device).

You can use it in your validation logic to only allow users identified above a certain threshold of confidence to perform a sensitive action. See [Understanding your confidence score](/docs/identification-accuracy-and-confidence) for more details.

<CodeGroup>
  ```javascript validateFingerprintResult.js theme={"theme":"github-dark-dimmed"}
    if (identification.confidence.score < env.MIN_CONFIDENCE_SCORE) {
      return { okay: false, error: 'Low confidence score, actions requires 2FA.' };
    }
  ```
</CodeGroup>

## Using Smart Signals

The `validateFingerprintResult` method is a good place to use all the [Smart Signals](/docs/smart-signals-reference) Fingerprint offers for detecting suspicious browser and device configurations.

For example, you can prevent bots, VPN users, Tor browser users, and users tampering with their browser configurations from submitting survey responses:

<CodeGroup>
  ```javascript validateFingerprintResult.js theme={"theme":"github-dark-dimmed"}
    if (identificationEvent.bot === 'bad') {
      return { okay: false, error: 'Malicious bot detected.' };
    }

    if (identificationEvent.vpn === true) {
      return { okay: false, error: 'VPN network detected.' };
    }

    if (identificationEvent.ip_blocklist?.tor_node === true) {
      return { okay: false, error: 'Tor network detected.' };
    }

    if (identificationEvent.tampering === true) {
      return { okay: false, error: 'Browser tampering detected.' };
    }
  ```
</CodeGroup>

## What's next

* Have a look at our [demo collection](https://demo.fingerprint.com/) to see how the patterns in this guide are implemented for specific use cases. The source code is open-source and available [on GitHub](https://github.com/fingerprintjs/fingerprintjs-pro-use-cases/blob/0589bdd38ba636c897b11fff8d9d9992417b763f/src/server/checks.ts#L186).
* If you have more questions about protecting your implementation from tampering and replay attacks, please reach out to our [support team](https://fingerprint.com/support/).

***

[Azure Proxy Integration](/docs/azure-proxy-integration)


# Protecting from payload replay attacks
Source: https://docs.fingerprint.com/docs/protecting-from-payload-replay-attacks

Identify malicious actors that capture and replay the client-side request payload using the replayed flag.

The `replayed` flag is a security mechanism designed to detect and mitigate **replay attacks** by verifying the uniqueness of the payload generated by our **JavaScript agent**. If the same payload is seen more than once, the `replayed` flag is raised **silently**, without exposing any information to the attacker.

## Purpose

This flag helps protect against abuse scenarios where attackers attempt to reuse a previously captured payload to manipulate the output of their visitor ID or Smart Signals. The attacker might be trying to evade your Fingerprint-based site protections or simply cause damage by inflating your API call volume.

<Note>
  **Request vs. response replay attacks**

  The `replayed` flag is designed to prevent payload replay attacks targeted against the Fingerprint API. To prevent replay attacks against your own server endpoints, where the attacker reuses something from the Fingerprint API **response** (`event_id` or `visitor_id`), see [Protecting from client-side tampering](/docs/protecting-from-client-side-tampering).
</Note>

### Prevent replay attacks

The `replayed` flag is specifically designed to detect the reuse of payloads generated by our **JavaScript agent**. If an attacker captures and attempts to reuse one of these payloads to spoof a legitimate `visitor_id`, the system sets the `replayed` flag to `true`.

The `replayed` flag is shown in:

* [Sealed Client Results](/docs/sealed-client-results)
* [Server API responses](/reference/server-api)
* [Webhooks](/docs/webhooks)

See the snippet below for an example of protecting your identification logic and preventing account takeovers, session spoofing, and other impersonation attacks.

Note: When using the [JavaScript agent v4](/reference/js-agent-get-function), serialize `sealed_result` before sending it to your server, for example with `result.sealed_result.base64()`.

```javascript theme={"theme":"github-dark-dimmed"}
// ...
export async function loginHandler(request) {
  const { sealed_result_base64 } = await request.json();
  // see our Sealed Client Results guide for more information
  // /docs/sealed-client-results
  const result = unsealEvent(sealed_result_base64); // result is the event payload

  if (result.replayed) {
    return Response.json(
      { message: "Suspicious identification payload detected." },
      { status: 403 },
    );
  }
  // ...
}
```

### Block fraudulent IP addresses

Replay activity frequently originates from bots or attackers operating behind suspicious IP addresses. By monitoring for the `replayed` flag, you can identify and filter out these potentially malicious sources. A common approach is to set up a webhook that inspects incoming traffic for `replayed: true` flags.

```javascript theme={"theme":"github-dark-dimmed"}
// ...
export async function webhookHandler(request: Request) {
  const event = await request.json();

  if (event.replayed) {
    saveIpForBlocklistExport(event.ip)
  }

  fingerprintWebhookDatabase.add(event);
  return Response.json({ message: 'Webhook received', status: 200 });
}
```

When such a flag is detected, you can save the IP address and temporarily add the associated IP address to our request filtering blocklist through the [Dashboard](/docs/network-request-filtering). The blocklist should be cleared after a few days to prevent false positives caused by IP rotations.

### Notice malicious behavior

Replayed payloads are a strong signal of potentially harmful behavior. While legitimate traffic rarely triggers this flag, attackers using automation or engaging in abusive activity—such as scraping, credential stuffing, or API probing—often might. By tracking and analyzing these replay flags, you can proactively detect and mitigate broader patterns of malicious behavior.

This becomes even more effective when combined with other [Smart Signals](/docs/smart-signals-reference) like [`datacenter`](/docs/smart-signals-reference#ip-geolocation) or [`bot`](/docs/smart-signals-reference#browser-bot-detection).

```sql theme={"theme":"github-dark-dimmed"}
SELECT ip, visitorId, jsonExtract("ip_info", "v4.geolocation.country.code")
FROM my_fingerprint_webhook_backups
WHERE replayed = "true" AND
(
  jsonExtract("bot", "result") = "bad" OR
  jsonExtract("ip_info", "v4.geolocation.datacenter") = "true"
)
```

## Availability

The `replayed` flag is available to **all customers**, as part of our core security feature set.


# Request filtering
Source: https://docs.fingerprint.com/docs/request-filtering

Block unwanted identification requests to prevent malicious actors from misusing your Fingerprint public API keys.

To provide device intelligence, Fingerprint runs on the client device — inside the browser or a mobile app. Client-side code can be easily examined, therefore, the API key you use to make identification requests to Fingerprint is by definition a *public API key*.

To prevent malicious actors from misusing your public API key and inflating your [Fingerprint costs](/docs/billing), you can filter out unwanted identification requests. These requests are not billed and will receive an error instead of the identification result.

* To filter requests from web browsers by **origin** or **HTTP header**, see [Request filtering for websites](/docs/request-filtering-for-websites).
* To filter requests from mobile apps by **package names** or **bundle IDs**, see [Request filtering for mobile apps](/docs/mobile-app-filtering).
* To filter requests from common indexing and AI bots, see [Search bot request filtering](/docs/search-bots-filtering) and [AI bot request filtering](/docs/ai-bot-filtering) respectively.
* To filter requests from a range of IP addresses, see [Network request filtering](/docs/network-request-filtering).

<Warning>
  **We rolled out the beta for [Request Filtering V2](/docs/request-filtering-v2).**

  New iteration of request filtering gives you more flexibility and control when blocking unwanted identification requests. You have full control over order of execution, and you can create more complex rules by using our flexible expression language.
</Warning>

***

What’s Next

* [Start your free workspace now](https://dashboard.fingerprintjs.com/signup/)


# Request filtering for websites
Source: https://docs.fingerprint.com/docs/request-filtering-for-websites



To prevent malicious actors from misusing your public API key, you can [filter out unwanted identification requests](/docs/request-filtering). These requests are not billed and will receive an error instead of the identification result.

This page covers filtering requests made from web browsers. You can filter requests by **website origin** or **HTTP headers**. To block requests from mobile apps, see [Request filtering for mobile apps](/docs/mobile-app-filtering).

## Configuration

Inside the Dashboard, navigate to **Security** in the left-hand menu.

### Filter by website origin

You can create a *blocklist* or *allowlist* of specific origins.

* *Allowlist*: If you only need to use your public API key on a few origins, you should allow only those origins and block all others.
* *Blocklist*: If you need to use your public API key on many origins, you can choose to only block specific origins you suspect might be stealing your API key.

<img alt="Screenshot of how to configure request filtering in the FingerprintJS dashboard" />

To filter requests by origin:

1. Navigate to the **[Security](https://dashboard.fingerprint.com/traffic-rules)** > **Web**.
2. Under **Websites**, click **Configure**.
3. To create an *Allowlist*, set **Default behavior** to  `Forbid all besides origins listed below`. Then fill in the **Exceptions** field with your list of allowed origins.
4. Alternatively, to create a *Blocklist*, set **Default behavior** to  `Allow all besides origins listed below`. Then fill in the **Exceptions** field with your list of blocked origins.
5. Click **Save**.

<img alt="Screenshot of the form required to set up an origin allowlist" />

<Note>
  A website origin is defined by the scheme and the domain name of the URL used to access it.\
  You can use the wildcard character (\*) as a subdomain name.
</Note>

### Filter by HTTP header

You can filter out identification requests by HTTP headers. Requests you might want to filter out include server-side rendering applications, crawlers, search indexing bots, or website availability monitors.

To filter requests by HTTP header:

1. Navigate to the **[Security](https://dashboard.fingerprint.com/traffic-rules)** > **Web**.
2. Under **Forbidden HTTP Headers**, click **Add rule**.
3. Fill in the **Header** name.
4. Choose your **Match Rule**.
5. Fill in the **Value**. You can use regular expressions.

<img alt="Screenshot of the form required to create an HTTP header rule" />

<Note>
  **Regular expressions in header rules**

  The regular expression (regex) match rule is defined by the [RE2](https://github.com/google/re2) notation. To make sure you are using the correct notation, you can:

  1. Go to [regex101.com](https://regex101.com/).
  2. Select the **Golang Flavor** option on the left.
  3. Debug the regular expression to suit your needs.
  4. Copy the **Regular expression** and paste it into the **Value** field in the rule form as-is.
</Note>

## Limitations

* The maximum number of request filtering rules on the web is defined by [Account limits](/docs/billing#account-limits). If you need more request filtering rules, please reach out to our [support team](https://fingerprint.com/support/).
* It can take up to 5 minutes to start filtering incoming requests after creating or editing an origin or header rule.

## Rule Priority and Examples

If *any* rule matches, the request filtering processing stops, and the result is immediately applied. This has clear interaction when only **Forbidden Origins** rules are set up but might be less clear when both **Allowed Origins** and **Forbidden HTTP Headers** rules are involved. The basic precedence is as follows:

1. **Allowed/Forbidden Origins** rules are checked **first**.
2. **Forbidden HTTP Headers** rules are checked **second**.

Let us illustrate that interaction on a more specific example.

### Rules Configuration

We'll configure two different rules

* one is going to whitelist our own website (`https://example.com`) and
* the second one is going to further prohibit any headers coming from `somesocialnetwork` **Referer**.

<img alt="Allowed Origins + Forbidden HTTP Headers rules" />

### Result

Because the **Allowed Origins** rule has strict precedence, we will see the following result.

| Origin                | Headers                        | Result      |
| :-------------------- | :----------------------------- | :---------- |
| `https://example.com` | Referer: somesocialnetwork.com | **`ALLOW`** |

As you can see on the example, the request came through because the **Allow Origins** rule was applied first, and that stopped the processing despite having somesocialnetwork.com as a **Referer**.


# (Beta) Request filtering V2
Source: https://docs.fingerprint.com/docs/request-filtering-v2

Block unwanted identification requests to prevent malicious actors from misusing your Fingerprint public API keys.

New iteration of request filtering gives you more flexibility and control when blocking unwanted identification requests. You have full control over order of execution, and you can create more complex rules by using our flexible expression language.

<Warning>
  Request Filtering V2 is currently in **beta**. This will allow us to validate its functionalities and make improvements before full release. If you want to use it and provide feedback, please follow the [migration guide](#beta-access).
</Warning>

# How it works

With expression-based filtering rules, you can **allow** or **deny** any request that matches the **criteria** in the expression. Every rule takes the form of `[allow | deny] if [expression is true]`.

Rules are evaluated **in order they are listed**:

1. Rule expressions will resolve to a boolean that determines if the rule matches or not.
2. The first rule that matches will determine if the request is allowed or denied.
3. If no rules match, request is allowed by default.

# Configuration

Managing of filtering rules is supported in both the Dashboard and via [Management API](/reference/filteringrulesv2controller_create).

Inside the Dashboard, navigate to [**Security**](https://dashboard.fingerprint.com/traffic-rules) in the left-hand menu.

<img alt="" />

To create a new rule:

1. Click on **Add rule**. New empty rule will be added at the bottom of the page.
2. Select **Allow** or **Deny** if you want this rule to allow or deny the request
3. Write your **Rule expression**. Check some [examples](#examples) or refer to full [reference of expression language](/docs/expression-language-reference).
4. Click on the **Checkmark** to save your rule. If the rule expression is not valid, you will see an error message.
5. To reorder rules, **drag & drop** the rules in the list to your desired order.

<Warning>
  During the beta phase, UI options for managing rules are limited. With full release, you can expect a more versatile editor with validation and autocomplete.
</Warning>

# Examples

Here are some examples of most common use cases which should cover all functionalities from the old version of request filtering rules. Check out **Expression language [reference](/docs/expression-language-reference)** for full list of available data points, operators and functions.

### Domain filtering

Domains are accessible in the `Origin` request header.

* **Allow** requests from **subdomain.example.com**
  * `[allow] http.request.headers['Origin'][0] == 'https://subdomain.example.com'`

### Network filtering

IP address is available in `http.request.ip`. It is a special type and needs to be compared to a valid CIDR notation.

* **Allow** requests from **123.0.0.1**
  * `[allow] http.request.ip in cidr('123.0.0.1/32')`
* **Deny** requests from **123.0.0.1/16**
  * `[deny] http.request.ip in cidr('123.0.0.1/16')`

### Mobile app filtering

Bundle identifiers for mobile apps are available in `sdk.platform.app_package_name`.

* **Allow** requests from **com.acme.default**
  * `[allow] sdk.platform.app_package_name == 'com.acme.default'`

### Request header filtering

Request headers are available in `http.request.headers` and will contain any custom headers you're sending.

* **Allow** requests from testing environments
  * `[allow] http.request.headers['X-ENV'] == 'test'`
* **Deny** requests referred from example.com
  * `[deny] http.request.headers['Referer'] contains 'example.com'`

### Bots filtering

Requests identified as bots have boolean flags exposed in `http.user_agent` map.

* **Allow** requests from **AI bots**
  * `[allow] http.user_agent.is_ai_bot`
* **Deny** requests from **crawler bots**
  * `[deny] http.user_agent.is_crawler_bot`

### Regular expressions

You can use [regular expressions](https://github.com/google/re2/wiki/Syntax) to search for string values that match a given pattern. When using regular expression, rule needs to use `matches` keyword, and the pattern string needs to be enclosed using backticks (`` ` ``) instead of regular quotation marks.

* **Deny** requests from any subdomain on \***.example.com**
  * `` [deny] http.request.headers['Origin'][0] matches `^https://\S+\.example\.com$` ``
* **Allow** requests from all apps with root identifier **com.acme.**\*
  * `` [deny] sdk.platform.app_package_name matches `^com\.acme\..*$` ``

### Multiple conditions

With logical operators, you can chain multiple conditions into a single expression.

Use the `&&` operator to indicate **AND** operator, and `||` operator to indicate **OR** operator.

* **Deny** requests from **specific IP address on a specific domain**
  * `[deny] http.request.ip in cidr('123.0.0.1/32') && http.request.headers['Origin'][0] == 'https://example.com'`
* **Deny** requests from **either AI or crawler bots**
  * `[deny] http.user_agent.is_crawler_bot || http.user_agent.is_ai_bot`

## Limitations

The maximum number of request filtering rules on the web is defined by [Account limits](/docs/billing#account-limits). If you need more request filtering rules, please reach out to our [support team](https://fingerprint.com/support/).

In addition, there are additional limitations regarding specific rule expressions:

* Max rule expression length: 1024 characters
* Max number of regular expression patterns allowed in a single expression: 10

# Beta access

Request filtering V2 is currently in **beta**, which means that we are still refining the scope and functionalities. If you want access to the flexibility and control the new system offers with expression-based rules, you can contact support to enable you access to Request Filtering V2.

## Migration steps

1. Once you have access, open the Dashboard and navigate to [**Security**](https://dashboard.fingerprint.com//traffic-rules).
2. Click on **Try out V2**. This will prompt you to confirm the migration process.
3. Once migration is complete, all **settings from V1 will be copied to V2**.
4. Enjoy the flexibility of new filtering rules!

You can undo the migration in case you didn't like the new system.

1. Click on **Switch back to V1**. This will prompt you to confirm rolling back to previous version.
2. Your settings will be **restored to the moment before you migrated to V2**. This means any changes you made in V2 will be discarded.
3. If you did revert back, please provide some feedback on how we can improve things.

***

[Network request filtering](/docs/network-request-filtering)


# Sealed Client Results
Source: https://docs.fingerprint.com/docs/sealed-client-results

Receive an encrypted payload in the JavaScript agent with all information available in the /v4/events endpoint, meant to be decrypted and used on your backend.

<Info>
  **Availability**

  * JavaScript agent version [**4.0.0**+](/docs/changelog-javascript-agent#v4-0-0)
  * iOS SDK version [**2.7.0+**](/docs/changelog-ios-sdk#v2-7-0)
  * Android SDK version [**2.7.0+**](/docs/changelog-android-sdk#v2-7-0)
</Info>

## How Sealed Client Results work

Sealed Client Results is an alternative delivery mechanism for information normally available only through our [Server API](/reference/server-api-get-event). Usually, you would need to call the Server API on your backend to:

* Validate the authenticity of the visitor ID and other information sent from the client.
* Get the full identification event, including [Smart Signals](/docs/smart-signals-reference).

With Sealed Results, the client agent response payload contains the same JSON structure that is available through the [`/v4/events` Server API](/reference/server-api-get-event) endpoint. This has two main advantages:

* Reduced end-to-end latency — unsealing the result happens on your server, no need to call the Server API.
* Increased secrecy — the payload is fully encrypted with a symmetric key, making it impossible for a malicious actor to read or modify the results on the client, similar to [Zero Trust Mode](/docs/zero-trust-mode).

Sealed results make it faster, safer, and more straightforward to integrate Fingerprint Identification results into your application.

## Data flow

<Frame>
  <img />
</Frame>

## Configuring Sealed Client Results

If you want to use Sealed Client Results, complete the following steps (the order is important):

1. Find an **Encryption key** for your environment in the Dashboard.
2. Set up your backend to accept Sealed Results and decrypt them with that key.
3. Prepare your frontend to start sending the encrypted payload to the backend.
4. Activate the **Encryption key** in the Dashboard to start receiving Sealed Client Results in the JavaScript agent response.

### Step 1: Find an encryption key in the Dashboard

Navigate to **Dashboard** > **[API Keys](https://dashboard.fingerprint.com/api-keys)** > **Sealed Client Results**.

<img alt="" />

You will see a list of **inactive encryption keys**, with each environment having a single key associated with it.

Copy the **Encryption key** in its **base64** representation to use on your backend.

<Warning>The **Encryption key** should remain `Inactive` for now.</Warning>

### Step 2: Decrypt and validate the `sealed_result` payload on your backend

Once the payload arrives at your backend, it needs to be **decrypted using the Encryption key found in the previous step**.

In JavaScript agent v4, `sealed_result` is returned as `BinaryOutput`, not as a string. Before sending it to your server, serialize it with one of the `BinaryOutput` methods:

* `base64()`
* `byteArray()`
* `blob()`
* `toString()`
* `toJSON()`

The examples below use `base64()`. The base64 payload has a format covered in [Appendix: Payload format](#appendix-payload-format).

The easiest way to decrypt the sealed result is to use one of our [Server SDKs](/reference/server-sdks).

<CodeGroup>
  ```javascript Node SDK theme={"theme":"github-dark-dimmed"}
  // Requires Node SDK v7.0 or higher
  const { unsealEventsResponse, DecryptionAlgorithm } = require('@fingerprint/node-sdk');

  async function main() {
    const sealedDataBase64 = process.env.BASE64_SEALED_RESULT;
    const decryptionKey = process.env.BASE64_KEY;

    if (!sealedDataBase64 || !decryptionKey) {
      console.error('Please set BASE64_KEY and BASE64_SEALED_RESULT environment variables');
      process.exit(1);
    }

    try {
      const unsealedData = await unsealEventsResponse(Buffer.from(sealedDataBase64, 'base64'), [
        {
          key: Buffer.from(decryptionKey, 'base64'),
          algorithm: DecryptionAlgorithm.Aes256Gcm,
        },
      ]);
      console.log(JSON.stringify(unsealedData, null, 2));
    } catch (e) {
      console.error(e);
      process.exit(1);
    }
  }

  main();

  ```

  ```php PHP SDK theme={"theme":"github-dark-dimmed"}
  <?php
  // Requires PHP SDK v7.0 or higher

  use Fingerprint\ServerSdk\Sealed\DecryptionAlgorithm;
  use Fingerprint\ServerSdk\Sealed\DecryptionKey;
  use Fingerprint\ServerSdk\Sealed\Sealed;

  require_once(__DIR__ . '/vendor/autoload.php');

  $sealed_result_bytes = base64_decode($_ENV['BASE64_SEALED_RESULT']);
  $sealed_key = base64_decode($_ENV['BASE64_KEY']);

  try {
      $data = Sealed::unsealEventResponse($sealed_result_bytes, [new DecryptionKey($sealed_key, DecryptionAlgorithm::AES_256_GCM)]);

      fwrite(STDOUT, sprintf("Unsealed event: %s \n", $data));
  } catch (Exception $e) {
      fwrite(STDERR, sprintf("Exception when unsealing event: %s\n", $e->getMessage()));
      exit(1);
  }
  ```

  ```go Go SDK theme={"theme":"github-dark-dimmed"}

  package main

  import (
    "encoding/base64"
    "fmt"
    "os"

    // Requires Go SDK v8 or higher
    "github.com/fingerprintjs/go-sdk/v8"
  )

  // Utility function to decode base64 string
  func base64Decode(input string) []byte {
    output, err := base64.StdEncoding.DecodeString(input)
    if err != nil {
      panic(err)
    }
    return output
  }

  func main() {
    // Sealed result from the frontend.
    sealedResultBytes := base64Decode(os.Getenv("BASE64_SEALED_RESULT"))
    // Base64 encoded key generated in the dashboard.
    key := base64Decode(os.Getenv("BASE64_KEY"))

    keys := []fingerprint.DecryptionKey{
      // You can provide more than one key to support key rotation. The SDK will try to decrypt the result with each key.
      {
        Key:       key,
        Algorithm: fingerprint.AlgorithmAES256GCM,
      },
    }
    unsealedResponse, err := fingerprint.UnsealEventsResponse(sealedResultBytes, keys)

    if err != nil {
      panic(err)
    }

    // Do something with unsealed response, e.g: send it back to the frontend.
    fmt.Println(unsealedResponse)
  }
  ```

  ```java Java SDK theme={"theme":"github-dark-dimmed"}
  // Requires Java SDK v8.0.0 or higher
  package com.fingerprint.example;

  import com.fingerprint.v4.Sealed;
  import com.fingerprint.v4.model.Event;

  import java.util.Base64;

  public class SealedResults {
      public static void main(String... args) throws Exception {
          // Sealed result from the frontend.
          String SEALED_RESULT_BASE64 = System.getenv("BASE64_SEALED_RESULT");

          // Base64 encoded key generated in the dashboard.
          String SEALED_KEY = System.getenv("BASE64_KEY");

          final Event event = Sealed.unsealEventResponse(
                  Base64.getDecoder().decode(SEALED_RESULT_BASE64),
                  // You can provide more than one key to support key rotation. The SDK will try to decrypt the result with each key.
                  new Sealed.DecryptionKey[]{
                          new Sealed.DecryptionKey(
                                  Base64.getDecoder().decode(SEALED_KEY),
                                  Sealed.DecryptionAlgorithm.AES_256_GCM
                          )
                  }
          );

          System.out.println(event);
      }
  }
  ```

  ```csharp C# .NET SDK theme={"theme":"github-dark-dimmed"}
  // Requires .NET SDK v8.0.0 or higher
  using System.Text.Json;
  using Fingerprint.ServerSdk;

  var sealedResultBase64 = Environment.GetEnvironmentVariable("BASE64_SEALED_RESULT")!;
  var sealedKey = Environment.GetEnvironmentVariable("BASE64_KEY")!;

  var eventResponse = Sealed.UnsealEventResponse(Convert.FromBase64String(sealedResultBase64), new[]
  {
      new Sealed.DecryptionKey(Convert.FromBase64String(sealedKey), Sealed.DecryptionAlgorithm.Aes256Gcm)
  });

  Console.WriteLine(JsonSerializer.Serialize(eventResponse));
  ```

  ```python Python SDK theme={"theme":"github-dark-dimmed"}
  # Requires Python SDK v9.0 or higher
  import base64
  import os

  from dotenv import load_dotenv

  from fingerprint_server_sdk import unseal_event_response, DecryptionKey, DecryptionAlgorithm

  load_dotenv()

  sealed_result_bytes = base64.b64decode(os.environ["BASE64_SEALED_RESULT"])
  key = base64.b64decode(os.environ["BASE64_KEY"])

  try:
      event_response = unseal_event_response(sealed_result_bytes, [DecryptionKey(key, DecryptionAlgorithm['Aes256Gcm'])])
      print("\n\n\nEvent response: \n", event_response)
  except Exception as e:
      print("Exception when calling unseal_event_response: %s\n" % e)
      exit(1)

  print("Unseal successful!")

  exit(0)
  ```
</CodeGroup>

If you prefer to write the decryption code yourself, see the [Appendix](#appendix-payload-format) at the end of this page for some examples. The SDKs are open-source so you can also refer to their source code on GitHub.

<Warning>
  **Never decrypt the payload in the browser**

  The decryption is designed to work on the **backend only**. If you try to decrypt the payload on the client, it means that anyone can see the shared key. That opens the possibility to read and alter the payload, exposing sensitive information and introducing new attack vectors.
</Warning>

### Step 3: Send `sealed_result` to your backend

Adjust your client code to serialize and send the `sealed_result` received from the Fingerprint JavaScript agent to the server endpoint you prepared in the previous step:

<CodeGroup>
  ```javascript Client Code theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  const fp = Fingerprint.start({
    apiKey: "PUBLIC_API_KEY"
  });

  fp.get()
    .then(fingerprint => {
      if (!fingerprint.sealed_result) {
        throw new Error("Sealed Client Results are not available for this response")
      }

      const sealed_result_base64 = fingerprint.sealed_result.base64()
      fetch("https://your-backend.com/sealed", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          event_id: fingerprint.event_id,
          sealed_result_base64,
        })
      })
        .then(response => console.log("Finished with status: ", response.status))
    })
    .catch(err => console.error("Failed to complete Sealed Client Results flow with error: ", err));
  ```

  ```json Response theme={"theme":"github-dark-dimmed"}
  {
    "event_id": "1748472295686.1yRrKC",
    "sealed_result_base64": "<base64-serialized encrypted event payload>"
  }
  ```
</CodeGroup>

<Info>
  **Server API Fallback**

  You may also consider sending the `event_id` that is returned in the regular JavaScript agent response to support the fallback to [Server API](/reference/server-api) request if something goes wrong and `sealed_result` is not available.
</Info>

### Step 4: Activate the encryption key in the Dashboard

Once the backend is set up to accept and decrypt incoming traffic, and the frontend contains code to send the `sealed_result` to the backend, you can activate your **Encryption key**.

1. Navigate to **Dashboard** > **[API Keys](https://dashboard.fingerprint.com/api-keys)** > **Sealed Client Results**.
2. Find the key you want to activate, click `...` and select **Activate**.
3. Once active, all events from the associated environment will be sealed using the encryption key.

<img alt="" />

That completes the setup and the `sealed_result` payload should start flowing from your client to your backend. Note that the key propagation could take a few minutes to finish so don't worry if you don't see the `sealed_result` payload immediately after the key got activated.

<Warning>
  When a key is activated, the JavaScript agent removes everything except `event_id` and
  `sealed_result` from the payload. Make sure that there is nothing left on the client that depends
  on the original (unencrypted) payload **before activating** the first key.
</Warning>

## Sealed Client Results with multiple environments

Sealed results are scoped to a specific **environment**. When creating an environment, an **inactive encryption key** will be automatically generated.

By activating encryption keys, you are selecting on which environment you want payload to be encrypted. If you're utilizing multiple environments, this means you can partially select for which environment you want to turn on Sealed Client Results.

Payloads will only be encrypted on environments with an active encryption key. On other environments, payload will remain unchanged.

This is beneficial if you would like to incrementally integrate Sealed Client Results into your multi-environment setup, or if you'd like to test Sealed Client Results on a smaller chunk of traffic before rolling it out everywhere.

## Key Rotation

We recommend creating a regular process for key rotation to prevent potential misuse. The generated keys don't expire but it is advised to rotate the key every 3 months, or before reaching a total of 4 billion requests, or if the key might have leaked (whatever comes first).

In all cases, follow these steps:

1. Navigate to **Dashboard** > **[API Keys](https://dashboard.fingerprint.com/api-keys)** > **Sealed Client Results**.
2. Find the key you want to rotate, click `...` and select **Rotate**.
3. In the dialog, you will find the **new key** that will replace the existing key after the rotation. Save the value of the next key and you can safely close the dialog.
4. **Update the backend** to try unsealing with both the old (original) and the new key.
5. Once your backend is ready to work with the new key, return to the dashboard and re-open the rotation dialog from step 2.
6. Click on **Rotate**. The old key is deactivated as there cannot be more than one key active at a time.
7. Wait a few moments until your backend starts receiving results sealed with the new key exclusively. Optionally, you can then completely remove the old key from the backend logic.

<img alt="" />

In case you accidentally finished a rotation too early, you can **Revert** back to the previous key you used before rotation.

1. Find the key you rotated, click `...` and select **Revert**.
2. In the dialog, you will find the **previous key** that you will be reverting to.
3. Click on **Revert** to confirm the action.

## Replay attack protection

**Sealed Client Results** don't add any protection against possible replay attacks. However, the feature makes it easy to implement replay attack protection.

With Sealed Client Results, you only need to check if the `event_id` retrieved from the `sealed_result` contains a unique and previously unseen value. Because the sealed payload cannot be modified, the `event_id` is always valid and genuine.

Additionally, you can also check the `timestamp` field to further validate the authenticity of the request. The time difference between `timestamp` and the current time should not surpass a reasonably low threshold.

## Disabling Sealed Client Results

You can turn off Sealed Client Results simply by disabling the **Encryption key** in the Dashboard.

<Warning>
  **Disabling the Encryption key will immediately stop payload encryption**

  Make sure that your integration can support handling unencrypted payload before you disable the encryption key.
</Warning>

If you've disabled the Encryption key by accident, you can re-enable the key to prevent any damage to your integration.

Once disabled, keys **cannot be deleted for 72 hours** from last deactivation. This is to make sure you can still reactivate keys in time if you need to update your integration.

If you need any assistance with disabling Sealed Client Results, please contact our [support team](https://fingerprint.com/support/).

<Check>
  **Implementation example**

  See our VPN detection [use case demo](https://demo.fingerprint.com/vpn-detection?utm_content=sealed-client-results) and [tutorial](https://fingerprint.com/blog/vpn-detection-location-spoofing-fraud-prevention?utm_content=sealed-client-results) for a practical example of Sealed results implementation. The demo is open-source and available [on GitHub](https://github.com/fingerprintjs/fingerprintjs-pro-use-cases/tree/main/src/app/vpn-detection).
</Check>

## Appendix: Payload format

After serializing `sealed_result` using `base64()`, the value is a **base64** representation of the following binary structure:

<Frame>
  <img />
</Frame>

* \[4 Bytes] Version header (currently set to `0x9E85DCED`)
  * You can use the version header to check that you are processing the correct version of the payload but it isn't part of the encrypted section. In rare cases where we introduce breaking changes to the payload structure, the version header will also get a new value (along with a way to pick which version you want to consume to ensure a smooth transition between different versions).

* `/v4/events` Payload sealed with **AES-256-GCM**
  * \[12 Bytes] Nonce/Initialization Vector
  * Encrypted `/v4/events` JSON payload, compressed with [raw deflate](https://datatracker.ietf.org/doc/html/rfc1951)
  * \[16 Bytes] Authentication Tag

See our reference implementation that unseals and decompresses the payload, while printing out debug output with intermediate steps:

<CodeGroup>
  ```javascript Unsealing in Node.js theme={"theme":"github-dark-dimmed"}
  import * as crypto from 'crypto'
  import { promisify } from 'util'
  import * as zlib from 'zlib'

  const sealedResultBase64 = "noXc7SXO+mqeAGrvBMgObi/S0fXTpP3zupk8qFqsO/1zdtWCD169iLA3VkkZh9ICHpZ0oWRzqG0M9/TnCeKFohgBLqDp6O0zEfXOv6i5q++aucItznQdLwrKLP+O0blfb4dWVI8/aSbd4ELAZuJJxj9bCoVZ1vk+ShbUXCRZTD30OIEAr3eiG9aw00y1UZIqMgX6CkFlU9L9OnKLsNsyomPIaRHTmgVTI5kNhrnVNyNsnzt9rY7fUD52DQxJILVPrUJ1Q+qW7VyNslzGYBPG0DyYlKbRAomKJDQIkdj/Uwa6bhSTq4XYNVvbk5AJ/dGwvsVdOnkMT2Ipd67KwbKfw5bqQj/cw6bj8Cp2FD4Dy4Ud4daBpPRsCyxBM2jOjVz1B/lAyrOp8BweXOXYugwdPyEn38MBZ5oL4D38jIwR/QiVnMHpERh93jtgwh9Abza6i4/zZaDAbPhtZLXSM5ztdctv8bAb63CppLU541Kf4OaLO3QLvfLRXK2n8bwEwzVAqQ22dyzt6/vPiRbZ5akh8JB6QFXG0QJF9DejsIspKF3JvOKjG2edmC9o+GfL3hwDBiihYXCGY9lElZICAdt+7rZm5UxMx7STrVKy81xcvfaIp1BwGh/HyMsJnkE8IczzRFpLlHGYuNDxdLoBjiifrmHvOCUDcV8UvhSV+UAZtAVejdNGo5G/bz0NF21HUO4pVRPu6RqZIs/aX4hlm6iO/0Ru00ct8pfadUIgRcephTuFC2fHyZxNBC6NApRtLSNLfzYTTo/uSjgcu6rLWiNo5G7yfrM45RXjalFEFzk75Z/fu9lCJJa5uLFgDNKlU+IaFjArfXJCll3apbZp4/LNKiU35ZlB7ZmjDTrji1wLep8iRVVEGht/DW00MTok7Zn7Fv+MlxgWmbZB3BuezwTmXb/fNw=="
  const sealedResult = Buffer.from(sealedResultBase64, 'base64')
  const sealedHeader = Buffer.from('9E85DCED', 'hex')
  const key = Buffer.from('p2PA7MGy5tx56cnyJaFZMr96BCFwZeHjZV2EqMvTq53=', 'base64')

  if (sealedResult.subarray(0, sealedHeader.length).toString('hex') !== sealedHeader.toString('hex')) {
  process.stderr.write('Wrong header\n')
  process.exit(1)
  }

  const nonceLength = 12
  const authTagLength = 16
  const nonce = sealedResult.subarray(sealedHeader.length, sealedHeader.length + nonceLength)
  const ciphertext = sealedResult.subarray(sealedHeader.length + nonceLength, -authTagLength)
  const authTag = sealedResult.subarray(-authTagLength)

  const decipher = crypto.createDecipheriv('aes-256-gcm', key, nonce).setAuthTag(authTag)
  const compressed = Buffer.concat([decipher.update(ciphertext), decipher.final()])
  process.stdout.write('Decrypted/compressed:\n')
  process.stdout.write(compressed.toString('base64'))
  process.stdout.write('\n')

  const payload = await promisify(zlib.inflateRaw)(compressed)
  process.stdout.write('\nDecompressed:\n')
  process.stdout.write(payload)
  process.stdout.write('\n')

  ```

  ```go Unsealing in Go theme={"theme":"github-dark-dimmed"}
  package main

  import (
      "bytes"
      "compress/flate"
      "crypto/aes"
      "crypto/cipher"
      "encoding/base64"
      "fmt"
      "io"
      "log"
      "net/http"

      "github.com/pkg/errors"
  )

  var (
      sealHeader = []byte{0x9E, 0x85, 0xDC, 0xED}
      ErrHeaderUnknown = errors.New("unknown header")
  )

  // The main function is not part of the unsealing process, it's a usage example
  func main() {
      base64Decode := func(input string) []byte {
          output, err := base64.StdEncoding.DecodeString(input)
          if err != nil {
              panic(err)
          }
          return output
      }

      unsealResponse := func(w http.ResponseWriter, r *http.Request) {
          b, err := io.ReadAll(r.Body)
          if err != nil {
              panic(err)
          }

          sealedResult := base64Decode(string(b))

          // Encryption key generated in step 1
          key := base64Decode("<encryption key>")

          unsealed, err := Unseal(sealedResult , key)
          if err != nil {
              panic(err)
          }

          fmt.Println(string(unsealed))

          w.WriteHeader(200)
      }

      http.HandleFunc("/sealed", unsealResponse)

      log.Fatal(http.ListenAndServe(":3030", nil))
  }

  func Unseal(sealed, key []byte) ([]byte, error) {
      if !bytes.Equal(sealed[:len(sealHeader)], sealHeader) {
          return nil, ErrHeaderUnknown
      }

      compressed, err := decrypt(sealed[len(sealHeader):], key)
      if err != nil {
          return nil, errors.Wrap(err, "decrypt")
      }

      payload, err := decompress(compressed)
      if err != nil {
          return nil, errors.Wrap(err, "decompress")
      }

      return payload, nil
  }

  func decrypt(payload, key []byte) ([]byte, error) {
      block, err := aes.NewCipher(key)
      if err != nil {
          return nil, errors.Wrap(err, "new cipher")
      }

      aesgcm, err := cipher.NewGCM(block)
      if err != nil {
          return nil, errors.Wrap(err, "new GCM")
      }

      if len(payload) < aesgcm.NonceSize() {
          return nil, errors.New("nonce")
      }

      nonce, ciphertext := payload[:aesgcm.NonceSize()], payload[aesgcm.NonceSize():]
      plaintext, err := aesgcm.Open(nil, nonce, ciphertext, nil)
      if err != nil {
          return nil, errors.Wrap(err, "aesgcm open")
      }

      return plaintext, nil
  }

  func decompress(compressed []byte) ([]byte, error) {
      reader := flate.NewReader(bytes.NewReader(compressed))
      defer reader.Close()

      decompressed, err := io.ReadAll(reader)
      if err != nil {
          return nil, errors.Wrap(err, "inflated payload read all bytes")
      }

      return decompressed, nil
  }
  ```
</CodeGroup>


# Search bot request filtering
Source: https://docs.fingerprint.com/docs/search-bots-filtering

Allow basic search bots filtering through a single switch in the Request Filtering Dashboard section

Search bots generate legitimate internet traffic allowing search engines to index your website. But you might not want search bots to trigger Fingerprint Identification or Smart Signals processing.

Although you can [filter requests based on the `User-Agent` header](/docs/request-filtering-for-websites#filter-by-http-header), you would need to manage your list of all different search bot `User-Agent` strings. Instead, we keep and update our own list of search bot filtering rules that **can be turned on or off through a switch in the Dashboard**.

Search bots that are filtered through this setting then behave in the same way as other request filtering rules and you don't get billed for them. Keep in mind that we won't return any information except `requestId` in those cases.

<Note>
  Search bots filtering based on `User-Agent` is a basic mechanism we provide for free to filter out commonly encountered and generally well behaved search bots.
  Because of its simplicity, it might introduce both **false positive and false negative** cases. If you need **better protection against sophisticated bots**, check out our [Smart Signals that contain a paid Bot Detection product](/docs/smart-signals-reference#browser-bot-detection).
</Note>

## Configuration

Search Bots Filtering can be turned on or off in our Dashboard.

1. Navigate to **Dashboard** > **[Security](https://dashboard.fingerprint.com/traffic-rules)** and switch to the **Bots** tab.
2. Enable **Exclude Search Bots** to start filtering search bots from your billable API calls.

<img alt="Dashboard - Search Bots Filtering" />

## List of supported search bots `User-Agent` strings

The list of search bots`User-Agent` strings we support is public and we keep it updated based on the currently supported `User-Agent` strings. The following table contains all supported `User-Agent` strings with their respective information sources.

| Owner      | User-Agent (Substrings)                                                                                                                                                                                                                                                                                                    | Public doc                                                                                     |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Mail.ru    | `mail.ru`                                                                                                                                                                                                                                                                                                                  | [source](https://help.mail.ru/webmaster/indexing/robots/robot_log)                             |
| Microsoft  | `bingbot`<br />`AdIdxBot`<br />`MicrosoftPreview`                                                                                                                                                                                                                                                                          | [source](https://www.bing.com/webmasters/help/which-crawlers-does-bing-use-8c184ec0)           |
| Apple      | `applebot`                                                                                                                                                                                                                                                                                                                 | [source](https://support.apple.com/en-us/HT204683)                                             |
| Huawei     | `petalbot`                                                                                                                                                                                                                                                                                                                 | [source](https://webmaster.petalsearch.com/site/petalbot)                                      |
| Naver      | `naver.me/spd`                                                                                                                                                                                                                                                                                                             | [source](https://help.naver.com/service/5626/contents/8026)                                    |
| Yahoo      | `slurp`                                                                                                                                                                                                                                                                                                                    | [source](https://help.yahoo.com/kb/SLN22600.html)                                              |
| Baidu      | `baiduspider`                                                                                                                                                                                                                                                                                                              | [source](https://www.baidu.com/search/robots_english.html)                                     |
| Sogou      | `sogou web spider`<br />`sogou wap spider`<br />`sogou pic spider`                                                                                                                                                                                                                                                         | [source](https://help.sogou.com/spider.html)                                                   |
| Exalead    | `exabot`                                                                                                                                                                                                                                                                                                                   | [source](https://www.exalead.com/search/webmasterguide)                                        |
| Coccoc     | `coccocbot`                                                                                                                                                                                                                                                                                                                | [source](https://help.coccoc.com/en/search-engine/coccoc-robots)                               |
| Seznam     | `seznamBot`                                                                                                                                                                                                                                                                                                                | [source](https://napoveda.seznam.cz/cz/fulltext-hledani-v-internetu/seznambot)                 |
| Google     | `googlebot`<br />`AdsBot-Google`<br />`Storebot-Google`<br />`APIs-Google`<br />`AdsBot-Google-Mobile`<br />`Mediapartners-Google`<br />`Googlebot-Image`<br />`Googlebot-News`<br />`Googlebot-Video`<br />`AdsBot-Google-Mobile-Apps`<br />`FeedFetcher-Google`<br />`Google-Read-Aloud`<br />`Google-Site-Verification` | [source](https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers) |
| Yandex     | `yandex.com/bots`                                                                                                                                                                                                                                                                                                          | [source](https://yandex.com/support/webmaster/robot-workings/check-yandex-robots.html)         |
| Bytedance  | `bytespider`                                                                                                                                                                                                                                                                                                               | [source](https://zhanzhang.toutiao.com/docs/intro/26899)                                       |
| Duckduckgo | `duckduckbot`                                                                                                                                                                                                                                                                                                              | [source](https://duckduckgo.com/duckduckgo-help-pages/results/duckduckbot/)                    |
| Ahrefs     | `AhrefsBot`<br />`AhrefsSiteAudit`                                                                                                                                                                                                                                                                                         | [source](https://ahrefs.com/robot)                                                             |
| Facebook   | `facebookexternalhit`<br />`facebookcatalog`                                                                                                                                                                                                                                                                               | [source](https://developers.facebook.com/docs/sharing/webmasters/crawler/)                     |
| Pinterest  | `Pinterestbot`                                                                                                                                                                                                                                                                                                             | [source](https://help.pinterest.com/en/business/article/pinterest-crawler)                     |
| Cincraw    | `Cincraw`                                                                                                                                                                                                                                                                                                                  | [source](https://cincrawdata.net/bot/)                                                         |
| Semrush    | `http://www.semrush.com/bot.html`                                                                                                                                                                                                                                                                                          |                                                                                                |
| Seekport   | `SeekportBot`                                                                                                                                                                                                                                                                                                              | [source](https://bot.seekport.com/)                                                            |
| Amazon     | `Amazonbot/0.1`<br />`amazonproductbot`                                                                                                                                                                                                                                                                                    | [source](https://developer.amazon.com/support/amazonbot)                                       |
| DataDog    | `datadog`                                                                                                                                                                                                                                                                                                                  | [source](https://docs.datadoghq.com/synthetics/guide/identify_synthetics_bots)                 |


# Segment Data Integration
Source: https://docs.fingerprint.com/docs/segment



<Warning>
  ### Segment integration does not support JavaScript agent v4

  The Segment integration currently supports JavaScript agent v3 only. For the
  v3 documentation, see [Segment Data Integration (v3)](/docs/v3/segment).
</Warning>


# Server API
Source: https://docs.fingerprint.com/docs/server-api





# Backend libraries
Source: https://docs.fingerprint.com/docs/server-sdks





# Smart Signals introduction
Source: https://docs.fingerprint.com/docs/smart-signals-introduction

Smart Signals give you actionable device intelligence for browsers and devices

In addition to visitor identification, Fingerprint provides actionable device intelligence insights called Smart Signals. They provide details on suspicious browser or device configurations, which can indicate malicious intent. For example, you can detect bots, VPN usage, tampered browsers, or jailbroken iPhones and adjust your business logic accordingly. Read our [blog post](https://fingerprint.com/blog/power-of-smart-signals-fraud-detection-prevention/) to learn how to get the most out of Smart Signals.

## Availability

The availability of each Smart Signal depends on the platform (Browser, Android, or iOS) and your [billing plan](https://fingerprint.com/pricing/).

* Smart Signals for Android are included on our Free plan, allowing you to start evaluating device integrity at no cost.
* Most Smart Signals are available in the Pro Plus plan. The [Raw Device Attributes](/docs/smart-signals-reference#raw-device-attributes) signal is currently only available for Enterprise customers.
* Enterprise plans are customized for each customer. If you are an Enterprise customer interested in one or more of these signals, please contact our [support team](https://fingerprint.com/support/) to enable them for you. Signing up for an Enterprise plan does not automatically enable all Smart Signals.

See [Pricing](https://fingerprint.com/pricing/) or [Smart Signals Reference](/docs/smart-signals-reference) for more details.

## Setup and Usage

Smart Signals are computed using the same device attributes collected for visitor identification. If you haven't already, [install the JavaScript agent on your website](/docs/install-the-javascript-agent), or add the [Android](/docs/native-android-integration), or [iOS](/docs/ios) agent to your mobile app to make identification requests.

Unlike the visitor ID, Smart Signals are *not available* in the identification response sent back to the client agents. Because Smart Signals are focused on fraud detection, we only make them available through our [Server API](/reference/server-api-get-event), [Webhooks](/docs/webhooks), and [Sealed Client Results](/docs/sealed-client-results) so we can ensure you receive those results unaltered.

For example, you can:

1. Get the [`event_id`](/reference/js-agent-get-function#event_id) from the JavaScript agent identification response and pass it to your server.
2. Call the [GET `/v4/events/:event_id`](/reference/server-api-get-event) endpoint from your server-side environment and retrieve the Smart Signals in the API response.
3. Use the Smart Signals information in your fraud prevention logic.

Some signals apply to all platforms and some are specific to browsers, Android, or iOS devices. You can see a brief overview of all available signals in the tables below. For detailed information about each signal, see the [Smart Signals Reference](/docs/smart-signals-reference).

## Suspect Score

Suspect Score is a quick and easy way to integrate Smart Signals into your fraud protection workflow. It is a weighted average of all Smart Signals indicating how unusual or suspicious the device is in a single number.

The more Smart Signals return a positive result, the higher the Suspect Score. You can customize how much each Smart Signal contributes to the final Suspect Score. See [Suspect Score](/docs/suspect-score) for more details.

Suspect Score is also available in the `get()` response of our JavaScript agent for easy experimentation. Although we do not recommend using the value for decisions on the client, it allows you to try Smart Signals in a distilled form without any server side setup.

## Browser Smart Signals

| Name                                                                                  | Description                                                                                                                          |
| :------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- |
| [Bot Detection](/docs/smart-signals-reference#browser-bot-detection)                  | Indicates bots and automated browsers like Selenium or Puppeteer.                                                                    |
| [Browser Tampering Detection](/docs/smart-signals-reference#browser-tamper-detection) | Indicates visitors are trying to avoid identification by using antidetect browsers or manually altering their browser configuration. |
| [Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection)  | Indicates Developer tools are open when the page loads.                                                                              |
| [Incognito Detection](/docs/smart-signals-reference#browser-incognito-detection)      | Indicates visitors are using Incognito or Private browsing mode.                                                                     |
| [Privacy-Focused Settings](/docs/smart-signals-reference#privacy-focused-settings)    | Indicates the browser is set to actively prevent fingerprinting, for example, Brave.                                                 |
| [Raw Device Attributes](/docs/smart-signals-reference#raw-device-attributes)          | Provides raw device attributes collected by the JavaScript agent. Enterprise plan only.                                              |
| [Browser VPN Detection](/docs/smart-signals-reference#vpn-detection-for-browsers)     | Indicates visitors are using a VPN to conceal their true IP address and location.                                                    |
| [Virtual Machine Detection](/docs/smart-signals-reference#virtual-machine-detection)  | Indicates the browser is running inside a virtual machine.                                                                           |
| [Device Rarity Detection](/docs/smart-signals-reference#device-rarity-detection)      | Identifies devices whose combination of core attributes is statistically uncommon or previously unseen across global traffic.        |

## Smart Signals for mobile devices

| Name                                                                                                           | Description                                                                                                                         | Android | iOS |
| :------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :-----: | :-: |
| [Android Emulator Detection](/docs/smart-signals-reference#android-emulator-detection)                         | Indicates your app is running from within an Android emulator instead of a physical device.                                         |    ✅    |  ❌  |
| [iOS Simulator Detection](/docs/smart-signals-reference#ios-simulator-detection)                               | Indicates your app is running on an iOS simulator rather than a physical device.                                                    |    ❌    |  ✅  |
| [Cloned App Detection](/docs/smart-signals-reference#cloned-app-detection)                                     | Indicates the request is from a cloned version of your app.                                                                         |    ✅    |  ❌  |
| [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection)                               | Indicates the time of the most recent factory reset for this mobile device.                                                         |    ✅    |  ✅  |
| [Frida Detection](/docs/smart-signals-reference#frida-detection)                                               | Indicates your app is being tampered with using Frida.                                                                              |    ✅    |  ✅  |
| [Geolocation Spoofing Detection](/docs/smart-signals-reference#geolocation-spoofing-detection)                 | Indicates the mobile device is trying to spoof its location.                                                                        |    ✅    |  ✅  |
| [Jailbroken Device Detection](/docs/smart-signals-reference#jailbroken-device-detection)                       | Indicates your app is running on a jailbroken iOS device.                                                                           |    ❌    |  ✅  |
| [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection)                                   | Indicates that the request from your app is intercepted and potentially modified.                                                   |    ✅    |  ✅  |
| [Rooted Device Detection](/docs/smart-signals-reference#rooted-device-detection)                               | Indicates your app is running on a rooted Android device.                                                                           |    ✅    |  ❌  |
| [Tampered Request Detection](/docs/smart-signals-reference#tampered-request-detection-for-mobile-apps)         | Indicates the request from your app to Fingerprint's servers has been tampered with.                                                |    ✅    |  ✅  |
| [Mobile VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices)                         | Indicates the mobile device has an active VPN connection.                                                                           |    ✅    |  ✅  |
| [Mobile Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection-for-mobile-devices) | Indicates whether developer tools are active on a mobile device.                                                                    |    ✅    |  ✅  |
| [Active Call Detection](/docs/smart-signals-reference#active-call-detection)                                   | Indicates if the user's device has an active cellular or internet (VoIP) call in progress at the moment of an identification event. |    ✅    |  ✅  |

<br />

## Smart Signals common for browsers and mobile devices

| Name                                                                       | Description                                                                                                                       |
| :------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| [High-Activity Device](/docs/smart-signals-reference#high-activity-device) | Detect if the device is among the top 2% of devices most frequently identified by your Fingerprint application.                   |
| [IP Geolocation](/docs/smart-signals-reference#ip-geolocation)             | Get the visitor's location based on their IP address.                                                                             |
| [Proxy Detection](/docs/smart-signals-reference#proxy-detection)           | Detect if the visitor's IP address belongs to a public or known residential proxy                                                 |
| [IP Blocklist](/docs/smart-signals-reference#ip-blocklist-matching)        | See if the visitor's IP address belongs to a known proxy, or a TOR node, or is associated with a previous SPAM or network attack. |
| [Velocity Signals](/docs/smart-signals-reference#velocity-signals)         | Detect unusually high numbers of IP addresses, countries, or linked IDs associated with a single device in a short period.        |


# Smart Signals reference
Source: https://docs.fingerprint.com/docs/smart-signals-reference

Fingerprint is not just an identity platform; it also helps fight fraud by providing actionable device intelligence called Smart Signals. This page contains the reference information for individual Smart Signal components and their applications.

Smart Signals are actionable device intelligence insights you can use to improve your fraud prevention logic. For general information about Smart Signals availability and usage, see [Smart Signals Introduction](/docs/smart-signals-introduction).

Some signals are available on [all platforms](#smart-signals-common-for-browsers-and-mobile-devices), while others are specific only to [browsers](#browser-smart-signals) or [mobile devices](#smart-signals-for-mobile-devices).

## Smart Signals common for browsers and mobile devices

These Smart Signals are available on all platforms.

### Suspect Score

<Availability />

Suspect Score combines all Smart Signals into a weighted integer value based on their global probability. To read more about the weights and the mechanisms, see [Suspect score](/docs/suspect-score).

```json Suspect Score theme={"theme":"github-dark-dimmed"}
"suspect_score": 10
```

### Velocity Signals

<Availability />

Velocity Signals sum [key data points](https://fingerprint.com/blog/product-update-velocity-signals/) at three distinct intervals: 5 minutes, 1 hour, and 24 hours as follows:

[`Per visitorID`](https://fingerprint.com/blog/product-update-velocity-signals/#per-visitorid) :

* Number of distinct IP addresses linked to the `visitor_id`
* Number of distinct countries associated with a `visitor_id`
* Number of distinct `linked_id` associated with the `visitor_id`
* Number of events linked to the `visitor_id`

[`Per linkedID`](https://fingerprint.com/blog/product-update-velocity-signals/#per-linkedid) :

* Number of distinct IPs associated with the `linked_id`
* Number of distinct `visitor_id` associated with the `linked_id`

[`Per IP`](https://fingerprint.com/blog/product-update-velocity-signals/#per-ip) :

* Number of events linked to an IP address

<CodeGroup>
  ```json Distinct IPs per visitorID theme={"theme":"github-dark-dimmed"}
  "velocity": {
      "distinct_ip": {
        "5_minutes": 1,
        "1_hour": 1,
        "24_hours": 1 // For visitors exceeding 10,000 in 24 hours, we will omit 5_minutes and 1_hour, returning only 24h as 10,000.
      }
    }
  ```

  ```json Distinct countries per visitorID theme={"theme":"github-dark-dimmed"}
  "velocity": {
    "distinct_country": {
        "5_minutes": 1,
        "1_hour": 2,
        "24_hours": 2 // For visitors exceeding 10,000 in 24 hours, we will omit 5_minutes and 1_hour, returning only 24h as 10,000.
      }
    }
  ```

  ```json Distinct linkedIDs per visitorID theme={"theme":"github-dark-dimmed"}
  "velocity": {
    "distinct_linked_id": {
      "5_minutes": 1,
      "1_hour": 5,
      "24_hours": 5 // For visitors exceeding 10,000 in 24 hours, we will omit 5_minutes and 1_hour, returning only 10,000 for 24h.
    }
  }
  ```

  ```json Events per visitorID theme={"theme":"github-dark-dimmed"}
  "velocity": {
    "events": {
      "5_minutes": 3,
      "1_hour": 5,
      "24_hours": 23 // For visitors exceeding 10,000 in 24 hours, we will omit 5_minutes and 1_hour, returning only 10,000 for 24h.
    }
  }
  ```

  ```json Distinct IPs per linkedID theme={"theme":"github-dark-dimmed"}
  "velocity": {
    "distinct_ip_by_linked_id": {
      "5_minutes": 1,
      "1_hour": 5,
      "24_hours": 5 // For visitors exceeding 10,000 in 24 hours, we will omit 5_minutes and 1_hour, returning only 10,000 for 24h.
    }
  }
  ```

  ```json Distinct visitorIDs per linkedID theme={"theme":"github-dark-dimmed"}
  "velocity": {
    "distinct_visitor_id_by_linked_id": {
      "5_minutes": 1,
      "1_hour": 5,
      "24_hours": 5 // For visitors exceeding 10,000 in 24 hours, we will omit 5_minutes and 1_hour, returning only 10,000 for 24h.
    }
  }
  ```

  ```json Events per IPv4 theme={"theme":"github-dark-dimmed"}
  "velocity": {
    "ip_events": {
      "5_minutes": 1,
      "1_hour": 5,
      "24_hours": 5
    }
  }
  ```

  ```json No Relevant Data - example theme={"theme":"github-dark-dimmed"}
  "velocity": {
    "distinct_visitor_id_by_linked_id": { // This will be an empty object if there is no data to present
    }
  }
  ```
</CodeGroup>

For high-activity visitors generating over 10,000 unique distinct values to track within a 24-hour window, we will omit the aggregation of 5-minute and 1-hour results, returning an accurate count up to 10,000 for a 24 hour period. This limit does not apply to number of events by visitor ID or events by IP.

### IP Geolocation

<Availability />

The IP Geolocation signal provides an estimated physical location of the client, along with network metadata to support fraud detection and traffic analysis

**Location data**

The location is composed of latitude and longitude, along with an accuracy radius ranging from 5 to 1000 km. These coordinates define the center of a circle that can be mapped. The postal code has the weakest level of confidence and this mappable area would rarely fall within a single postal code.

Latitude and longitude values are mapped to the nearest public park or body of water to avoid implying a specific residential or business location.

**Network data**

IP Geolocation also includes network and ownership metadata, such as:

* ASN information
* Organization type (ISP, Hosting, Business, Education, Government)
* Datacenter indicator

This data can be used to group IP ranges, apply protection or allowlisting rules, and better understand the network context of incoming traffic

<CodeGroup>
  ```json IP Geolocation theme={"theme":"github-dark-dimmed"}
  "ip_info": {
    "v4": {
      "address": "94.142.239.124",
      "geolocation": {
        "accuracy_radius": 20,
        "latitude": 50.05,
        "longitude": 14.4,
        "postal_code": "150 00",
        "timezone": "Europe/Prague",
        "city_name": "Prague",
        "country_code": "CZ",
        "country_name": "Czechia",
        "continent_code": "EU",
        "continent_name": "Europe",
        "subdivisions": [
          {
            "iso_code": "10",
            "name": "Hlavni mesto Praha"
          }
        ]
      },
      "asn": "7922",
      "asn_name": "COMCAST-7922",
      "asn_network": "73.136.0.0/13",
      "asn_type": "isp",
      "datacenter_result": true,
      "datacenter_name": "DediPath"
    },
    "v6": {
      "address": "2001:db8:3333:4444:5555:6666:7777:8888",
      "geolocation": {
        "accuracy_radius": 5,
        "latitude": 49.982,
        "longitude": 36.2566,
        "postal_code": "10112",
        "timezone": "Europe/Berlin",
        "city_name": "Berlin",
        "country_code": "DE",
        "country_name": "Germany",
        "continent_code": "EU",
        "continent_name": "Europe",
        "subdivisions": [
          {
            "iso_code": "BE",
            "name": "Land Berlin"
          }
        ]
      },
      "asn": "6805",
      "asn_name": "Telefonica Germany",
      "asn_network": "2a02:3100::/24",
      "asn_type": "isp",
      "datacenter_result": false,
      "datacenter_name": ""
    }
  }
  ```
</CodeGroup>

### Proxy Detection

<Availability />

Detects whether the IP address is used by a **residential** or a **data center** proxy provider using a combination of internal and third-party data sources.

* Data center proxies are typically hosted in data centers and connect with HTTPS or SOCKS5 protocols.
* Residential proxies route internet traffic through real user devices with legitimate ISP-issued IP addresses, making requests appear as if they originate from ordinary end-users. They are commonly used for fraudulent activity, such as account takeovers or illegal content scraping.

<CodeGroup>
  ```json Proxy not detected theme={"theme":"github-dark-dimmed"}
  "proxy": false,
  "proxy_confidence": "high",
  "proxy_ml_score": 0.138
  ```

  ```json Residential proxy detected theme={"theme":"github-dark-dimmed"}
  // will return true in case the device IP was recently used by a known residential proxy provider
  "proxy": true,
  // can also be "medium" for moderately active proxy IPs,
  // or "high" for recently active proxy IPs
  "proxy_confidence": "high",
  "proxy_ml_score": 0.821,
  "proxy_details": {
    "proxy_type": "residential",
    "provider": "BrightData"
  }
  ```

  ```javascript Data center proxy detected theme={"theme":"github-dark-dimmed"}
  // will return true in case the device IP belongs to a known data center proxy
  "proxy": true,
  // can also be "medium" for moderately active proxy IPs,
  // or "high" for recently active proxy IPs
  "proxy_confidence": "low",
  "proxy_ml_score": 0.252,
  "proxy_details": {
    "proxy_type": "data_center",
    "provider": "Massive",
    // this field is optional and is returned when the time of last proxy activity is known
    "last_seen_at": 1708102555327
  }
  ```

  ```javascript Proxy Detected (type unknown) theme={"theme":"github-dark-dimmed"}
  "proxy": true,
  "proxy_confidence": "low",
  "proxy_ml_score": 0.196,
  "proxy_details": {
      "proxy_type": "unknown" // proxy was detected by the ML model but the type could not be determined
  }
  ```
</CodeGroup>

#### `proxy_confidence`

<Note>
  The confidence logic described below is in gradual rollout, as this is a new change to how `proxy_confidence` is calculated.
</Note>

The confidence level indicates how certain Fingerprint is that the current request is using a proxy.

In case of `proxy: true`

* **High confidence**: The IP was last seen active within the past minute.
* **Medium confidence**: The IP was last seen active between 1 and 5 minutes ago.
* **Low confidence**: The IP was last seen active between 5 and 15 minutes ago — indicating historical proxy activity rather than a currently active proxy.

When the proxy is detected solely by the ML model, confidence instead follows fixed score thresholds: `0.6 – 0.8` = `low`, `0.8 – 0.9` = `medium`, and above `0.9` = `high`.

In case of `proxy: false`

* **High confidence**: The IP was last seen active more than 15 minutes ago (or never) — indicating no recent proxy behavior.

#### `proxy_ml_score`

`proxy_ml_score` is a score between 0 and 1 representing the probability that the request is using a proxy, as determined by the ML model.

#### `proxy_details`

`proxy_details` is an object with additional information about the detected proxy. It always contains a `proxy_type` field with one of three values:

* `residential` - traffic routed through a residential IP
* `data_center` - traffic routed through a datacenter IP
* `unknown` - proxy was detected by the ML model but the type could not be determined

May also contain an optional `last_seen_at` timestamp indicating when this IP was last observed exhibiting proxy-like behavior. The timestamp is in ISO 8601 format with hourly resolution, always in UTC. This field is not present when the proxy was detected solely by the ML model.

### IP Blocklist Matching

<Availability />

The feature uses a combination of internal and 3rd-party IP databases to determine whether:

* `tor` payload : The IP address is a known Tor exit node. Do not utilize active Tor detection mechanisms.
* `ipBlocklist.details`payload : The IP address has been part of a network attack, email spam attack or if 75% or more of events from an IP are flagged as [replayed](/docs/protecting-from-payload-replay-attacks) within the last 7 days.

<CodeGroup>
  ```json Blocklist theme={"theme":"github-dark-dimmed"}
  "ip_blocklist": {
    "email_spam": false,
    "attack_source": false,
    "tor_node": false
  }
  ```
</CodeGroup>

### High-Activity Device

<Availability />

Detects if the device is among the top 2% of devices most frequently identified by your Fingerprint application.**High-Activity Device** searches for spikes in traffic connected to a single `visitorID`. It computes the amount of visits **in the past 24 hours** for each `visitorID` **every five minutes** and reports `high_activity_device` as `true` if the number of visits for the past 24 hours surpasses a threshold.

#### High-Activity Device Threshold

The threshold is calculated for each customer separately and is determined through **a normal traffic distribution**. If the returned `visitorID` does **more requests than 98% of other daily visitors**, the High-Activity Smart Signal returns a positive result. If the traffic doesn't pass the threshold, `high_activity_device` returns `false`.

<CodeGroup>
  ```json High Activity - Detected theme={"theme":"github-dark-dimmed"}
  "high_activity_device": true
  ```

  ```json Normal Activity theme={"theme":"github-dark-dimmed"}
  "high_activity_device": false
  ```
</CodeGroup>

### Raw Device Attributes

<Availability />

Raw Device Attributes expose low-level data points describing the browser, device, and rendering environment, collected by our JavaScript agent and native iOS/Android SDKs.

<Accordion title="JSON">
  ```json theme={"theme":"github-dark-dimmed"}
  "raw_device_attributes": {
    "font_preferences": {
      "default": 73.78125,
      "serif": 73.78125,
      "sans": 72.0078125,
      "mono": 66.53125,
      "apple": 73.78125,
      "min": 4.6171875,
      "system": 73.046875
    },
    "emoji": {
      "font": "Times",
      "width": 1280,
      "height": 18.5,
      "top": 9.5,
      "bottom": 28,
      "left": 8,
      "right": 1288,
      "x": 8,
      "y": 9.5
    },
    "fonts": [
      "Arial Unicode MS",
      "Gill Sans",
      "Helvetica Neue",
      "Menlo"
    ],
    "device_memory": 8,
    "timezone": "America/New_York",
    "canvas": {
      "winding": true,
      "geometry": "db3c1462576a399a03ae93d0ab9eb5c4",
      "text": "70c3d3f7eb4408dc37a6bf8af1c51029"
    },
    "languages": [
      [
        "en-US"
      ]
    ],
    "webgl_extensions": {
      "context_attributes": "6b1ed336830d2bc96442a9d76373252a",
      "parameters": "ea118c48e308bc4b0677118bbb3019ec",
      "shader_precisions": "f223dfbcd580cf142da156d93790eb83",
      "extensions": "57233d7b10f89fcd1ff95e3837ccd72d",
      "extension_parameters": "86a8abb36f0cb30b5946dec0c761d042",
      "unsupported_extensions": []
    },
    "webgl_basics": {
      "version": "WebGL 1.0 (OpenGL ES 2.0 Chromium)",
      "vendor": "WebKit",
      "vendor_unmasked": "Google Inc. (Apple)",
      "renderer": "WebKit WebGL",
      "renderer_unmasked": "ANGLE (Apple, ANGLE Metal Renderer: Apple M4, Unspecified Version)",
      "shading_language_version": "WebGL GLSL ES 1.0 (OpenGL ES GLSL ES 1.0 Chromium)"
    },
    "screen_resolution": [
      1710,
      1107
    ],
    "touch_support": {
      "touch_event": false,
      "touch_start": false,
      "max_touch_points": 0
    },
    "architecture": 127,
    "cookies_enabled": true,
    "hardware_concurrency": 10,
    "date_time_locale": "en-US",
    "vendor": "Google Inc.",
    "color_depth": 30,
    "platform": "MacIntel",
    "session_storage": true,
    "local_storage": true,
    "audio": 124.04347745512496,
    "plugins": [
      {
        "name": "PDF Viewer",
        "description": "Portable Document Format",
        "mimeTypes": [
          {
            "type": "application/pdf",
            "suffixes": "pdf"
          },
          {
            "type": "text/pdf",
            "suffixes": "pdf"
          }
        ]
      },
      {
        "name": "Chrome PDF Viewer",
        "description": "Portable Document Format",
        "mimeTypes": [
          {
            "type": "application/pdf",
            "suffixes": "pdf"
          },
          {
            "type": "text/pdf",
            "suffixes": "pdf"
          }
        ]
      },
      {
        "name": "Chromium PDF Viewer",
        "description": "Portable Document Format",
        "mimeTypes": [
          {
            "type": "application/pdf",
            "suffixes": "pdf"
          },
          {
            "type": "text/pdf",
            "suffixes": "pdf"
          }
        ]
      },
      {
        "name": "Microsoft Edge PDF Viewer",
        "description": "Portable Document Format",
        "mimeTypes": [
          {
            "type": "application/pdf",
            "suffixes": "pdf"
          },
          {
            "type": "text/pdf",
            "suffixes": "pdf"
          }
        ]
      },
      {
        "name": "WebKit built-in PDF",
        "description": "Portable Document Format",
        "mimeTypes": [
          {
            "type": "application/pdf",
            "suffixes": "pdf"
          },
          {
            "type": "text/pdf",
            "suffixes": "pdf"
          }
        ]
      }
    ],
    "indexed_db": true,
    "math": "5f030fa7d2e5f9f757bfaf81642eb1a6",
    "font_hash": "bbbea47743cf8367b580a2097e639557",
    "timezone_offset": "+03:00",
    "battery_level": 62,
    "battery_charging": false,
    "keyboard_layout_hash": "dd1e04262570228449ef7357c1cd9439",
    "keyboard_layout_name": "en-US"
  }
  ```
</Accordion>

<Accordion title="Web Attribute descriptions">
  <Accordion title="font_preferences">
    Measures the rendered size of different font families to capture subtle differences in font rendering behavior across platforms and configurations.
  </Accordion>

  <Accordion title="emoji">
    Captures how emoji glyphs are rendered and positioned in the browser, which can vary by OS, browser, and font stack.
  </Accordion>

  <Accordion title="fonts">
    Lists detectable system fonts available in the browser environment.
  </Accordion>

  <Accordion title="device_memory">
    Reflects the approximate device RAM in GB as reported by the browser.
  </Accordion>

  <Accordion title="timezone">
    Represents the browser’s configured IANA time zone identifier.
  </Accordion>

  <Accordion title="canvas">
    Contains hashed results of canvas rendering tests that detect differences in graphics rendering behavior.
  </Accordion>

  <Accordion title="webgl_extensions">
    Includes hashed representations of supported WebGL extensions, parameters, and shader capabilities.
  </Accordion>

  <Accordion title="webgl_basics">
    Provides core WebGL metadata such as version, vendor, renderer, and shading language information.
  </Accordion>

  <Accordion title="screen_resolution">
    Reports the available screen width and height in pixels.
  </Accordion>

  <Accordion title="touch_support">
    Indicates whether touch events are supported and the maximum number of simultaneous touch points.
  </Accordion>

  <Accordion title="architecture">
    Represents a numeric value describing the browser-reported CPU architecture characteristics.
  </Accordion>

  <Accordion title="cookies_enabled">
    Indicates whether cookies are enabled and accessible in the browser.
  </Accordion>

  <Accordion title="hardware_concurrency">
    Reports the number of logical CPU cores available to the browser.
  </Accordion>

  <Accordion title="date_time_locale">
    Represents the locale used for date and time formatting in the browser.
  </Accordion>

  <Accordion title="vendor">
    Identifies the browser vendor string as reported by the user agent.
  </Accordion>

  <Accordion title="color_depth">
    Indicates the color depth of the display in bits per pixel.
  </Accordion>

  <Accordion title="platform">
    Describes the platform on which the browser is running (e.g., MacIntel, Win32).
  </Accordion>

  <Accordion title="session_storage">
    Indicates whether the browser supports and allows access to session storage.
  </Accordion>

  <Accordion title="local_storage">
    Indicates whether the browser supports and allows access to local storage.
  </Accordion>

  <Accordion title="audio">
    Represents a numeric fingerprint derived from audio signal processing behavior in the browser.
  </Accordion>

  <Accordion title="plugins">
    Lists browser-detected plugins and their supported MIME types.
  </Accordion>

  <Accordion title="keyboard_layout_name">
    The detected keyboard layout, returned as a locale identifier (for example, `en-US` or `pt-BR`), based on the physical key mapping reported by the browser. Returns `null` for a small number of layouts that are physically identical across multiple locales and can't be reliably distinguished. Only available in Chrome and other Chromium-based browsers.
  </Accordion>

  <Accordion title="keyboard_layout_hash">
    A hashed fingerprint of the detected keyboard's key mapping, used to identify differences in physical layout. Only available in Chrome and other Chromium-based browsers.
  </Accordion>

  <Accordion title="font_hash">
    A hashed fingerprint of the fonts detected on the device, used to identify subtle differences in installed font configurations. Only available in Chrome and other Chromium-based browsers.
  </Accordion>

  <Accordion title="timezone_offset">
    The browser's UTC time zone offset (for example, `+01:00`), calculated independently from the IANA timezone identifier.
  </Accordion>

  <Accordion title="battery_level">
    The device's current battery charge level, as a percentage. Only available in Chrome and other Chromium-based browsers.
  </Accordion>

  <Accordion title="battery_charging">
    Whether the device's battery is currently plugged in and charging (`true`) or running on battery power (`false`).
  </Accordion>

  <Accordion title="indexed_db">
    Indicates whether IndexedDB is available and accessible in the browser.
  </Accordion>
</Accordion>

<Accordion title="Mobile Attribute descriptions">
  <Accordion title="device_manufacturer">
    Android and iOS only. Reflects the manufacturer of the device as reported by the platform (e.g., Apple, Samsung, Google).

    <CodeGroup>
      ```json JSON theme={"theme":"github-dark-dimmed"}
      { "raw_device_attributes": { device_manufacturer": "samsung" } }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="device_model">
    Android and iOS only. Reflects the model name of the device as reported by the platform.

    <CodeGroup>
      ```json JSON theme={"theme":"github-dark-dimmed"}
      { "raw_device_attributes": { device_model": "SM-A336B" } }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="device_memory">
    Reflects the approximate device RAM in GB as reported by the device.

    <CodeGroup>
      ```json JSON theme={"theme":"github-dark-dimmed"}
      { "raw_device_attributes": { "device_memory": 8 } }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="languages">
    Reflects the device's preferred language as reported by the platforms.

    <CodeGroup>
      ```json JSON theme={"theme":"github-dark-dimmed"}
      { "raw_device_attributes": { "languages": [["en-US"]] } }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="screen_resolution">
    Returns the available mobile device screen width and height in pixels.

    <CodeGroup>
      ```json JSON theme={"theme":"github-dark-dimmed"}
      { "raw_device_attributes": { "screen_resolution": [390, 844] } }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="battery_level">
    Android and iOS only. Reports the device's current battery level in percentage.

    <CodeGroup>
      ```json JSON theme={"theme":"github-dark-dimmed"}
      { "raw_device_attributes": { "battery_level": true } }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="battery_low_power_mode">
    Android and iOS only. Indicates whether low power mode (battery saver) is active on the device.

    <CodeGroup>
      ```json JSON theme={"theme":"github-dark-dimmed"}
      { "raw_device_attributes": { "battery_low_power_mode": true } }
      ```
    </CodeGroup>
  </Accordion>
</Accordion>

**Notes**

* Many values are hashed to reduce payload size and prevent direct reconstruction of raw rendering data.
* Individual attributes are not inherently malicious, they are evaluated in combination to detect anomalous or manipulated environments.

### Proximity Detection

<Availability />

Proximity detection is a complementary, location-based signal. Unlike the visitor ID, the proximity ID does not identify a unique device or browser but instead represents a fixed geographical zone within which the device is observed. This provides an additional layer of context, making it possible to identify groups of devices in the same physical area or a single device that may have changed its identity while remaining in the same zone.

**How to use this signal on each platform**

**Web:**

* Make sure your website uses JavaScript Agent version 3.12.9 or higher.
* Ensure that location permission is enabled and granted in the browser. The signal relies on the browser’s Geolocation API, so proximity data can only be collected when the user allows location access.

**Android:**

* To use this feature, make sure to update your app to use [Android SDK v2.10.0](/docs/changelog-android-sdk#v2-10-0) or higher.
* Ensure your app declares the required [location permissions](/docs/android-sdk#location-permissions). For integration details, please follow the instructions on the [Android SDK configuration](/docs/android-sdk#using-location-data-for-proximity-detection) page.
* Proximity IDs and related data (e.g., confidence level, precision radius) will be exposed only via the [Server API](/reference/server-api), [webhooks](/docs/webhooks), or when [Sealed Client Results](/docs/sealed-client-results) are enabled.

**iOS:**

* To use this feature, make sure to update your app to use [iOS SDK v2.10.0+](/docs/changelog-ios-sdk#v2-10-0) or higher.
* Ensure your app declares the required [location permissions](/docs/ios-sdk#handling-location-permissions). For integration details, please follow the instructions on the [iOS SDK configuration](/docs/ios-sdk#using-location-data-for-proximity-detection) page.
* Same as for Android, proximity IDs and related data (e.g., confidence level, precision radius) will be exposed only via the [Server API](/reference/server-api), [webhooks](/docs/webhooks), or when [Sealed Client Results](/docs/sealed-client-results) are enabled.

We use a [discrete global grid system](https://en.wikipedia.org/wiki/Discrete_global_grid) to generate proximity data in a consistent and privacy-conscious way. This approach allows us to represent user locations as coarse, non-identifiable spatial zones (proximity IDs), enabling scalable proximity detection and fraud analysis while protecting user privacy. For a closer look at how we apply this approach in practice, see our [technical deep-dive](https://fingerprint.com/blog/proximity-detection-deep-dive/).

The response will include proximity results in the following structure:

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  {
    "proximity": {
      "id": "w1aTfd4MCvl",
      "precision_radius": 10,
      "confidence": 0.95
    }
  }
  ```
</CodeGroup>

Note: In API v4, the `proximity` attribute is omitted from the response payload if the underlying geolocation data is not available, rather than being returned as an empty object.

`id`

The `id` field is a stable identifier for a given proximity zone. Devices observed within the same zone will share the same `id`. It can be used for detecting behaviors like:

* Devices frequently appearing together (co-location patterns).
* Repeated activity from the same physical area.
* Potential device farms or shared access points. `id` cannot be reverse-mapped to a specific geolocation, enabling privacy-preserving location-based analysis without compromising user identity or precision.

`precisionRadius`

The `precisionRadius` field indicates the precision level of the proximity zone, expressed in meters. For example, `"precisionRadius": 10` means the device's location was mapped to a zone covering an area approximately 10 meters across.

* Smaller values correspond to finer-grained zones and higher precision.
* Proximity precision levels are hierarchical: each proximity ID is contained within a parent proximity ID at a coarser level (larger `precisionRadius`).
  * Devices with identical coordinates can map to different proximity IDs if their reported location accuracies differ significantly.
  * For example, identical coordinates with `5` m and `10` m location accuracy would map to the same proximity ID, while `50` m accuracy would map to a different, coarser proximity ID.
* By default, we return the most precise proximity ID based on the location signals, but you can also retrieve proximity data at a specific (default or larger) `precisionRadius` using [/v4/events](/reference/server-api-search-events). We recommend leveraging this search filter to get the most value from proximity data. This feature allows you to search across coarser radius levels, helping identify all devices within a larger area - even if they were originally mapped to more granular zones.

<Info>
  **Useful tip: Keep in mind that adjacent** physical areas may generate different Proximity IDs. Using the filter by `precisionRadius` through [/v4/events](/reference/server-api-search-events) ensures your logic can accommodate these natural boundaries by grouping related IDs under a broader zone.
</Info>

**How to interpret precisionRadius**

| **Precision radius range** | **What it means**                                       | **Typical use cases**                                                                                                                                   |
| -------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **0-10 m**                 | Very precise location (room-level or same building).    | Detecting co-located devices, potential device farms, or flagging a single device that may have changed its identity but remained in the same location. |
| **10-75 m**                | Street-level accuracy. Same street or nearby building.  | Retail/store fraud detection, delivery validation, nearby device matching.                                                                              |
| **75-200 m**               | Neighborhood/block-level accuracy.                      | Good for geo-marketing and less strict fraud checks; however, it can flag potential clusters of spoofed locations or reused identities.                 |
| **200 m-1 km**             | City-level accuracy. Same area, but not the exact spot. | Audience analytics, compliance checks, potential clusters of spoofed locations or reused identities.                                                    |
| **1 km+**                  | Rough location.                                         | Country/city validation, coarse geolocation, potential clusters of spoofed locations or reused identities.                                              |

`confidence`

The `confidence` field ranges from `0` to `1` and reflects the likelihood that the true device location lies within the mapped proximity zone rather than an adjacent one. It is calculated by evaluating multiple factors that determine how well the device location coordinates and accuracy radius fit within the proximity zone.

* Scores closer to `1` indicate high confidence that the true device location is inside the mapped proximity zone, as the device location area fits cleanly within its bounds.
* Scores closer to `0` indicate low confidence, as the device location area is only partially contained within the proximity zone bounds, suggesting the true location point may lie within an adjacent zone. Even with a score of `0`, the true location will always be either within the mapped proximity zone or an immediately adjacent one. Retrieving proximity IDs from [/v4/events](/reference/server-api-search-events) at coarser precision levels (filtering by larger `precisionRadius` values) typically yields higher confidence scores.

## Browser Smart Signals

The Smart Signals listed below apply only to browsers.

### Browser Bot Detection

<Availability />

[**Javascript agent v3.7.0+**](/docs/changelog-javascript-agent#v3-7-0)

Get information about good and bad bots, allowing you to block or filter them from your regular traffic and stop automated abuse attempts.

The `bot` field contains one of `not_detected`, `bad` or `good` values where

* `not_detected` means that we haven't detected a bot and the payload should belong to a regular visitor
* `good` indicates that the bot is a well-known web crawler or other search engine bot
* `bad` is an automated tool that doesn't have legitimate uses and assumes fraudulent activity

<CodeGroup>
  ```json Bad Bot - Detected theme={"theme":"github-dark-dimmed"}
  "bot": "bad",
  "bot_type": "selenium"
  ```

  ```json Legitimate Visitor theme={"theme":"github-dark-dimmed"}
  "bot": "not_detected"
  ```
</CodeGroup>

### Browser Incognito Detection

<Availability />

**Incognito** flag detects whether incognito or private modes are being used by the visitor to access the customer's website.

Most browsers have an option called Incognito mode ([Chrome](https://support.google.com/chrome/answer/95464?hl=en\&co=GENIE.Platform%3DDesktop)) or Private mode ([Safari](https://support.apple.com/en-gb/guide/safari/ibrw1069/mac), [Firefox](https://support.mozilla.org/en-US/kb/private-browsing-use-firefox-without-history)) that disables some functionality and makes the general browser storage more ephemeral. Normal browser tabs save additional information like cookies and local storage content in a way that ensures that the information is available to the website even after the browser window is closed and re-opened. Incognito mode makes sure that there are no such traces once a window gets closed.

Since the most basic fingerprinting technique could be storing a cookie in the visitor's browser, the incognito mode can be used to circumvent this simple mechanism, making sure that the returning visitor is not correctly re-identified through cookies and other information stored in the browser. This might be interpreted as an attempt to pose as a completely new identity. It might also be considered to be the most basic mechanism of browser tampering.

The flag is an interesting data point in fraud scenarios, especially in use cases where applying promotional coupons, redeeming bonuses or voting should be limited to once per user.

<CodeGroup>
  ```json Incognito Mode - Detected theme={"theme":"github-dark-dimmed"}
  "incognito": true
  ```

  ```json Normal Mode theme={"theme":"github-dark-dimmed"}
  "incognito": false
  ```
</CodeGroup>

These browsers are supported:

* Safari (macOS / iOS)
* Chrome (Windows / macOS / iOS / Android / Linux)
* Samsung Browser (Android)
* Firefox (Windows / macOS / iOS / Android / Linux)
* Edge (Windows / macOS / iOS / Android)
* Brave (Windows / macOS / iOS / Android / Linux)

<Warning>
  **HTML iframes limitation**

  Incognito detection can give a false result when JavaScript agent runs in an iframe. Make sure JavaScript agent runs outside iframes to get the accurate result.
</Warning>

### VPN Detection for browsers

<Availability />

Fingerprint's [VPN detection](https://fingerprint.com/blog/vpn-detection-how-it-works/) is capable of detecting whether the user is in a different timezone compared to their originating IP address indicated by the `timezone_mismatch` flag. It can also provide information about whether an IP address is associated with one of the public VPN providers, indicated by the `publicVPN` flag, or anonymizing services, indicated by the `relay` flag . On top of that, we detect whether the OS of the client matches the OS of the network traffic we see, represented in the `os_mismatch` flag. We also apply a unified ML model to detect VPN usage, represented in the `ml_prediction` flag.

If any of those `vpn_methods` return a positive result, we return the final `vpn` as `true`.

<CodeGroup>
  ```json VPN Detected theme={"theme":"github-dark-dimmed"}
  "vpn": true,
  "vpn_confidence": "high",
  "vpn_ml_score": 0.895,
  "vpn_origin_timezone": "Europe/Berlin",
  "vpn_origin_country": "DE", 
  "vpn_methods": {
      "timezone_mismatch": true,
      "public_vpn": true,
      "auxiliary_mobile": false, 
      "os_mismatch": false,
      "relay": false,
      "ml_prediction": true
  }
  ```

  ```json No VPN Detected theme={"theme":"github-dark-dimmed"}
  "vpn": false,
  "vpn_confidence": "high",
  "vpn_ml_score": 0.024,
  "vpn_origin_timezone": "Europe/Berlin",
  "vpn_origin_country": "DE", 
  "vpn_methods": {
      "timezone_mismatch": false,
      "public_vpn": false,
      "auxiliary_mobile": false,
      "os_mismatch": false,
      "relay": false,
      "ml_prediction": false
  }
  ```
</CodeGroup>

#### `vpn`

* `true` if we detect a VPN through `timezone_mismatch`, `public_vpn`, `relay`, `os_mismatch`, or `ml_prediction` methods. The field can be used as a standalone flag for VPN detection. Alternatively, fields in the `methods` section (documented below) can be used in specific use-cases to improve the granularity of the detection
* `false` if none of the `methods` below returned a positive result

#### `vpn_confidence`

The confidence level indicates how certain Fingerprint is that the current request is originating from a VPN. It is conveyed as a string with three possible values: `high`, `medium`, or `low`. This confidence level is determined by evaluating multiple factors, such as `public_vpn`, `timezone_mismatch`, `os_mismatch`, `ml_prediction` and other relevant `vpn_methods`.

In case of `vpn: true`

When `ml_prediction` is the only signal triggering detection, confidence is determined solely by the ML score using fixed thresholds: `0.6 – 0.8` = `low`, `0.8 – 0.9` = `medium`, and above `0.9` = `high`. <br /><br />When multiple signals are active, confidence reflects the strongest available signal across both the ML model and rule-based methods.

* **High confidence**: Clear, strong signals suggest the user is connected via a VPN.
* **Medium confidence**: Some signals point to possible VPN usage, including cases where a significant difference between the device's original timezone and the IP timezone is detected. The evidence is not definitive.
* **Low confidence**: Mainly due to a minor difference between the device's original timezone and the IP timezone. This could suggest scenarios other than VPN usage, such as when the network provider is registered in a different timezone or routes traffic through servers in another location.

In case of `vpn: false`

* **High confidence**: Strong signals suggest the user is not using a VPN.
* **Medium confidence**: Partial signals have been captured, but the evidence is not definitive.

#### `vpn_ml_score`

The output of Fingerprint's ML model for VPN detection, expressed as a decimal between 0 and 1. Values closer to 1 indicate higher likelihood of VPN usage.

#### `vpn_origin_timezone`

This field exposes the [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) that is available through the system settings. Since the presence of a VPN does not affect the value of this field, it can be used as a true timezone of origin (physical location) of the user.

* **Example:** `originTimezone: "Europe/Prague"`

#### `vpn_origin_country`

This field returns the estimated country of origin of the user based on device location data, expressed as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (e.g. `"DE"`). Returns `"unknown"` when the country could not be determined.

#### `vpn_methods`

More granular VPN detection methods that contribute to the final VPN detection `result`.

##### `timezone_mismatch`

* `true`
  * When the geolocated IP address of the device does not match the originTimezone from the system settings or
  * When at least 50% of requests from the same IP in the last 7 days show a mismatch between the device’s originTimezone and the IP address location
* `false` when `originTimezone` matches the location of the IP address from which we receive the traffic

The `originTimezone` includes a country-specific reference like `"Europe/Prague"`. The `timezoneMismatch` will be `true` even if a visitor in Prague uses a Berlin VPN server, despite both countries being in the same *GMT+2* UTC offset. For most use cases, `timezoneMismatch` functions well as an indicator of country mismatch between the browser and the IP address.

##### `public_vpn`

Detects whether the IP address of the event matches any publicly known VPN providers like [NordVPN](https://nordvpn.com/), [Surfshark](https://surfshark.com/), [ExpressVPN](https://www.expressvpn.com/), [ProtonVPN](https://protonvpn.com/) and others.

* `true` when our database of public VPN provider IP addresses contains the IP address of the event
* `false` if we did not find a match in our public VPN provider database

##### `os_mismatch`

Compares the network signature of the request we have received through our proprietary algorithm and searches our internal database to determine whether the signature matches the OS (operating system) of the client.

* `true`
  * If the network signature of the request we receive **does not match** the signature of the OS of the client or
  * When at least 10% of requests from the same IP in the last 7 days show this mismatch
* `false`
  * if the network signature of the request we receive matches the signature of the OS of the client
  * if we fail to capture the OS information through our detection algorithm (happens in 10-15% cases)

The method is currently very accurate for **Windows** devices but might be less accurate for other OS combinations. We recommend using this flag to lower the false positive rate of the `timezoneMismatch` method.

##### `relay`

Detects whether the IP address of the event matches anonymizing services, such as iCloud Private Relay.

##### `auxiliary_mobile`

* This field is primarily set for requests from our iOS and Android native SDKs.
* For browsers, it is normally false, but will be true if at least 10% of requests from the same IP in the last 7 days meet the auxiliary mobile detection criteria.
* See the detailed description in [VPN Detection for mobile devices](/docs/smart-signals-reference#vpn-detection-for-mobile-devices)

`ml_prediction`<br />Indicates whether Fingerprint's ML model detected VPN usage. Set to `true` when Fingerprint's ML model predicts this request is originating from a VPN, `false` otherwise

### Browser Tamper Detection

<Availability />

There are very simple techniques to confuse less sophisticated fingerprinting algorithms through User Agent [spoofing](https://fingerprint.com/blog/what-is-browser-spoofing/) or by changing the output of selected signals collected from the browser, including the use of antidetect browsers.

While our `visitor_id` remains stable in those cases, tampering detection helps detect this behavior.

We do this using two complementary detection approaches:

* Statistical anomaly detection, which identifies browser signatures that are unusually rare compared to the overall population
* Antidetect browser detection, which combines heuristic (rule-based) methods with a machine learning model to identify known antidetect browsers

<CodeGroup>
  ```json Tampering Detected - Antidetect browser theme={"theme":"github-dark-dimmed"}
  "tampering": true,
  "tampering_confidence": "high",
  "tampering_ml_score": 0.9721,
  "tampering_details": {
      "anomaly_score": 0,
      "anti_detect_browser": true 
    } 
  ```

  ```json Tampering Detected - High anomaly score theme={"theme":"github-dark-dimmed"}
  "tampering": true,
  "tampering_confidence": "medium",
  "tampering_ml_score": 0,
  "tampering_details": {
      "anomaly_score": 0.9721,
          "anti_detect_browser": false
  }
  ```

  ```json Standard Browser theme={"theme":"github-dark-dimmed"}
  "tampering": false,
  "tampering_confidence": "high",
  "tampering_ml_score": 0,
  "tampering_details": {
      "anomaly_score": 0,
      "anti_detect_browser": false
  }
  ```
</CodeGroup>

#### `tampering`

* `true` if tampering is detected through an anomalous browser signature, antidetect browser detection, or other tampering-related methods
* `false` if none of the tampering checks return a positive result

The field can be used as a standalone flag for tampering detection. Alternatively, the more granular fields documented below can be used for workflows that require more context.

#### `tampering_confidence`

The confidence level indicates how certain Fingerprint is that the current request involves browser tampering. This confidence level is determined by evaluating multiple factors, such as heuristic rules, probabilistic anomaly detection, an anti detect browser ml model, and other relevant methods. It is conveyed as a string with possible values such as high, medium, or low

In case of tampering: `true`

* **High confidence**: heuristic anti detect browser signals and the ml model are triggered, or all of the methods are triggered.
* **Medium confidence**: either the ml model triggers alone, the anomaly score triggers alone with or without the heuristic anti detect browser methods trigger.
* **Low confidence**: only the heuristic anti detect methods are triggered.

In case of tampering: `false`

* **High confidence**: Strong signals suggest the user is not tampering with their request.

#### `tampering_ml_score`

The output of this model is captured as `tampering_ml_score`, a number indicating how likely an event is coming from an anti detect browser. Values close to 1 signify higher confidence and we consider anything above the threshold of 0.8 to be actionable (the result and anti\_detect\_browser fields conveniently captures that fact)

#### `tampering_details`

Provides more granular tampering-related signals that contribute to the final tampering result.

#### `anomaly_score`

The output of this model is captured as `anomaly_score`, a statistical score indicating how rare the visitor’s browser signature is compared to the overall population. Values close to `1` signify highly anomalous browsers and we consider anything above the threshold of `0.5` to be actionable (the `result` field conveniently captures that fact).

#### `anti_detect_browser`

Detects whether the request shows evidence of antidetect browser usage.

This field may be triggered by:

* heuristic detection of known antidetect browser behavior
* machine learning detection of antidetect browser patterns

Examples of antidetect browsers include tools such as AdsPower, DolphinAnty, OctoBrowser, and GoLogin.

### Virtual Machine Detection

<Availability />

Detects if the browser is running inside a [virtualization software](https://fingerprint.com/blog/virtual-machine-fraud-detection/) like VirtualBox by examining the browser configuration.

<CodeGroup>
  ```json Browser Launched from a VM theme={"theme":"github-dark-dimmed"}
  "virtual_machine": true,
  "virtual_machine_ml_score": 0.812
  ```

  ```json Legitimate Browser theme={"theme":"github-dark-dimmed"}
  "virtual_machine": false,
  "virtual_machine_ml_score": 0.732
  ```
</CodeGroup>

#### `virtual_machine`

* `true` if virtualization is detected
* `false` if no virtualization indicators are found

#### `virtual_machine_ml_score`

The output of Fingerprint's ML model for virtual machine detection, expressed as a decimal between 0 and 1. Values closer to 1 indicate higher likelihood of a virtual machine environment.

### Privacy-Focused Settings

<Availability />

Firefox, Brave, and other privacy-focused browsers actively [fight fingerprinting](https://fingerprint.com/blog/privacy-settings-detection/) and expose user settings that have the ability to randomize and obfuscate signal output. The Privacy-Focused Settings Smart Signal detects if those settings are enabled and reports it.

<CodeGroup>
  ```json Privacy Settings - Detected theme={"theme":"github-dark-dimmed"}
  "privacy_settings": true
  ```

  ```json No Privacy Settings theme={"theme":"github-dark-dimmed"}
  "privacy_settings": false
  ```
</CodeGroup>

### Developer Tools Detection

<Availability />

Detect whether browser developer tools are manually opened in Chrome or Firefox, or whether a Chrome instance is being controlled via an active Chrome DevTools Protocol session. This enables detection of various automation frameworks and libraries.

> Note: Data required for Developer Tools detection are collected when the JavaScript agent [loads](/reference/js-agent-start-function), not when the user is [identified](/reference/js-agent-get-function). This can result in false negatives if the visitor opens Developer Tools only after loading the page.

<CodeGroup>
  ```json Developer Tool Detected theme={"theme":"github-dark-dimmed"}
  "developer_tools": true
  ```

  ```json No Developer Tool Detected theme={"theme":"github-dark-dimmed"}
  "developer_tools": false
  ```
</CodeGroup>

### Device Rarity Detection

<Availability />

Device Rarity identifies devices whose combination of core attributes is statistically uncommon or previously unseen across global traffic. Unlike [Browser Tamper Detection](/docs/smart-signals-reference#browser-tamper-detection), which flags internally inconsistent configurations, Device Rarity asks a different question: *how common is this full device configuration globally?*

This allows you to flag:

* Never-before-seen device configurations (`not_seen`)
* Extremely rare configurations (`p99.9+`) even when they are internally consistent and not caught by tampering detection

Device Rarity is most effective when combined with other signals such as [Browser Tamper Detection](/docs/smart-signals-reference#browser-tamper-detection), [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-browsers), and [Suspect Score](/docs/suspect-score).

<CodeGroup>
  ```json Rare device detected theme={"theme":"github-dark-dimmed"}
    "rare_device": true,
    "rare_device_percentile_bucket": "p99.9+"
  ```

  ```json Never-before-seen device theme={"theme":"github-dark-dimmed"}
    "rare_device": true,
    "rare_device_percentile_bucket": "not_seen"
  ```

  ```json Common device theme={"theme":"github-dark-dimmed"}
    "rare_device": false,
    "rare_device_percentile_bucket": "<p95"
  ```
</CodeGroup>

#### `rare_device`

* `true` if the device configuration is at or above the p99.9+ rarity threshold, or has never been observed before
* `false` if the device configuration is common

#### `rare_device_percentile_bucket`

Indicates how rare the device configuration is relative to global traffic observed over the past 14 days.

| Value         | Description                                                                              |
| ------------- | ---------------------------------------------------------------------------------------- |
| `not_seen`    | No prior observation within the reference window. Treat as the most extreme rarity case. |
| `p99.9+`      | Extremely rare — seen in fewer than 0.1% of global traffic                               |
| `p99.5-p99.9` | Very rare — historically observed but highly uncommon                                    |
| `p95-p99`     | Rare but not extreme                                                                     |
| `<p95`        | Common — frequently observed in global traffic                                           |

## Smart Signals for mobile devices

The Smart Signals listed in this section apply only to mobile devices and provide valuable intelligence about the integrity of the device and the app. Smart Signals for Android devices are now included on our [Free plan](https://fingerprint.com/pricing/), making it easier to get started. Full access to all mobile Smart Signals is included with our [Pro Plus and Enterprise plans](https://fingerprint.com/pricing/). If you are interested in one or more of these signals, then please [contact our support team](https://fingerprint.com/support/) to enable them for you.

When your app is integrated with Fingerprint (using either our native mobile SDKs or our multi-platform SDKs), you will receive these signals as part of our Server API and/or Webhooks responses.

### Android Emulator Detection

<Availability />

[**Android SDK v2.3.0+**](/docs/changelog-android-sdk#v2-3-0)

Prevent spam and protect against nefarious Android emulator farms by ensuring the request is coming from a physical device. To [detect emulators](https://fingerprint.com/blog/android-emulator-tamper-fraud-detection/), several additional device attributes have to be collected and this increases the time to get a `visitorId`. The latency can be anywhere between 300 and 1500ms.

```json theme={"theme":"github-dark-dimmed"}
"emulator": false
```

### iOS Simulator Detection

<Availability />

[**iOS SDK v2.12.0+**](/docs/changelog-ios-sdk#december-2025)

Detect whether your app is running on an iOS simulator rather than a physical device. In production environments, simulators are rarely used by legitimate users - they are commonly leveraged by fraudsters to run automated attacks at scale, including account farming, bonus abuse, and promo exploitation. Use this signal to flag non-genuine iOS environments and strengthen your fraud detection stack alongside other signals such as [jailbreak detection](/docs/smart-signals-reference#jailbroken-device-detection), [VPN](http://localhost:3001/docs/smart-signals-reference#vpn-detection-for-mobile-devices) and [proxy](/docs/smart-signals-reference#proxy-detection) usage.

```json theme={"theme":"github-dark-dimmed"}
"simulator": false
```

### Cloned App Detection

<Availability />

[**Android SDK v2.3.0+**](/docs/changelog-android-sdk#v2-3-0)

Identify if a request is coming from a cloned application. Making multiple [clones of an app](https://fingerprint.com/blog/navigating-risks-user-initiated-app-cloning/) on the same device can be used to abuse promotions and get around app restrictions. (Android only)

```json theme={"theme":"github-dark-dimmed"}
"cloned_app": false
```

### Factory Reset Detection

<Availability />

[**Android SDK v2.3.0+**](/docs/changelog-android-sdk#v2-3-0)<br />[**iOS SDK v2.3.0+**](/docs/changelog-ios-sdk#v2-3-0)

Resetting a **mobile device** to default factory settings has been a common technique that fraudsters use to [evade fraud detection mechanisms](https://fingerprint.com/blog/detecting-suspicious-activity-factory-reset/). When a factory reset is performed, it can

* Disguise the identity of the mobile device
* Be used to abuse promotional offers
* Prevent the mobile device from being blocked for fraudulent activity

The Factory Reset Smart Signal will indicate when the mobile device was most recently factory reset. You can use this information in your fraud detection mechanisms to flag a mobile device as suspicious.

As an example, for a mobile device that was factory reset on July 19, 2023, at 6 AM EST, the response will be:

```json theme={"theme":"github-dark-dimmed"}
"factory_reset_timestamp": 1689756000
```

**What is the response for devices that were never factory reset?**

**iOS SDK v2.3.0 or higher**

* For iOS devices that were never factory reset, the `factory_reset_timestamp` field will correspond to [epoch](https://en.wikipedia.org/wiki/Epoch_\(computing\)):
  ```json theme={"theme":"github-dark-dimmed"}
  "factory_reset_timestamp": 0
  ```

**In what other iOS scenarios can a timestamp reset to epoch?**

* The **iOS device** that initiated the request is not a physical device but an iOS simulator. (Conversely, a factory reset can be detected for Android emulators).
* Your **iOS app** does not use Fingerprint Identification SDK **v2.3.0 or higher**. The ability to detect factory reset was introduced only in v2.3.0.

**Android SDK v2.3.0 to 2.9.0**

* For Android devices that were never factory reset, the `factory_reset_timestamp` field in the response will correspond to when the device was activated or in some scenarios, the `factory_reset_timestamp` field will correspond to [epoch](https://en.wikipedia.org/wiki/Epoch_\(computing\)):
  ```json theme={"theme":"github-dark-dimmed"}
  "factory_reset_timestamp": 0
  ```

**Android SDK v2.10.0 and higher**

Starting from Android SDK **v2.10.0** the factory reset detection algorithm has been improved for Android devices to reduce false positives and better distinguish real resets from routine system updates, Google system changes, or vendor-specific behavior.

* For Android devices that were never factory reset, the `factory_reset_timestamp` field will correspond to [epoch](https://en.wikipedia.org/wiki/Epoch_\(computing\)):
  ```json theme={"theme":"github-dark-dimmed"}
  "factory_reset_timestamp": 0
  ```
* If an Android device previously showed a factory reset timestamp but now returns the [epoch](https://en.wikipedia.org/wiki/Epoch_\(computing\)) value after updating to SDK v2.10.0 or higher, it simply means that no real factory reset occurred. Starting with SDK v2.10.0, affected devices have their factory reset timestamps recalculated to ensure accuracy. In these cases, the earlier timestamp was most likely triggered by a system update or silent Google update that behaved similarly to a reset.

**In what other Android scenarios can a timestamp reset to epoch?**

* Your **Android app** uses an incompatible version of Fingerprint Identification SDK
  * **\v2.3.0:** The ability to detect factory reset was introduced only in v2.3.0.
  * **v2.3.0 ≥ SDK \< v2.3.4:** Due to *lazy* signal collection, more than one request must be initiated from the same device for a factory reset to be detected. If you would like to use one of these versions in your app, you first need to [contact our support team](https://fingerprint.com/support/) to enable factory reset detection for your account. (Since the first request from a fraudulent device is the most critical request to detect fraud, we made improvements in v2.3.4 that allowed us to detect a factory reset during the first request itself.)
* **SDK v2.10.0+** As mentioned above, if an Android device previously showed a factory reset due to a system update or silent Google system update before upgrading to SDK v2.10.0, its factory reset timestamp will be recalculated after the upgrade. If no actual user-initiated reset occurred, the timestamp will be updated to the epoch value.

### Frida Detection

<Availability />

[**Android SDK v2.3.3+**](/docs/changelog-android-sdk#v2-3-3)<br />[**iOS SDK v2.2.0+**](/docs/changelog-ios-sdk#v2-2-0)

In simple terms, [app hooking](https://en.wikipedia.org/wiki/Hooking) is a process where the behavior of a mobile app is changed by intercepting the app at runtime. [Frida](https://frida.re/) is a dynamic instrumentation toolkit that tech-savvy fraudsters can use to spoof an app at runtime and change its behavior. With this Smart Signal, you will know if [Frida](https://fingerprint.com/blog/exploring-frida-dynamic-instrumentation-tool-kit/) is being used to dynamically instrument the app.

<CodeGroup>
  ```json theme={"theme":"github-dark-dimmed"}
  "frida": false
  ```
</CodeGroup>

### Geolocation Spoofing Detection

<Availability />

[**Android SDK v2.3.4+**](/docs/changelog-android-sdk#v2-3-4)<br />[**iOS SDK v2.3.1+**](/docs/changelog-ios-sdk#v2-3-1)

Fraudsters spoof the location of their mobile devices to fool fraud detection systems. With this Smart Signal, you will know if the location of the mobile device has been spoofed or not. We also recommend using this Smart Signal in combination with [Proximity Detection](/docs/smart-signals-reference#proximity-detection) results.

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  "location_spoofing": false
  ```
</CodeGroup>

Note: The SDK itself does not request any location permissions. The SDK performs a non-intrusive check to determine whether the host app has already been granted the necessary location permissions. Based on that check, it either collects the geolocation spoofing signal or skips it. In short, this geolocation spoofing detection is only applicable to location-enabled apps for now. For more info about working with location permissions on app side, please refer to the resources:

* [Location Permission for iOS](https://developer.apple.com/documentation/corelocation/requesting_authorization_to_use_location_services).
* [Location Permission for Android](https://developer.android.com/training/permissions/requesting).

### Jailbroken Device Detection

<Availability />

[**iOS SDK v2.2.0+**](/docs/changelog-ios-sdk#v2-2-0)

An iPhone or an iPad is labeled *jailbroken* when unauthorized modifications are made to the underlying operating system (iOS). Jailbreaking weakens a device’s built-in security features and makes it easy to steal sensitive information stored on the device. See [Unauthorized modification of iOS](https://support.apple.com/guide/iphone/unauthorized-modification-of-ios-iph9385bb26a/ios) for more information.

Fraudsters employ [phishing](https://en.wikipedia.org/wiki/Phishing) mechanisms to trick users into installing *jailbreak* software on their devices and then take control of their devices. Your app (e.g. banking, e-commerce, etc) will not be able to distinguish the transactions made using [jailbroken devices](https://fingerprint.com/blog/prevent-mobile-fraud-jailbroken-device-detection/) from those made using genuine devices. Honoring these fraudulent transactions will lead to financial losses (caused by chargeback expenses, account takeover, etc) and loss of trust among your customers.

The Jailbroken Smart Signal will help you detect if your app is being used from an iPhone/iPad that has been jailbroken and enable you to proactively act upon it.

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  "jailbroken": false
  ```
</CodeGroup>

### MitM Attack Detection

<Availability />

[**Android SDK v2.8.0+**](/docs/changelog-android-sdk#v2-8-0)<br />[**iOS SDK v2.8.2+**](/docs/changelog-ios-sdk#v2-8-2)

Man-in-the-Middle (MitM) attacks occur when a fraudster intercepts the communication between two parties with the intention of

* Gaining access to sensitive information.
* Modifying the information to their advantage.
* Block the requests to/from the intended parties.

These attacks can result in service disruptions for an organization, diminishing customer trust, damaging reputation, and causing financial losses.

The MitM Attacks Smart Signal will help you detect if requests made to Fingerprint servers are intercepted and potentially modified. You can use this information to identify spoofed requests/responses and take additional precautionary steps.

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  "mitm_attack": false
  ```
</CodeGroup>

### Rooted Device Detection

<Availability />

[**Android SDK v2.3.0+**](/docs/changelog-android-sdk#v2-3-0)

Ensure a safe Android mobile app environment by detecting [rooted devices](https://fingerprint.com/blog/android-rooted-device-detection/).

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  "root_apps": false
  ```
</CodeGroup>

### Tampered Request Detection for mobile apps

<Availability />

[**Android SDK v2.3.0+**](/docs/changelog-android-sdk#v2-3-0)<br />[**iOS SDK v2.2.0+**](/docs/changelog-ios-sdk#v2-2-0)

Promotional offers are often exploited by creating multiple accounts. Device identification enables businesses to determine if the same mobile device was used to create multiple accounts. One technique fraudsters employ to trick device identification is to modify the request sent to our servers.

When your app requests a visitor ID for the device, Fingerprint collects several properties from the device and sends it to our servers. The properties collected from the device are used to generate the visitor ID and deduce other Smart Signals. However, if the properties within the request are modified beyond recognition, then

* A new visitor ID could be generated for an already-seen device
* All the intended Smart Signals may not be flagged.

The Tampered Request Detection Smart Signal detects anomalies in the properties received with the request. Thus, it enables you to identify tampered requests and take corresponding mitigation measures.

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  "tampering": true
  "tampering_details" {
    "anomaly_score": 1
  }
  ```
</CodeGroup>

#### `tampering`

Indicates if an identification request from an Android SDK has been tampered with.

* `true` - If the request contains anomalous device attributes that could not have been legitimately produced by Fingerprint's Android or iOS SDK (see `anomaly_score`).
* `false` - If the request is considered genuine.

#### `tampering_details.anomaly_score`

When the request contains anomalous device attributes, this value is 1. Otherwise, it is 0.

### VPN Detection for mobile devices

<Availability />

[**Android SDK v2.3.3+**](/docs/changelog-android-sdk#v2-3-3)<br />[**iOS SDK v2.3.0+**](/docs/changelog-ios-sdk#v2-3-0)

VPN apps for mobile devices are popular with both legit users and fraudsters. These VPN apps

* Protect their users’ privacy by encrypting all their traffic
* Allow their users to remain anonymous by giving them the ability to hide their real location

The VPN Detection Smart Signal for mobile devices will help you [detect](https://fingerprint.com/blog/vpn-detection-location-spoofing-fraud-prevention/) if your app is being used by a mobile device with an active VPN connection.

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  "vpn": true,
  "vpn_confidence": "high",
  "vpn_origin_timezone": "Europe/Berlin",
  "vpn_origin_country": "DE", // country code string in the ISO 3166 format
  "vpn_methods": {
      "timezone_mismatch": true,
      "public_vpn": true,
      "auxiliary_mobile": true,
      "os_mismatch": false, // always false, irrelevant for native SDKs
      "relay": false
  }
  ```
</CodeGroup>

#### `vpn`

For mobile devices, `vpn` is true when either of the four listed methods is true:

* `timezone_mismatch` - `true` when the device is in a different timezone compared to the timezone of the originating IP address.
* `public_vpn` - `true` when the IP address matches one of the known IP addresses that belong to public VPN providers.
* `auxiliary_mobile` - `true` when other proprietary detection methods indicate the presence of a VPN.
* `relay`- `true` then the IP address of the event matches anonymizing services, such as iCloud Private Relay.

Note: `os_mismatch` is web-specific, always `false` when using mobile SDKs.

#### `vpn_confidence`

The confidence level indicates how certain Fingerprint is that the current request is originating from a VPN. This confidence level is determined by evaluating multiple factors, such as `public_vpn`, `timezone_mismatch`, `auxiliary_mobile`, and other relevant methods.

To learn more about the possible values and how they are determined, see [confidence](/docs/smart-signals-reference#vpn_confidence).

#### `vpn_origin_timezone`

This field indicates the [IANA timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) that is currently set for the mobile device. In situations where a VPN is enabled, this timezone can be different from the timezone associated with the IP address.

The `vpn_origin_timezone` usually includes a country-specific reference like `"Europe/Prague"`. The `timezone_mismatch` will be `true` even if a mobile user in Prague uses a Berlin VPN server, despite both countries being in the same *GMT+2* UTC offset. For most use cases, `timezone_mismatch` functions well as an indicator of country mismatch between the mobile device and the IP address.

This field is supported for both Android and iOS devices.

#### `vpn_origin_country`

This field indicates the country in which the mobile device is physically located at the time of request. The country is represented in [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) format. It does not require Location Permissions to be enabled for your app.

This field can be very useful in situations where an active VPN can mask the true location of the device.

**Android devices**

* This field is supported only in Android SDK [v2.4.0](https://github.com/fingerprintjs/fingerprintjs-pro-android/releases/tag/v2.4.0) and higher. For lower versions of the Android SDK, the value is set to `unknown`.
* If the request is from an emulator, irrespective of the SDK version used, the value is set to `unknown`.

**iOS devices**

* This field is supported only in iOS SDK [**v2.9.0**](https://docs.fingerprint.com/docs/changelog-ios-sdk#v2-9-0) and higher. For lower versions of the iOS SDK, the value is set to `unknown`.

### Developer Tools Detection for mobile devices

<Availability />

[**Android SDK v2.6.0+**](https://docs.fingerprint.com/docs/changelog-android-sdk#v2-6-0)<br />[**iOS SDK v2.12.0+**](https://docs.fingerprint.com/docs/changelog-ios-sdk#december-2025)

This mobile smart signal detects whether developer tools are active on a mobile device. Developer tools are standard in development and testing workflows, especially on Android, but their presence on a production device can indicate exposure to reverse engineering, dynamic instrumentation, or automated abuse. The signal is most meaningful when combined with others such as [Frida detection](https://docs.fingerprint.com/docs/smart-signals-reference#frida-detection), [Android emulator](https://docs.fingerprint.com/docs/smart-signals-reference#android-emulator-detection) and [iOS simulator](https://docs.fingerprint.com/docs/smart-signals-reference#ios-simulator-detection) detection.

**What is detected per platform:**

* **iOS** detects developer activity across three complementary layers: whether developer mode is explicitly enabled on the device, whether the app was signed with a development profile rather than distributed through the App Store, and whether the app is actively being run from Xcode. The signal returns `true` if any of these indicators is detected.

As mentioned, Developer Tools detection is available from [iOS SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#december-2025). For improved detection accuracy, we recommend upgrading to [iOS SDK 2.13.0](https://docs.fingerprint.com/docs/changelog-ios-sdk#february-2026) or higher.

* **Android** detects developer activity at the device level by checking whether developer options are enabled, whether ADB (Android Debug Bridge) is active, and whether USB debugging or Wireless debugging is enabled. The signal returns `true` if any of these indicators are detected. For improved detection accuracy on Android, we recommend upgrading to [Android SDK 2.13.1](https://docs.fingerprint.com/docs/changelog-android-sdk#v2-13-1) or higher.

<CodeGroup>
  ```json Developer Tool Detected theme={"theme":"github-dark-dimmed"}
  "developer_tools": true
  ```

  ```json No Developer Tool Detected theme={"theme":"github-dark-dimmed"}
  "developer_tools": false
  ```
</CodeGroup>

### Active Call Detection

<Availability />

[Android SDK v2.16.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#june-2026)<br />[iOS SDK v2.16.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#june-2026)

Detect whether the user's device has an active cellular or internet (VoIP) call in progress at the moment of an identification event. This gives you real-time behavioral context that goes beyond device and identity signals, and is particularly useful for surfacing live social engineering attempts, for example, when a fraudster is coaching a victim by phone to read out a one-time passcode or approve a fraudulent transaction. To learn more about how you can use this signal in your app, refer to our article on [Active Call Detection](https://fingerprint.com/blog/product-update-active-call-detection/).

<Warning>
  This signal does not require any risky or sensitive permissions, and does not collect PII (such as phone numbers) or call log data.
</Warning>

<CodeGroup>
  ```json Active Call Detected theme={"theme":"github-dark-dimmed"}
  "active_call": true
  ```

  ```json No Active Call Detected theme={"theme":"github-dark-dimmed"}
  "active_call": false
  ```
</CodeGroup>

If this data isn't available (for example, when using an older SDK version), the `active_call` field is omitted from the response entirely, rather than returned as an empty value. This is consistent with how other Smart Signals behave in API v4.


# Status Page
Source: https://docs.fingerprint.com/docs/status





# Supplementary Identifiers: High Recall ID
Source: https://docs.fingerprint.com/docs/supplementary-identifiers-highrecall

Learn how High Recall ID improves visitor recognition for personalization and reduces friction for legitimate users

High Recall ID is a supplementary browser identifier optimized for coverage over precision.

You can use High Recall ID when failing to recognize a returning visitor is more expensive than an incorrect match. It is best suited for user experience and analytics workflows — such as providing personalized experiences for anonymous users, improving returning user experience, increasing conversion, etc.

For use cases where precision cannot be compromised — such as high-risk financial transactions — use the standard visitor ID instead. The standard visitor ID is optimized for precision — when there is ambiguity in browser signals between two visits, it prefers to create a new visitor ID rather than risk an incorrect match.

<Note>High Recall ID does not match across different browsers. The High Recall ID for a Safari browser will be different from that for Firefox.</Note>

## Benefits of High Recall ID

### Improves conversion by recognizing more returning visitors

When a returning visitor isn't recognized, their experience resets. Previously viewed products, applied filters, and personalization signals are lost — and they are treated as a first-time visitor. This increases drop-off and reduces conversion.

Consider an e-commerce site where an anonymous user adds a pair of running shoes to their cart and leaves without purchasing. When they return the next day, the standard visitor ID, optimized for precision, may not recognize them if the browser signals vary between these two visits. As a result, their cart is empty, and the homepage shows no relevant recommendations. But High Recall ID can tolerate these small signal variations and recognize the user across sessions — their cart is preserved, and the homepage surfaces the products they previously viewed — reducing friction and improving the chance of conversion.

### Reduces friction for legitimate users

The standard visitor ID alone may not provide enough information to reliably distinguish legitimate users from suspicious ones. High Recall ID, used alongside the standard visitor ID, provides an additional layer of context to apply the appropriate level of friction to the right users.

For example, detecting account sharing or account takeovers typically requires introducing friction — step-up authentication, re-verification, or access restrictions. When browser/device characteristics vary between sessions (e.g., a single user accessing from different locations or devices), the same friction can also be triggered for legitimate single users who aren't sharing their account. Since High Recall ID stays stable across small browser/device variations, combining it with the standard visitor ID gives you a more reliable basis for introducing the right level of friction:

* Apply little or no friction: When both the standard visitor ID and High Recall ID remain the same between sessions, the visit is likely legitimate.
* Apply moderate friction: When the High Recall ID remains the same, but only the standard visitor ID differs, there is some cause for suspicion.
* Apply high friction: When both the High Recall ID and the standard visitor ID are different between sessions, the browser is unfamiliar.

## Availability

* Only for Enterprise Plans, upon request. If you would like to try High Recall ID, please reach out to [our support team](https://fingerprint.com/support/).
* Supported only for events that originate from the [JavaScript agent](/reference/js-agent) and/or the [frontend libraries](/docs/frontend-libraries).
* Supported by all of our [Backend libraries](/reference/server-sdks).

## High Recall ID in API responses

In API responses and webhooks, High Recall ID is represented by the JSON object [`supplementary_id_high_recall`](/reference/server-api-get-event#response-supplementary-id-high-recall).

```json theme={"theme":"github-dark-dimmed"}
"supplementary_id_high_recall": {
  "visitor_id": "0jnGMkPYXX37DqVa4ZIO3f_hr",
  "visitor_found": true,
  "confidence": {
    "score": 0,
    "version": "Not Supported"
  },
  "first_seen_at": 1778086556130,
  "last_seen_at": 1778604975494
},
```

## Feature comparison: Standard Visitor ID vs. High Recall ID

|                                                                                                                                           | Standard Visitor ID                                                                | High Recall ID                                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Optimized for                                                                                                                             | Precision                                                                          | Coverage                                                                                                       |
| Confidence score                                                                                                                          | Yes                                                                                | No                                                                                                             |
| Supported for events initiated from the [JavaScript agent](/reference/js-agent) and/or the [frontend libraries](/docs/frontend-libraries) | Yes                                                                                | Yes                                                                                                            |
| Supported for events initiated from any of the [mobile SDKs](/docs/mobile-identification)                                                 | Yes                                                                                | No                                                                                                             |
| [JavaScript agent response](/reference/js-agent-get-function#get-response)                                                                | [visitor\_id](/reference/js-agent-get-function#visitor_id)                         | Included in field [`sealed_result`](/reference/js-agent-get-function#sealed_result)                            |
| [`GET /events/{event_id}`](/reference/server-api-get-event)                                                                               | [`identification`](/reference/server-api-get-event#response-identification) object | [`supplementary_id_high_recall`](/reference/server-api-get-event#response-supplementary-id-high-recall) object |
| [Webhooks](/reference/posteventwebhook)                                                                                                   | Yes                                                                                | Yes                                                                                                            |
| Supported in [DELETE /visitors/](/reference/server-api-delete-visitor-id)                                                                 | Yes                                                                                | No                                                                                                             |
| Supported in [CSV export](/docs/analytics#csv-export)                                                                                     | Exported in column `identification.visitor_id`                                     | Exported in column `supplementary_id_high_recall.visitor_id`                                                   |
| Availability                                                                                                                              | All Plans, by default                                                              | Enterprise Plans only, upon request                                                                            |


# Suspect Score
Source: https://docs.fingerprint.com/docs/suspect-score

Suspect Score is an easy way to integrate Smart Signals into your fraud protection work flow. It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity.

# What is Suspect Score

**Suspect Score** is a single risk score that helps you quickly identify suspicious activity using Smart Signals.

Instead of analyzing each signal individually, Suspect Score combines them into one value—making it easier to make fraud decisions in real time.

Each Smart Signal contributes to the score with a predefined weight.

The more suspicious signals are triggered, the higher the final score.

It's part of the Smart Signals payload available in Server API, Webhooks and Sealed Client Results.

<Warning>
  **How new signals affect your score**

  When new Smart Signals are introduced: **New customers** automatically receive default weights **Existing customers** start with a weight of 0 to avoid impacting existing logic. You can enable and configure these weights at any time in the [*Custom Weights Configuration*](/docs/suspect-score#custom-weights-configuration) section.
</Warning>

## Suspect Score Weights

Each Smart Signal has its own **weight**, contributing to the final **score**. The weights are currently based on the probability that the selected Smart Signal is triggered on a global scale. Smart Signals that are less likely to be triggered have stronger weights, and vice versa.

Weights might have slightly different values based on the request's originating platform (web, Android and iOS). This is caused by different representation of average traffic for each platform.

<Info>
  **N/A** in the table below means that the signal is not reflected in the *Suspect Score*. This might happen for two reasons - either the signal is not available on that particular platform (see our [Smart Signals introduction page](/docs/smart-signals-introduction) for signal availability) **or** the signal had low incidence rate and would skew the computation too much (the weight would be extremely high).
</Info>

### Weights Table

| Smart Signal                                                                                                   | Web/Browser | Android | iOS |
| :------------------------------------------------------------------------------------------------------------- | :---------- | :------ | :-- |
| [Bot Detection](/docs/smart-signals-reference#browser-bot-detection) (`bot.type == bad`)                       | 7           | N/A     | N/A |
| [Incognito Detection](/docs/smart-signals-reference#browser-incognito-detection) (`incognito`)                 | 4           | N/A     | N/A |
| [VPN Detection](/docs/smart-signals-reference#vpn_methods) (`timezone_mismatch`)                               | 3           | 4       | 4   |
| [VPN Detection](/docs/smart-signals-reference#vpn_methods) (`public_vpn`)                                      | 4           | 5       | 5   |
| [VPN Detection](/docs/smart-signals-reference#vpn_methods) (`os_mismatch`)                                     | N/A         | N/A     | N/A |
| [VPN Detection](/docs/smart-signals-reference#vpn_methods) (`auxiliary_mobile`)                                | N/A         | 6       | 6   |
| [VPN Detection](/docs/smart-signals-reference#vpn_methods) (`relay`)                                           | 4           | 4       | 4   |
| [Tampering Detection](/docs/smart-signals-reference#browser-tamper-detection) (`AnomalyScore > 0.5`)           | 8           | N/A     | N/A |
| [Tampering Detection](/docs/smart-signals-reference#browser-tamper-detection) (`Antidetect Browser`)           | 8           | N/A     | N/A |
| [Virtual Machine Detection](/docs/smart-signals-reference#virtual-machine-detection) (`virtual_machine`)       | 14          | N/A     | N/A |
| [Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection) (`developer_tools`)       | 8           | 8       | 16  |
| [Device Rarity Detection](/docs/smart-signals-reference#device-rarity-detection) (`rare_device`)               | N/A         | N/A     | N/A |
| [Velocity Signals](/docs/smart-signals-reference#velocity-signals) (`velocity`)                                | N/A         | N/A     | N/A |
| [Privacy-Focused Settings](/docs/smart-signals-reference#privacy-focused-settings) (`privacy_settings`)        | 6           | N/A     | N/A |
| [IP Blocklist](/docs/smart-signals-reference#ip-blocklist-matching) (`email_spam`)                             | 14          | 12      | 13  |
| [IP Blocklist](/docs/smart-signals-reference#ip-blocklist-matching) (`attack_source`)                          | 13          | 13      | 13  |
| [Tor Exit Node](/docs/smart-signals-reference#ip-blocklist-matching) (`tor`)                                   | 14          | 16      | 17  |
| [Data Center Proxy](/docs/smart-signals-reference#proxy-detection) (`proxy_details.proxy_type == data_center`) | 14          | 12      | 15  |
| [Residential proxy](/docs/smart-signals-reference#proxy-detection) (`proxy_details.proxy_type == residential`) | 6           | 6       | 6   |
| [Android Emulator Detection](/docs/smart-signals-reference#android-emulator-detection) (`emulator`)            | N/A         | 9       | N/A |
| [Rooted Device Detection](/docs/smart-signals-reference#rooted-device-detection) (`root_apps`)                 | N/A         | 12      | N/A |
| [Cloned App Detection](/docs/smart-signals-reference#cloned-app-detection) (`cloned_app`)                      | N/A         | 9       | N/A |
| [Jailbroken Device Detection](/docs/smart-signals-reference#jailbroken-device-detection) (`jailbreak`)         | N/A         | N/A     | 10  |
| [Frida Detection](/docs/smart-signals-reference#frida-detection) (`frida`)                                     | N/A         | 14      | N/A |
| [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection) (`mitm_attack`)                   | N/A         | 14      | 14  |
| [High-Activity Device](/docs/smart-signals-reference#high-activity-device) (`high_activity`)                   | 6           | 5       | 6   |
| [iOS Simulator Detection](/docs/smart-signals-reference#ios-simulator-detection) (`simulator`)                 | N/A         | N/A     | 16  |

# How to Use Suspect Score

Suspect Score can be used to flag and review possible suspicious activity. It can be used to **quickly integrate Smart Signals** into your fraud protection workflow without the need to explore fraud correlations of individual Smart Signals.

<CodeGroup>
  ```json Suspect Score in /v4/events/:event_id and Webhooks theme={"theme":"github-dark-dimmed"}
  {
    // ...
    "suspect_score": 10
  }
  ```
</CodeGroup>

# Custom Weights Configuration

Fingerprint allows you to customize Suspect Score weights in two ways:

* Automatic weight generation using fraud-labeled data
* Manual adjustment of signal weights

Automatic weight generation allows you to train Suspect Score weights using your own fraud data, making the score better reflect fraud patterns in your environment.

## Automatic Weight Generation Using Fraud-Labeled Data

You can train Suspect Score using your own fraud-labeled data to better reflect your specific risk patterns.

Fingerprint analyzes your dataset and recommends optimized weights based on how each Smart Signal correlates with fraud. Based on this analysis, the system generates recommended weights for each signal.

These recommendations help tune the Suspect Score so it better reflects the fraud patterns specific to your traffic.

### Preparing Your Dataset

Your dataset must meet the following requirements:

Format

* CSV file
* Minimum count of events to upload is 1,000
* Maximum file size: 10 MB

You can download an example template to see the expected format.

Required fields

Your dataset should include:

* Request ID: the Fingerprint request identifier
* Fraud label: indicates whether the visitor was fraudulent

The system uses these fields to analyze which Smart Signals appear most frequently in fraudulent activity.

### Uploading Your Dataset

Follow these steps to generate Suspect Score weights using fraud-labeled data.

1. **Navigate to Suspect Score Analytics**

Open the Dashboard and go to:

Smart Signals → Suspect Score → Analysis

2. **Upload Your File**

You can upload your dataset in two ways:

* Drag and drop a CSV file into the upload area
* Click Choose to select a file from your computer

3. **Start the Training Process**

After the file is uploaded, Fingerprint will begin analyzing the dataset. During this step the system:

* Evaluates each Smart Signal
* Measures how strongly it correlates with fraudulent activity
* Generates optimized weights for the Suspect Score

The analysis process may take up to 30 minutes depending on the dataset size.

4. **Review Generated Weights**

After the analysis completes, Fingerprint generates recommended weights for the Smart Signals.

These recommendations appear in the Processed Data section where you can review and decide whether to apply them.

### Reviewing Processed Fraud Data

All analyzed datasets appear in the Processed Data section.

This section acts as a history log for fraud analysis runs and allows you to:

* Track uploaded datasets
* Monitor analysis results
* Review recommended weight changes
* Apply or reject updates to your Suspect Score configuration

### Dataset Status

Processed datasets are organized into three categories.

**Needs Review**

Files listed under Needs review contain recommendations that have not yet been applied.

These datasets require review before any changes are applied.

**Accepted**

The Accepted section contains datasets whose recommendations were approved and applied.

Once accepted:

* The recommended weights are applied to your Suspect Score configuration
* Future requests will be scored using the updated weights

**Rejected**

Datasets listed under Rejected were reviewed but not applied.

Rejected datasets remain visible for reference but do not affect the Suspect Score configuration.

### Reviewing Recommended Changes

When you click a dataset in the Needs review section, a review panel opens that displays both signal-level changes and a suggested overall threshold.

This threshold represents the score above which a request is likely to be considered suspicious, based on your uploaded fraud data.

The interface groups Smart Signals into two categories.

**Changed**

Signals listed under Changed have updated weights based on the fraud patterns detected in your dataset.

These adjustments increase or decrease the influence of the signal in the Suspect Score calculation.

**Unchanged**

Signals listed under Unchanged were analyzed but did not show a strong correlation with fraud in the uploaded dataset.

Their weights remain the same.

## Manual adjustment of signal weights

You can manually adjust weights to match your use case.

Open the Dashboard and go to:

2. Smart Signals → Suspect Score
3. Select the correct tab based on the platform for which you would like to configure the weights (**Web**, **iOS** SDK or **Android** SDK)

<Frame>
  <img alt="" />
</Frame>

4. Input your preferred weights as integers between 0 and 10000 on the right
5. Click on **Save Changes**

<Frame>
  <img alt="" />
</Frame>

The changes will propagate in a matter of minutes and you will start receiving the Suspect Score based on your custom weights.

## Configuring Weights by Confidence Level

**VPN Detection** and **Residential Proxy Detection** support confidence-based weighting. Instead of a single weight per signal, you can assign separate weights to low, medium, and high confidence detections to better reflect your risk tolerance.

### VPN Detection

By default, VPN Detection uses **method-based weighting**, where each detection method (`publicVPN`, `timezoneMismatch`, and others) has its own configurable weight. You can switch to **confidence-based weighting** to assign a single weight per confidence level instead.

Only one mode can be active at a time. Switching modes preserves the other configuration but deactivates it until you switch back.

To switch VPN Detection to confidence-based weighting:

1. Open the Dashboard and go to **Smart Signals → Suspect Score**
2. Under **VPN Detection**, select **Confidence** from the weighting mode selector
3. Input your preferred weights for **Low confidence**, **Medium confidence**, and **High confidence**
4. Click **Save Changes**

The default confidence-based weights for VPN Detection are:

| Confidence Level | Web/Browser | Android | iOS |
| :--------------- | :---------- | :------ | :-- |
| Low              | 2           | 2       | 2   |
| Medium           | 4           | 5       | 5   |
| High             | 6           | 7       | 7   |

### Residential Proxy Detection

Residential Proxy Detection uses a **flat-value weighting** by default. You can switch to confidence-based weighting, and the page then displays three separate weight inputs, one for each confidence level.

To switch Residential Proxy detection to confidence-based weighting:

1. Open the Dashboard and go to **Smart Signals → Suspect Score**
2. Under **Residential Proxy**, select **Confidence** from the weighting mode selector
3. Input your preferred weights for **Low confidence**, **Medium confidence**, and **High confidence**
4. Click **Save Changes**

The default confidence-based weights are:

| Confidence Level | Web/Browser | Android | iOS |
| :--------------- | :---------- | :------ | :-- |
| Low              | 2           | 2       | 2   |
| Medium           | 4           | 4       | 4   |
| High             | 6           | 6       | 6   |

## Disabling a Weight Completely

Some scenarios like the one mentioned above with the high VPN incidence rate might result in the need to disable a particular Smart Signal. In those cases it's possible to set the weight to zero through a dedicated button in the user interface.

<Frame>
  <img alt="" />
</Frame>

The changes have to be saved at the bottom of the page to propagate.

## Restoring Defaults

We will always provide a set of default values based on our internal understanding of Smart Signal incidence rates (the statistical analysis mentioned in a previous section). Individual Suspect Score weights can be restored to those defaults by clicking on the **restore default weight value** button.

<Frame>
  <img alt="" />
</Frame>

The changes have to be saved at the bottom of the page to propagate.

***

What’s Next

Want to know the detail about each individual Smart Signal? Visit our Smart Signals Overview page to get more information.

* [Smart Signals Overview](/docs/smart-signals-reference)


# Linking and tagging information
Source: https://docs.fingerprint.com/docs/tagging-information



The visitor ID provided by Fingerprint Identification is especially useful when combined with information you already know about your users, for example, account IDs, order IDs, etc. You can follow user actions, track logged-in devices, and recognize malicious behavior.

| Use case                         | Description                                                                                                                                                                               |
| :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account Takeover Prevention**  | Link visitor ID to account username to prevent malicious login attempts. Require multi-factor authentication if an unfamiliar visitor ID is trying to log in.                             |
| **Account Sharing Prevention**   | Link visitor ID to account username to prevent users from sharing accounts.  Flag accounts that exceed a certain number of visitor IDs as suspected of account sharing.                   |
| **Trial Abuse Prevention**       | Link visitor ID to account username to prevent multiple sign-ups from a single visitor. Flag visitor IDs that exceed a certain number of associated accounts as suspected of trial abuse. |
| **Credit Card Fraud Prevention** | Link visitor ID to hashed credit card numbers to prevent repeated use of faulty credit cards. Flag visitors that exceed a certain number of credit cards.                                 |

There are three ways to link visitor IDs with your own metadata:

* **On your server, in your own database**: Process visitor ID and metadata on your server and store them in your own database table. This approach is secure, durable, and recommended for most security use cases.
* **On your client, during the identification event**: Use the `linkedId` or `tags` parameters to pass your metadata to the Fingerprint API when requesting the visitor ID. Fingerprint stores this data for 30 or 90+ days, depending on your plan. This method is recommended for use cases where spoofing and long-term storage are not a concern.
* **On your server, after the identification event**: Update existing events by sending the `linked_id` or `tags` information to the `/v4/events/:event_id` endpoint with a PATCH request. This method allows for modifying event data after the initial identification, which is useful if the information was not available at the time of the client-side request. The updated data is stored the same way as the client-side parameters.

## Linking information in your own database

On the client, use the Fingerprint JavaScript agent to get a visitor ID and send it to your server for processing.

```javascript client/login.js theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from '@fingerprint/agent';

// ...
const fp = Fingerprint.start({ apiKey: PUBLIC_API_KEY });

fp.get()
  .then((result) => {
    const { visitor_id, event_id } = result;
    fetch(`/api/linking-data`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        visitor_id,
        event_id,
        accountId: '123456',
      }),
    });
  });
```

Inside the server endpoint, verify the authenticity of the visitor ID and save it to your database together with your internal ID or other metadata.

```javascript server/api/linking-data.js theme={"theme":"github-dark-dimmed"}
export default async function submitEndpointHandler(req, res) {
  const { event_id, visitor_id, accountId } = req.body;
  if (!areIDsValid(event_id, visitor_id)) {
    res.status(400).send('Something went wrong.');
    return;
  }
  saveToAccountsDatabaseTable({
    visitor_id,
    accountId
  });
  res.status(200).send('visitor ID and accountId link saved to database');
}
```

<Note>
  [Verifying the visitor ID](/docs/protecting-from-client-side-tampering) involves calling our [Server API](/reference/server-api) to make sure it was recently generated by Fingerprint. See our [Fingerprint Use Cases](https://github.com/fingerprintjs/fingerprintjs-pro-use-cases) project for implementation examples.
</Note>

This approach requires more setup but is more secure. You have full control over the data and can store it indefinitely.

## Using `linkedId` and `tags` on the client

Associate your data with a visitor ID using the `linkedId` or `tags` parameter of the [JavaScript agent](/reference/js-agent-get-function#linkedid)'s `get()` function.

```html client/identify.js theme={"theme":"github-dark-dimmed"}
<script>
  const fpPromise = import('https://fpjscdn.net/v4/PUBLIC_API_KEY')
    .then(Fingerprint => Fingerprint.start());

  // Pass your own data to get()
  fpPromise
    .then(fp => fp.get({
      linkedId: "accountNum12345",
      tags: {
        orders: ["orderNum6789"],
        location: { city: "Atlanta", country: "US" }
      } 
    }))
    .then(result => console.log(result.visitor_id));
</script>
```

Your information will be part of that identification event and available through [Webhooks](/docs/webhooks) and [Server API](/reference/server-api). You can use webhooks to automatically store the events in your own database indefinitely.

```json Event data theme={"theme":"github-dark-dimmed"}
{
  "event_id": "1680110819553.B2U183",
  "linked_id": "accountNum12345",
  "tags": {
    "location": {
      "city": "Atlanta",
      "country": "US"
    },
    "orders": [
      "orderNum6789"
    ]
  },
  "identification": {
    "visitor_id": "cMBjS1eCyObMgQ4BiYEO"
    // ...
  }
}
```

## Updating `linked_id` and `tags` on the server

Associate `linked_id` or `tags` data with a visitor ID using the `/v4/events/:event_id` endpoint of the Fingerprint Server API with a PATCH request.

On the client, use the Fingerprint JavaScript agent to get an event ID and send it to your server.

```javascript client/order.js theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from '@fingerprint/agent';

// ...
const fp = Fingerprint.start({ apiKey: PUBLIC_API_KEY });

fp.get()
  .then((result) => {
    const { event_id } = result;

    // Send information to the server for processing the order
    // At this point, we do not have the order ID yet
    fetch(`/api/process-order`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        event_id,
        // Any other relevant information related to the order process can be sent here. e.g., cart ID, products, etc.
      }),
    });
  });
```

On the backend, use the event ID to make a PATCH request to the `/v4/events/:event_id` endpoint of the Fingerprint Server API.

```javascript server/api/process-order.js theme={"theme":"github-dark-dimmed"}
const response = await fetch(`https://api.fpjs.io/v4/events/${event_id}`, {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer SECRET_API_KEY",
  },
  body: JSON.stringify({
    linked_id: orderId, // Use the order ID as the linked_id
    tags: {
      orderStatus: "completed", // Example additional tag
      paymentMethod: "credit_card", // Example additional tag
    },
  }),
});
```

Your information will be added to the event and available through the Dashboard and [Server API](/reference/server-api).

```json Event data theme={"theme":"github-dark-dimmed"}
{
  "event_id": "1730134629123.MALXYZ",
  "linked_id": "orderNum12345",
  "tags": {
    "orderStatus": "completed",
    "paymentMethod": "credit_card"
  },
  "identification": {
    "visitor_id": "cxhbePz123zrMpABC2r3"
    // ...
  }
}
```

Tagged or linked information has no influence on identification accuracy. Both `tags` and `linked_id` are arbitrary pieces of information linked to a particular Fingerprint event for your own use.

### What's the difference between `linked ID` and `tags`?

* `linked_id` is a simple string identifier. Fingerprint indexes it so you can use it as a filter when retrieving the [visit history](/reference/server-api-search-events) of a specific visitor ID via the [Server API](/reference/server-api). Objects, arrays, or non-string values passed to `linked_id` are converted to strings.
* `tags` accepts any simple value or any JavaScript object smaller than 16KB. It cannot be used to filter visits but can store a large amount of structured data about your visitor.

<Warning>
  **Limitations**

  #### Spoofing

  Defining `linkedId` and `tags` in the browser is vulnerable to tampering, as is all client-side code. More sophisticated attackers can spoof the `linkedId` or `tags` and send any arbitrary value to Fingerprint API.
  We don't recommend relying on `linked_id` and `tags` for security use cases. Link visitor IDs to other metadata [on your server instead](#linking-information-in-your-own-database).

  #### Data storage

  Fingerprint stores the visit history [for a limited time](/docs/billing#account-limits) (30 days for accounts, 90 or more for Enterprise). After that, the identification events and their `linked_id` and `tags` values will not be available through the Server API.
  If your use case requires long-term data storage, you can use webhooks to [store the events](/docs/regions#data-retention) in your database as they happen or link visitor IDs to your metadata [on your server entirely](#linking-information-in-your-own-database).
</Warning>

### Hashing linked or tagged information

Fingerprint Identification is often useful when your internal IDs are unavailable, for example, on a login or signup page. To avoid sending emails, phone numbers, or other sensitive information to Fingerprint, you can hash the information first and pass only the hash into the `tags` or `linkedId`.

<Note>
  **Hashing explained**

  A [hash function](https://en.wikipedia.org/wiki/Hash_function) is a mathematical function that takes an input of arbitrary length and outputs a random-looking fixed-length representation of it. Hash functions are used to represent the original data in a more efficient and secure way.

  * For the same input, a hash function always returns the same result.
  * Any change in input leads to a different result (collisions are rare).
  * Computing the original input from its hash is practically impossible.
</Note>

You can use the [crypto browser API](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) to hash sensitive information before sending it to Fingerprint:

```javascript Hashing information before passing it to &#x60;linkedId&#x60; theme={"theme":"github-dark-dimmed"}
async function hash(sensitiveInfo) {
  const hashBytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(sensitiveInfo));
  return Array.prototype.map
    .call(new Uint8Array(hashBytes), (byte) => byte.toString(16).padStart(2, '0'))
    .join('');
}

const email = "personalemail@gmail.com";
const linkedId = await hash(email);
// linkedId is now '9663a85cfcd473cba225ab15bbb4ca6a424203297f62e87abd5fa897a6f0aef7'

fp.get({ linkedId })
  .then(result => console.log(result.visitor_id));
```

For example, you might want to reduce multiple signups from the same visitor ID. On submit, you can use the Server API to retrieve all email hashes recently linked to that visitor ID. Then flag or block the visitor ID if it exceeds a certain number of linked emails.


# Terms of service
Source: https://docs.fingerprint.com/docs/terms-of-service

Effective date: Nov 1, 2026. | [Archived Versions](/docs/legal-archive)

These Terms of Service, as amended from time to time (“**Terms**”), are entered into by and between FingerprintJS, Inc., a Delaware corporation (“**FingerprintJS**”), and the customer identified during Onboarding (“**Customer**”).

“**Onboarding**” means the process by which Customer procures from FingerprintJS a subscription to use the Service through a self-service sign-up process made available on FingerprintJS’s website. These Terms and any terms agreed-to during Onboarding are collectively referred to herein as the “**Agreement**”. By accessing or using the Service (as defined below) or clicking a button or checking a box marked “Submit”, “I Agree”, “I Accept”, or something similar, or by otherwise affirmatively manifesting assent to this Agreement, Customer signifies that Customer has read, understood, and agrees to be bound by this Agreement as of Customer’s completion of Onboarding (such date, the “**Effective Date**”).

**PLEASE NOTE: THE SERVICE IS MADE AVAILABLE ON A SUBSCRIPTION BASIS. YOUR SUBSCRIPTION FOR THE SERVICE AND THIS AGREEMENT WILL BE AUTOMATICALLY RENEWED FOR SUCCESSIVE BILLING PERIODS AT OUR THEN-CURRENT PRICING UNLESS YOU OPT OUT OF THE AUTO-RENEWAL IN ACCORDANCE WITH SECTION 5.iv BELOW.**

## 1. Fingerprint Service

### 1.i Subscription

Subject to the terms and conditions of this Agreement, and in each case solely during the Subscription Term: (a) FingerprintJS hereby grants Customer a limited, revocable, non-exclusive, non-transferable (except in compliance with Section 13.i) right and license to install the Agent on the Customer Website solely as necessary to use the Service in accordance with the Documentation; ii) right and license to install or use the Mobile SDKs; and (b) Customer and its Users may remotely access the Dashboard. Such use is limited to Customer's internal use. Customer and each User must keep Credentials confidential and not share them with anyone else. Customer is responsible for (i) its Users’ compliance with this Agreement and actions taken through their Credentials and (ii) disabling access to the Service by any User who is no longer an employee of Customer.

### 1.ii Restrictions

Customer shall not use the Service for any purposes beyond the scope of the access granted in this Agreement. Customer shall not at any time, directly or indirectly (and shall not allow and third party to): (a) copy, modify, or create derivative works of the Service or any component thereof; (b) rent, lease, lend, sell, license, sublicense, assign, distribute, publish, transfer, or otherwise make available the Service or any component thereof; (c) reverse engineer, disassemble, decompile, decode, adapt, or otherwise attempt to derive or gain access to the Agent or Mobile SDKs or any other software component of the Service, in whole or in part; (d) remove any proprietary notices from the Service or any component thereof; (e) use the Service or any component thereof in any manner or for any purpose that infringes, misappropriates, or otherwise violates any intellectual property right or other right of any person, or that violates any applicable law; or (f) use the Service or any component thereof for any benchmarking purpose or for the purpose of developing or assisting in the development of a product or service that competes with the Service, that utilizes functions and features similar to those of the Service or that copies the Service or any part, feature, function, graphics or user interface of the Service; (g) use browser automation tools or any software applications that run automated tasks to create accounts, subscriptions, users or other resources in the Service; (h) bypass or ignore instructions that control access to the Service, including attempting to circumvent any rate limiting systems by using multiple API keys, directing traffic through multiple IP addresses, or otherwise obfuscating the source of traffic you send to the Service; (i) attempt to gain unauthorized access to, interfere with, damage, or disrupt any parts of the Service, the server on which the Service is stored, or any server, computer, or database connected to the Service; (j) use the Service to transmit any computer viruses, worms, defects, Trojan horses, or other items of a destructive nature to violate the security of any computer network, crack passwords or security encryption codes; or (k) access, retrieve, or index any portion of the Service for purposes of constructing or populating a searchable database.

## 2. Support Terms

During the Subscription Term, FingerprintJS will use commercially reasonable efforts to respond in a timely manner to support tickets sent by Customer to [support@fingerprint.com](mailto:support@fingerprint.com).

## 3. Data Rights

### 3.i Visitor Data and Personal Information

#### 3.i(a) License Grant

Customer grants FingerprintJS a non-exclusive, non-transferable (except in compliance with Section 13.i) right and license to: (i) use, copy, store, transmit, display, modify and create derivative works of Visitor Data as necessary to provide the Service to Customer under this Agreement and as otherwise described in the Privacy policy; (ii) aggregate the Visitor Data with other data in a de-identified form and to use such derived data for any lawful purpose both during and after the Subscription Term; and (iii) if Customer elects to use the DRN as part of the Service, use any Fraud Identification Data that the Customer submits to FingerprintJS to maintain the DRN and make the Fraud Identification Data contained within the DRN available to other customers of FingerprintJS.

#### 3.i(b) DRN

Customer acknowledges that the license in Section 3.i.a(iii) shall survive termination of the Agreement or termination of the Customer’s use of or access to the DRN as part of the Service, and FingerprintJS shall not be required to delete any Fraud Identification Data maintained by FingerprintJS as part of the DRN on termination of the Agreement or on termination of Customer’s use of or access to the DRN.

#### 3.i(c) Data Processing

If Customer is established in the European Economic Area, the United Kingdom, or Switzerland, or if any Personal Information processed by FingerprintJS in connection with the Service otherwise falls within the scope of the European Data Privacy Legislation, FingerprintJS will process any such Personal Information in accordance with FingerprintJS’ GDPR data processing addendum, which will be incorporated by reference into this Agreement and can be accessed at [https://dev.fingerprint.com/docs/dpa-gdpr](https://dev.fingerprint.com/docs/dpa-gdpr) (as modified from time to time). If Customer is subject to US Data Protection Laws or if any Personal Information processed by FingerprintJS in connection with the Service includes Personal Information within the scope of such US Data Protection Laws, FingerprintJS will process any such Personal Information in accordance with FingerprintJS’ US Data Protection Laws data processing addendum, which will be incorporated by reference into this Agreement and can be accessed [https://docs.fingerprint.com/docs/dpa-usspl](https://docs.fingerprint.com/docs/dpa-usspl) (as modified from time to time). Notwithstanding the foregoing, if the parties agree in writing to use a different data processing addendum, such data processing addendum will apply in lieu of either of the foregoing data processing addenda.

### 3.ii Usage Data

FingerprintJS may collect Usage Data and use it to operate, improve and support the Service and for other lawful business practices, such as analytics, benchmarking and reports. However, FingerprintJS will not disclose Usage Data to third parties (other than duly appointed service providers), including in benchmarks or reports, unless it has been (a) de-identified so that it does not individually identify Customer, its Users or any other person and (b) aggregated with usage data across other FingerprintJS customers.

### 3.iii Security

FingerprintJS uses reasonable technical and organizational measures designed to protect the Service and Visitor Data.

### 3.iv Location

Customer may elect to deploy the Service in the following regions: United States, European Union, and Asia. If United States is selected, Visitor Data that contains Personal Information will be stored in data centers located in the US; if European Union is selected, Visitor Data that contains Personal Information will be stored in data centers located in the EU; if Asia is selected, Visitor Data that contains Personal Information will be stored in data centers located in India. Data derived from Visitor Data that does not contain personal information may be stored in data centers located in a region different than their primary region.

## 4. Customer Obligations

Customer (a) is solely responsible for its Visitor Data (including its content) and compliance with all Applicable Laws in its use of the Service and (b) represents and warrants that it has made all necessary disclosures and obtained all necessary consents required for its submission of data and granting of rights to FingerprintJS under this Agreement without violating or infringing any third-party intellectual property or privacy rights or Customer or third-party terms of service or privacy policies.

## 5. Commercial Terms

### 5.i Types of Plans

As described on the FingerprintJS pricing page (located at [https://fingerprint.com/pricing/](https://fingerprint.com/pricing/)) (the “**Pricing Page**”), two tiers of the Service are made available by FingerprintJS: (a) a free tier (“**Free Plan**”) and (b) a paid tier (“**Paid Plan**”). Except as otherwise expressly noted, both the Free Plan and Paid Plan are subject to the terms of this Agreement.

### 5.ii Fees and Taxes

Fees are as described on the Pricing Page. All fees and expenses are non-refundable except as set out in Section 10.i (FingerprintJS Indemnity). Customer is responsible for any sales, use, GST, value-added, withholding or similar taxes or levies that apply to any amounts payable by Customer hereunder, whether domestic or foreign (“**Taxes**”), other than FingerprintJS’s income tax. Fees and expenses are exclusive of Taxes.

### 5.iii Payment; Billing

Customer must provide FingerprintJS with a current, valid accepted method of payment (as it may be updated from time to time, “**Payment Method**”) in order to purchase and use a Paid Plan. FingerprintJS uses a third party payment processor (currently Stripe, Inc. (“**Stripe**”)) to process payments using the provided Payment Method. By starting a Paid Plan and providing or designating a Payment Method, Customer agrees to be bound by Stripe’s Services Agreement available at [https://stripe.com/us/legal](https://stripe.com/us/legal) and further authorizes FingerprintJS to charge Customer any applicable fees at the then current rate, and any other charges Customer may incur in connection with Customer’s use of the Service, to Customer’s Payment Method. Customer acknowledges that the amount billed each period may vary for reasons that may include the particular number of Unique Browser Instances during such period, different plan options or services, promotional offers, and/or changing a plan, and Customer authorizes FingerprintJS to charge Customer’s Payment Method for such varying amounts, which may be billed in one or more charges. Fees for the Service may be billed at the beginning of the applicable billing cycle or at a later period, depending on the specific details of the Customer’s Paid Plan (as described on the Pricing Page).

### 5.iv Automatic Renewal

After Customer’s initial billing cycle, and again after any subsequent billing cycle, Customer’s subscription will automatically commence on the first day following the end of such period (each a “**Renewal Commencement Date**”) and continue for an additional equivalent period, at FingerprintJS’s then-current price for such subscription. Customer agrees that its Payment Method will be subject to this automatic renewal feature unless Customer cancels its subscription at least thirty (30) days prior to the Renewal Commencement Date. By subscribing, Customer authorizes FingerprintJS to charge Customer’s Payment Method for the initial billing cycle and any subsequent billing cycle. Customer reserves the right to change the timing of its billing as indicated in this Section 5.iii. FingerprintJS may authorize your Payment Method in anticipation of subscription or other charges.

### 5.v Fee Changes

FingerprintJS, in its sole discretion and at any time, may modify the fees for the Service. Any fee change will become effective at the end of the then-current billing cycle. FingerprintJS will provide Customer with reasonable prior notice of any change in fees. Customer’s continued use of Service after a fee change comes into effect constitutes Customer’s agreement to pay the modified fee amount.

### 5.vi Suspension of Service

FingerprintJS may suspend Customer’s access to the Service if (a) Customer breaches Section 1.ii (Restrictions) or Section 4 (Customer Obligations), (b) if Customer’s account is 30 days or more overdue, (c) if Customer’s actions risk harm to other customers or the security, availability or integrity of the Service, or (d) in the case of Free Plan accounts, if no API calls have been made for a continuous period of 90 days. Where practicable, FingerprintJS will use reasonable efforts to provide Customer with prior notice of the suspension. Once Customer resolves the issue requiring suspension, FingerprintJS will promptly restore Customer’s access to the Service in accordance with this Agreement. For Free Plan accounts suspended due to inactivity, FingerprintJS may terminate the account if no activity resumes within 7 days after notice of suspension is provided to Customer.

## 6. Warranty Disclaimer

### 6.i Disclaimers

THE SERVICE IS PROVIDED “AS IS”. FINGERPRINTJS AND ITS SUPPLIERS MAKE NO OTHER WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NONINFRINGEMENT. FINGERPRINTJS DOES NOT WARRANT VISITOR DATA WILL BE ACCURATE OR PRESERVED WITHOUT LOSS. FINGERPRINTJS IS NOT LIABLE FOR DELAYS, FAILURES OR PROBLEMS INHERENT IN USE OF THE INTERNET AND ELECTRONIC COMMUNICATIONS OR OTHER SYSTEMS OUTSIDE FINGERPRINTJS’S CONTROL. FEATURES OF THE SERVICE DESIGNED TO DETECT AND FILTER CATEGORIES OF DATA HAVE INHERENT LIMITATIONS. FINGERPRINTJS DOES NOT GUARANTEE THAT THE SERVICE WILL DETECT OR FILTER ALL DATA WITH COMPLETE ACCURACY. CUSTOMER IS SOLELY RESPONSIBLE FOR ITS OWN DATA HANDLING POLICIES. CUSTOMER MAY HAVE OTHER STATUTORY RIGHTS, BUT ANY STATUTORILY REQUIRED WARRANTIES WILL BE LIMITED TO THE SHORTEST LEGALLY PERMITTED PERIOD. CUSTOMER HEREBY AGREE TO WAIVE ALL LAWS THAT MAY LIMIT THE EFFICACY OF SUCH RELEASES CONTAINED HEREIN. WITHOUT LIMITING THE FOREGOING, CUSTOMER SPECIFICALLY AGREES TO WAIVE THE PROVISIONS OF CALIFORNIA CIVIL CODE SECTION 1542, WHICH PROVIDES “A GENERAL RELEASE DOES NOT EXTEND TO CLAIMS WHICH THE CREDITOR DOES NOT KNOW OR SUSPECT TO EXIST IN HIS FAVOR AT THE TIME OF EXECUTING THE RELEASE, WHICH IF KNOWN BY HIM MUST HAVE MATERIALLY AFFECTED HIS SETTLEMENT WITH THE DEBTOR.”

## 7. Term and Termination

### 7.i Term

This Agreement starts on the Effective Date and continues until terminated in accordance with this Agreement (the “**Subscription Term**”).

### 7.ii Termination

Either party may terminate this Agreement if the other party (a) fails to cure a material breach of this Agreement (including a failure to pay fees) within 30 days after written notice, (b) ceases operation without a successor or (c) seeks protection under a bankruptcy, receivership, trust deed, creditors’ arrangement, composition or comparable proceeding, or if such a proceeding is instituted against that party and not dismissed within 60 days. Notwithstanding anything to the contrary in this Agreement, FingerprintJS may, in its sole and absolute discretion (x) terminate any Free Plan at any time and for any reason without notice and (y) terminate any Paid Plan for any reason with thirty (30) days’ prior written notice.

### 7.iii Effect of Termination

Upon expiration or termination of this Agreement, (a) Customer’s right to use the Service (including its license to any Agent and the Mobile SDKs) will terminate, and (b) Customer shall immediately cease any and all use of and access to the Service. At the disclosing party’s request upon expiration or termination of this Agreement, the receiving party will delete all of the disclosing party’s Confidential Information (as defined in Section 11) in its possession or control. Customer acknowledges that following termination it shall have no further access to any Visitor Data input into the Service, and that FingerprintJS may delete any such data as may have been stored by FingerprintJS at any time. Visitor Data and other Confidential Information may be retained in the receiving party’s standard backups after deletion but will remain subject to this Agreement’s confidentiality restrictions.

### 7.iv Survival

These Sections survive expiration or termination of this Agreement: 1.ii (Restrictions), 3.i (Visitor Data) (but solely as it relates to derived data and 3.i.c. (Data Processing)), 3.ii (Usage Data), 4 (Customer Obligations), 5.ii (Fees and Taxes), 6.i (Disclaimers), 7.iii (Effect of Termination), 7.iv (Survival), 8 (Ownership), 9 (Limitations of Liability), 10 (Indemnification), 11 (Confidentiality), 13 (General Terms) and 14 (Definitions). Except where an exclusive remedy is provided, exercising a remedy under this Agreement does not limit other remedies a party may have.

## 8. Ownership

Neither party grants the other any rights or licenses not expressly set out in this Agreement. Except for FingerprintJS’s use rights in this Agreement, between the parties Customer retains all intellectual property and other rights in Visitor Data provided to FingerprintJS. Except for Customer’s limited license and use rights set forth in Section 1 of this Agreement, FingerprintJS and its licensors retain all intellectual property and other rights in the Service, the Agent and Mobile SDKs, and any related FingerprintJS technology, including any modifications or improvements to these items made by FingerprintJS. If Customer provides FingerprintJS with feedback or suggestions regarding the Service or other FingerprintJS offerings, FingerprintJS may use the feedback or suggestions without restriction.

## 9. Limitations of Liability

### 9.i Consequential Damages Waiver

NEITHER FINGERPRINTJS NOR ITS SUPPLIERS WILL HAVE ANY LIABILITY ARISING OUT OF OR RELATED TO THIS AGREEMENT FOR ANY LOSS OF USE, LOST DATA, LOST PROFITS, FAILURE OF SECURITY MECHANISMS, INTERRUPTION OF BUSINESS OR ANY INDIRECT, SPECIAL, INCIDENTAL, RELIANCE OR CONSEQUENTIAL DAMAGES OF ANY KIND, EVEN IF INFORMED OF THEIR POSSIBILITY IN ADVANCE.

### 9.ii Liability Cap

FINGERPRINTJS’S (AND ITS SUPPLIERS’) ENTIRE LIABILITY ARISING OUT OF OR RELATED TO THIS AGREEMENT WILL NOT EXCEED IN AGGREGATE THE AMOUNTS PAID OR PAYABLE BY CUSTOMER TO FINGERPRINTJS DURING THE 12 MONTHS IMMEDIATELY PRECEDING THE CLAIM (OR, IF FEWER THAN 12 MONTHS HAVE ELAPSED UNDER THE AGREEMENT, THE AVERAGE MONTHLY FEES PAID OR PAYABLE BY CUSTOMER TO FINGERPRINTJS UNDER THE AGREEMENT MULTIPLIED BY 12).

### 9.iii Nature of Claims and Failure of Essential Purpose

The waivers and limitations in this Section 9 apply regardless of the form of action, whether in contract, tort (including negligence), strict liability or otherwise and will survive and apply even if any limited remedy in this Agreement fails of its essential purpose.

## 10. Indemnification

### 10.i FingerprintJS Indemnity

FingerprintJS will defend Customer from and against any third-party claim to the extent alleging that the Service, when used as authorized by Customer, infringes a third-party’s U.S. patent, copyright or trademark, and will indemnify Customer against any damages or costs finally awarded by a court of competent jurisdiction against Customer (including reasonable attorneys’ fees) or agreed in settlement by FingerprintJS resulting from the claim. In response to an actual or potential infringement claim, if required by settlement or injunction or as FingerprintJS determines necessary to avoid material liability, FingerprintJS may at its option: (a) procure rights for Customer’s continued use of the Service, (b) replace or modify the alleged infringing portion of the Service to avoid infringement without reducing the Service’s overall functionality or (c) terminate Customer’s access to the infringing portion of the Service and refund to Customer any pre-paid, unused fees for the terminated portion of the applicable Subscription Term. FingerprintJS’s obligations in this Section 10 do not apply to the following “Customer-Controlled Matters” (i) to infringement resulting from Customer’s modification of the Agent or Mobile SDKs or use of the Service in combination with items not provided by FingerprintJS, (ii) to infringement resulting from use of a non-supported version of the Agent, Mobile SDKs or Service, (iii) to infringement resulting from unauthorized use of the Service, (iv) FingerprintJS’ compliance with any designs, requirements or specifications required or otherwise provided by Customer, or (v) if Customer settles or makes any admissions about a claim without FingerprintJS’s prior written consent. This Section 10 sets out Customer’s exclusive remedy and FingerprintJS’s entire liability regarding infringement of third-party intellectual property rights.

### 10.ii Customer Indemnity

At FingerprintJS’s request, Customer will defend FingerprintJS and its affiliates from and against any third-party claim based upon or arising from Visitor Data or FingerprintJS’s collection, storage, or processing thereof in compliance with this Agreement, or any Customer-Controlled Matter, and, regardless of whether FingerprintJS requests Customer to defend against such a claim, will indemnify FingerprintJS and its affiliates against any damages or costs awarded against FingerprintJS or its affiliates (including reasonable attorneys’ fees) or agreed in settlement by Customer resulting from the claim.

### 10.iii Indemnity Procedures

The party seeking defense and indemnification hereunder (the “**Indemnified Party**”) must provide the party from whom indemnification is sought (the “**Indemnifying Party**”): (a) prompt written notice of any claim for which indemnification is sought (provided that a failure to provide such notice will not relieve the Indemnifying Party of its obligations under this Section 10 except to the extent material prejudice results from such failure); (b) all reasonable cooperation, at the Indemnifying Party’s request and expense, in the defense and settlement of the claim; and (c) sole control of the defense and settlement of the claim (provided that (i) where Customer is the Indemnifying Party, such control only accrues to the extent FingerprintJS requests Customer’s defense of the claim and (ii) the Indemnifying Party may not agree to any settlement that places any obligation on the Indemnified Party without the Indemnified Party’s written consent, not to be unreasonably withheld, conditioned, or delayed).

## 11. Confidentiality

### 11.i Definition

“**Confidential Information**” means information disclosed under this Agreement that is designated by the disclosing party as proprietary or confidential or that should be reasonably understood to be proprietary or confidential due to its nature and the circumstances of its disclosure. FingerprintJS’s Confidential Information includes any technical or performance information about, and all nonpublic aspects of, the Service. Customer acknowledges that Fraud Identification Data maintained by FingerprintJS as part of the DRN does not constitute Customer’s Confidential Information.

### 11.ii Obligations

As receiving party, each party will (a) hold in confidence and not disclose Confidential Information to third parties except as permitted in this Agreement, and (b) only use Confidential Information to fulfill its obligations and exercise its rights in this Agreement. The receiving party may disclose Confidential Information to its employees, agents, contractors and other representatives having a legitimate need to know (including, for FingerprintJS, the subcontractors referenced in Section 13.ix), provided it remains responsible for their compliance with this Section 11 and they are bound to confidentiality obligations no less protective than this Section 11.

### 11.iii Exclusions

These confidentiality obligations do not apply to information that the receiving party can document (a) is or becomes public knowledge through no fault of the receiving party, (b) it rightfully knew or possessed prior to receipt under this Agreement, (c) it rightfully received from a third party without breach of confidentiality obligations or (d) it independently developed without using the disclosing party’s Confidential Information. The receiving party may disclose Confidential Information if required by Applicable Laws, subpoena or court order, provided (if permitted by Applicable Laws) it notifies the disclosing party in advance and cooperates in any effort to obtain confidential treatment.

### 11.iv Remedies

Unauthorized use or disclosure of Confidential Information may cause substantial harm for which damages alone are an insufficient remedy. Each party may seek appropriate equitable relief, in addition to other available remedies, for breach or threatened breach of this Section 11.

## 12. Publicity

FingerprintJS may include Customer and its trademarks in FingerprintJS’s customer lists and promotional materials but will cease this use at Customer’s written request.

## 13. General Terms

### 13.i Assignment

Neither party may assign this Agreement without the prior written consent of the other party, except that either party may assign this Agreement in connection with a merger, reorganization, acquisition or other transfer of all or substantially all its assets or voting securities. Any non-permitted assignment is void. This Agreement will bind and inure to the benefit of each party’s permitted successors and assigns.

### 13.ii Governing Law, Jurisdiction and Venue

This Agreement is governed by the laws of the State of Delaware and the United States without regard to conflicts of laws provisions and without regard to the United Nations Convention on the International Sale of Goods. The jurisdiction and venue for actions related to this Agreement will be the state and United States federal courts located in New Castle County, Delaware and both parties submit to the personal jurisdiction of those courts.

### 13.iii Notices

Except as set out in this Agreement, notices under this Agreement must be in writing to the addresses on the first page. Either party may update its address with notice to the other party. FingerprintJS may also send operational notices to Customer by email or through the Service.

### 13.iv Entire Agreement

This Agreement is the parties’ entire agreement regarding its subject matter and supersedes any prior or contemporaneous agreements regarding its subject matter. In this Agreement, headings are for convenience only and “including” and similar terms are to be construed without limitation. The terms in any Customer purchase order or business form will not amend or modify this Agreement and are expressly rejected by FingerprintJS; any of these Customer documents are for administrative purposes only and have no legal effect.

### 13.v Amendments

FingerprintJS may, in its sole discretion and from time to time, modify this Agreement by posting a revised version of this Agreement on its website. Customer is responsible for regularly reviewing this Agreement. CONTINUED USE OF THE SERVICE AFTER ANY SUCH CHANGES SHALL CONSTITUTE CUSTOMER’S AGREEMENT TO SUCH CHANGES. If Customer does not agree to the revised Agreement, then Customer may not use or continue to use the Service. Changes will become effective no sooner than seven (7) days after they are posted; provided that changes addressing new functions or changes made for legal reasons will be effective immediately.

### 13.vi Waivers and Severability

Waivers must be signed by the waiving party’s authorized representative and cannot be implied from conduct. If any provision of this Agreement is held invalid, illegal or unenforceable, it will be limited to the minimum extent necessary so the rest of this Agreement remains in effect.

### 13.vii Audit Rights

Upon FingerprintJS’s written request, Customer shall certify in a signed writing that Customer’s use of the Service is in full compliance with the terms of this Agreement.

### 13.viii Force Majeure

Neither party is liable for any delay or failure to perform any obligation under this Agreement (except for a failure to pay fees) due to events beyond its reasonable control, such as a strike, blockade, war, act of terrorism, riot, internet or utility failures, refusal of government license or natural disaster.

### 13.ix Subcontractors

FingerprintJS may use subcontractors and permit them to exercise FingerprintJS’s rights, but FingerprintJS remains responsible for their compliance with this Agreement and for its overall performance under this Agreement.

### 13.x Independent Contractors

The parties are independent contractors, not agents, partners or joint venturers.

### 13.xi Open Source

Certain aspects of the Service may contain or be provided with third-party components subject to the terms and conditions of “open source” software licenses (“**Third-Party Open Source**”). Third-Party Open Source may be identified in the Service (or a portion thereof), the Documentation, or FingerprintJS shall provide a list of the Third-Party Open Source to Customer upon Customer’s written request. To the extent required by the license that accompanies the Third-Party Open Source, the terms of such license will apply in lieu of the terms of this Agreement with respect to such Third-Party Open Source, including, without limitation, any provisions governing access to source code, modification, or reverse engineering. For clarity, Third-Party Open Source does not include any open source software created by FingerprintJS.

## 14. Definitions

“**Agent**” means the FingerprintJS JavaScript agent and any related code that the Customer installs on the Customer Website in connection with its use of the Service.

“**Applicable Laws**” means all relevant local, state, federal and international laws, regulations and conventions, including those related to data privacy and data transfer, international communications and export of technical data or Personal Information.

“**Browser**” means a particular software application designed to allow interactive access to the World Wide Web such as, by way of example and without limitation, Google Chrome, Firefox, Apple Safari, and Microsoft Edge.

“**CCPA**” means the California Consumer Privacy Act of 2018, Cal. Civ. Code § 1798.100 et seq., as amended, including its implementing regulations and the California Privacy Rights Act of 2020.

“**Credentials**” means user IDs, passwords, accounts, license keys or other Service access mechanisms provided by FingerprintJS.

“**Customer Website**” means the website of Customer on which the Agent is installed.  **“Dashboard”** means the hosted user interface made available by FingerprintJS at [https://dashboard.fingerprint.com](https://dashboard.fingerprint.com/) through which Customer can access certain information in connection with the Service.

“**Device Reputation Network**” or

“**DRN**” means the database maintained by FingerprintJS containing, in relation to each device to which Fraud Identification Data relates, aggregated Fraud Identification Data submitted by customers of FingerprintJS.

"**Documentation**" means the documentation made available to Customer by FingerprintJS for use with the Service at [https://dev.fingerprint.com/docs](https://dev.fingerprint.com/docs) (as modified from time to time).

"**European Data Privacy Legislation**" means, as applicable: (i) Regulation (EU) 2016/679; (ii) the "UK GDPR" as defined in The Data Protection, Privacy and Electronic Communications (Amendment Etc.) (EU Exit) Regulations 2019; and (iii) the Swiss Federal Act on Data Protection of 25 September 2020 and the Swiss Data Protection Ordinance of 31 August 2022, and any new or revised version of these laws that may enter into force for time to time.

“**Fraud Identification Data**” means information regarding devices associated with successful detections of fraud.

“**Mobile SDKs**” means the FingerprintJS object code or machine code libraries or software development kits in compiled, intermediate language, or source code form and any related code that the Customer adds to their mobile device applications in connection with its use of the Service.

“**Personal Information**” means information relating to identified or identifiable natural persons.

“**Privacy Policy**” means the FingerprintJS Privacy Policy, the current version of which is available at [https://dev.fingerprint.com/docs/privacy-policy](https://dev.fingerprint.com/docs/privacy-policy) (as modified from time to time).

“**Service**” means FingerprintJS’s proprietary fingerprinting-as-a-service offering, FingerprintJS. The Service includes the Dashboard, the Agent, the server-side software that analyzes Visitor Data, and, where the Customer elects to use such features of the Service using the functionalities on the Dashboard, either or both of the following: (i) additional model-driven fraud prediction and detection services; and (ii) access to the DRN.

“**Unique Browser Instance**” means a single instance of a single Browser on a single device initiated by a visitor to the Customer Website in an individual calendar month. \[1]

“**Usage Data**” means technical, log, usage and other data related to Customer’s (or its authorized users’) general use of the Service.

“**US Data Protection Laws**” means all applicable federal and state laws rules, regulations, and governmental requirements relating to data protection, the processing of Personal Information, privacy and/or data protection in force from time to time in the United States, including (without limitation) the CCPA.

“**User**” means any employee or contractor of Customer that Customer allows to use the Service on its behalf.

“**Visitor Data**” means the Customer Website session data collected in connection with the Service and any additional data provided or made available to FingerprintJS in relation to the Customer Website session, including any Fraud Identification Data provided by the Customer.

\[1] By way of example, a visitor who accesses the Customer Website via Google Chrome on a given device in a given calendar month counts as one (1) Unique Browser Instance. If the same visitor accesses the Customer Website via Firefox or a different device in the same calendar month, that counts as two (2) Unique Browser Instances (one (1) for the Google Chrome instance on the initial device and one (1) for the Firefox instance on the same device or the Google Chrome instance on a different device, respectively) in the applicable calendar month.

***

What’s Next

* [Start your free subscription now](https://dashboard.fingerprintjs.com/signup/)


# Troubleshoot 503 errors in Akamai Proxy Integration
Source: https://docs.fingerprint.com/docs/troubleshooting-akamai-supernet-error

Fix 503 errors between Akamai and Fingerprint endpoints by aligning Origin SSL verification settings in your Akamai property rules.

## Overview

If you are using an **Akamai Proxy Integration** with Fingerprint and requests to Fingerprint endpoints start returning `HTTP 503`, the most common cause is an Origin SSL verification mismatch in your Akamai property configuration.

This guide explains how to confirm the issue and update the relevant Akamai rule so Akamai can successfully connect to the Fingerprint origin.

## Symptoms

You may see:

* `503` responses from requests routed through Akamai to Fingerprint endpoints.
* The issue affects Fingerprint endpoints that are served through the Akamai property rule for Fingerprint.

## How to verify the error

If you see this 503 error on any Fingerprint endpoint, copy the Reference ID from the response body that Akamai returned. For example: `43.5cb6efc3.1773756189.10ff07a`.

1. Go to the Akamai Control Center.
2. Navigate to **Support** > **Edge Diagnostics**.
3. In the **Popular Tools** section, click **Translate Error String**.
4. Paste the Reference ID into the **Error reference codes** field.
5. Click **Submit**.
6. Wait for Akamai to fetch details.
7. Click the **View document** icon for the new item in the table below.
8. Check the **Reason for failure** field.

If the **Reason for failure** field shows `ERR_NON_SUPERNET_IP` or a similar SSL verification error, Akamai cannot connect to the Fingerprint origin.

## Resolution

In your Akamai Property Manager, navigate to **Fingerprint** > **Origin for Agent** > **Origin Behavior** > **Origin SSL Certificate Verification**.

<Frame>
  <img alt="Origin SSL Certificate Verification settings in Akamai Property Manager" />
</Frame>

1. Change the **Verification Settings** to `Choose Your Own`.
2. Keep **Use SNI TLS Extension** and **Match CA/SAN To** as is.
3. Change **Trust** to `Akamai-managed Certificate Authorities Sets`.
4. Select the **Akamai Certificate Store** and **Third Party Certificate Store** checkboxes.
5. Click **Save**.

If other endpoints are affected, repeat the steps for each affected endpoint. Fingerprint has 3 endpoints on Akamai:

* Agent download
* Browser Cache
* Identification

### Resolving Akamai validation errors

When saving your changes, you may encounter the following or similar validation error:

> Choosing Use Platform Settings for SSL Certificate Verification (in Origin Server) is not compatible with the custom settings you have chosen in Origin Server. Make sure the SSL Certificate Verification settings match in Origin Server.

This message means that the **Verification Settings** value in the Default Rule's Origin Behavior does not match the value used in your Fingerprint origin rules. Akamai requires the same **Verification Settings** value across all Origin Behavior rules in the property.

To fix the validation error:

1. In the Default Rule, open **Origin Behavior** and note the value of **Verification Settings**.
2. For each Fingerprint origin rule (Agent, Browser Cache, Identification), open **Origin Behavior**.
3. Set **Verification Settings** in each Fingerprint origin rule to the same value you noted in the Default Rule.
4. Save the property.

If the Default Rule's Origin Behavior uses **Verification Settings** set to `Third Party`, contact [Fingerprint support](https://fingerprint.com/support/).


# Visitor footprint timestamps
Source: https://docs.fingerprint.com/docs/useful-timestamps

Visitor footprint timestamps represent two significant events for a browser or device:

* The first time a browser or device appeared in your application.
* The most recent identification before the current event.

These timestamps when combined with Smart Signals (e.g. [IP Geolocation](/docs/smart-signals-reference#ip-geolocation), etc) can be valuable in detecting account takeover and other fraud.

## Availability

Visitor footprint timestamps are available for all plans at no additional cost. These fields are included in:

* [Server API v4 event responses](/reference/server-api)
* [Webhook v4 payloads](/docs/webhooks)
* [Sealed client results](/docs/sealed-client-results)

## Representation in API response

In API responses, visitor footprint timestamps are represented by the following JSON properties:

1. `identification.first_seen_at`
2. `identification.last_seen_at`

`last_seen_at` contains the previous identification timestamp. For a visitor's first identification, it equals `first_seen_at`.

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  {
    // ...
    // Timestamps are Unix millisecond integers
    "identification": {
      "first_seen_at": 1647430261101,
      "last_seen_at": 1648118914023
    },
    // ...
  }
  ```
</CodeGroup>

***

[Identifying users in hybrid app frameworks](/docs/identifying-users-in-hybrid-app-frameworks)

[Changelog (Android SDK)](/docs/changelog-android-sdk)


# Webhooks
Source: https://docs.fingerprint.com/docs/webhooks

Receive an HTTP request to your server with Fingerprint results for every identification event the moment it happens.

Webhooks are a form of server-to-server communication allowing Fingerprint to send data to ***your*** application’s API endpoint every time we identify a visitor.

You can think of it as the *reverse* [Server API](/reference/server-api) — instead of having to request identification data, we send the identification events to your server as they happen. You can use webhooks to:

* Store all of your identification events in your database indefinitely. Fingerprint stores your events only [for a limited time](/docs/billing#account-limits).
* Get Fingerprint results to your server securely and incorporate them into your fraud prevention logic or trigger other workflows for every identification event.

Webhooks are asynchronous and don't incur performance overhead when enabled. When multiple webhooks are enabled, events are delivered to each of them simultaneously.

## Implementing a webhook handler

When you call the JavaScript agent [get()](/reference/js-agent-get-function) method (or the mobile SDK equivalent), the identification request is processed by Fingerprint, and the device intelligence results are sent to your server endpoint.

To receive webhooks, you need to create an API endpoint in your server application that can receive POST HTTP requests from Fingerprint and return a successful response. For example:

<CodeGroup>
  ```javascript Next.js theme={"theme":"github-dark-dimmed"}
    import { Event } from '@fingerprint/node-sdk';

    export async function POST(request: Request) {
      const identificationEvent = (await request.json()) as Event;
      console.log(identificationEvent.identification.visitor_id);
      
      fingerprintEventsDatabase.add(identificationEvent);
      return Response.json({ message: 'Webhook received', status: 200 });
    }
  ```
</CodeGroup>

> Note: Our [Server SDKs](/reference/server-sdks) can provide you with type information about the webhook format.

Once you add the webhook to your system, you can test it using `cURL`. The payload below is a minimal example; a real webhook contains the full [`Event`](/reference/server-api-get-event) object with additional fields.

<CodeGroup>
  ```shell cURL theme={"theme":"github-dark-dimmed"}
    curl <your-webhook-url> \
      -X POST \
      -H "Content-Type: application/json" \
      -d '{ "event_id": "1708102555327.NLOjmg", "identification": { "visitor_id": "3HNey93AkBW6CRbxV6xP" } }'
  ```
</CodeGroup>

### Timeout and errors

* Fingerprint expects your server endpoint to respond with a [**`2xx`**](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_success) status code **within 3 seconds** of receiving the webhook payload.
* Otherwise, the webhook will be shown as *Failed* on the *Webhook events* page in the Dashboard.
* Headers and the response should be smaller than `4KB`, otherwise, they will be truncated.

### Retries

* Every request is retried **once** if it times out or returns a non-`2xx` response.
* The retry happens **5 minutes after** the first unsuccessful request.
* The retry request will have the **same request ID** as the first request, so it's possible to use it as an idempotency key.

If you have multiple webhooks configured under one application, each request will be treated independently. If your webhook endpoint fails, a retry will only be triggered for the endpoint that caused the issue.

## Registering your webhook URL

<Frame>
  <img />
</Frame>

You can register webhooks from your Fingerprint account as follows:

1. Navigate to **Dashboard** > **[Webhooks](https://dashboard.fingerprint.com/webhooks)**.
2. Click **Add webhook**.
3. Set *URL* to the HTTPS URL of your webhook endpoint. IP addresses or HTTP domains are not allowed.
4. If you select an [environment](/docs/multiple-environments), your webhook will be only report on events from a matching environment.
5. If you want to use [legacy payload format](#legacy-webhook-payload), check the *Use legacy payload* box.
6. Click **Create Webhook**.
7. You will see a success modal that says **Webhooks created**.
8. We recommend that you use [Webhook signatures](#webhook-signatures) to verify the incoming webhooks, make sure to download or copy the encryption key shown on the success modal. **The key is only shown once**.
9. Assuming your webhook handler is implemented and deployed, you can click **Send test event** to verify everything works as expected.

<img alt="" />

The created webhook is **Enabled** by default. You can manually deactivate your webhooks by clicking the **Edit** icon.

## Webhook payload format

Webhooks follow the same format as **Server API** responses, so you can reuse most of the code used with other Server API endpoints.

More details and webhook payload examples can be found on the [Webhooks reference page](/reference/posteventwebhook).

Our [Server SDKs](/reference/server-sdks) can also provide you with type information about the webhook format.

### Legacy webhook payload

<Warning>
  **Deprecation Notice**

  This legacy webhook payload (v3) was deprecated. If you still use this version, please follow our [migration guide](/reference/migrating-from-server-api-v3-to-v4#migrating-webhooks) to migrate from this deprecated version to the new one. The [one year deprecation period](/reference/api-deprecation-policy#one-year-migration-period) will start after the entire ecosystem supports Server API v4.
</Warning>

The webhook format is shared between all activated products. Fields can be specified as:

* optional (can be absent)
* nullable (can be null)
* empty (can be empty: `""` or `{}`)

For example `requestId` is not optional, it can't be null, it can't be empty.

<Info>
  **Smart Signals Fields**

  The set of features exposed in the root object is determined by the pricing tier of your workspace. `suspectScore`, `rootApps`, `tampering`, `proxy`, `vpn`, `tor`, `ipBlocklist`, `bot`, `ipInfo`, `emulator`, `clonedApp`, `factoryReset`, `jailbroken`, `frida`, `privacySettings`, `virtualMachine`, `remoteTools`, `velocity`, `developerTools` and `rawDeviceAttributes` fields are unavailable on the basic **Pro** tier.

  The webhook format exposes the same Smart Signals information as the Server API `/events` endpoint, even though the format is not **exactly the same**. The response payload is based on the originating platform (browser, iOS SDK, Android SDK) and feature availability. See our [Smart Signals cheat sheet](/docs/smart-signals-introduction) for a complete overview.
</Info>

<Accordion title="View legacy webhook payload" icon="info">
  <CodeGroup>
    ```json Pro theme={"theme":"github-dark-dimmed"}
    {
      // Unique request identifier
      // maxLength: 20
      "requestId": "1708102555327.NLOjmg",
      // customer-provided data, for example requestType and yourCustomId
      // both the tag and the information it contains are optional
      // and only for the customer's need.
      // empty, maxLength: 16KB
      "tag": {
          "requestType": "signup",
          "yourCustomId": 45321
      },
      // user-provided scalar identifier
      // optional,maxLength: 256
      "linkedId": "any-string",
      // persistent visitor identifier
      // helpful to detect anonymous or private mode users
      // maxLength: 20
      "visitorId": "3HNey93AkBW6CRbxV6xP",
      // tells whether a visitor was found in a visits history
      "visitorFound": true,
      // timestamp in milliseconds (since unix epoch)
      // 
      "timestamp": 1554910997788,
      // time in RFC3339 format
      // 
      "time": "2019-04-10T15:43:17.788Z",
      // if the page view was made in incognito or private mode
      "incognito": false,
      // URL where the API was called in the browser
      // empty maxLength: 4096
      "url": "https://banking.example.com/signup",
      // The URL of a client-side referrer
      // optional, maxLength: 4096
      "clientReferrer": "https://google.com?search=banking+services",
      // maxLength: 40
      "ip": "216.3.128.12",
      // indicates whether a request payload was replayed
      "replayed": false,
      // optional
      "environmentId": "ae_rrETjdWcfqI6AFsk",
      // empty
      // This field is deprecated and will not return a result for applications created after January 23rd, 2024
      // See /docs/smart-signals-overview#ip-geolocation for a replacement in our Smart Signals product
      "ipLocation": {
          // kilometers
          // optional
          "accuracyRadius": 1,
          // optional
          "city": {
              // empty, maxLength: 4096
              "name": "Bolingbrook"
          },
          // optional
          "continent": {
              // empty, maxLength: 2
              "code": "NA",
              // empty, maxLength: 40
              "name": "North America"
          },
          // optional
          "country": {
              // empty, maxLength: 2
              "code": "US",
              // empty, maxLength: 250
              "name": "United States"
          },
          // optional
          "latitude": 41.12933,
          // optional
          "longitude": -88.9954,
          // optional, maxLength: 40
          "postalCode": "60547",
          // optional
          "subdivisions": [
              {
                  // empty, maxLength: 250
                  "isoCode": "IL",
                  // empty, maxLength: 250
                  "name": "Illinois"
              }
          ],
          // optional, maxLength: 250
          "timezone": "America/Chicago"
      },
      "browserDetails": {
          // empty, maxLength: 250
          "browserName": "Chrome",
          // empty, maxLength: 250
          "browserFullVersion": "73.0.3683.86",
          // empty, maxLength: 250
          "browserMajorVersion": "73",
          // empty, maxLength: 250
          "os": "Mac OS X",
          // empty, maxLength: 250
          "osVersion": "10.14.3",
          // empty, maxLength: 250
          "device": "Other",
          // empty, maxLength: 4096
          "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86"
      },
      // optional
      "confidence": {
          // 0 - 1
          "score": 0.97
      },
      "firstSeenAt": {
          // nullable
          "global": "2022-03-16T11:26:45.362Z",
          // nullable
          "subscription": "2022-03-16T11:31:01.101Z"
      },
      "lastSeenAt": {
          // nullable
          "global": "2022-03-16T11:28:34.023Z",
          // nullable
          "subscription": null
      },
      // optional, maxLength: 4096
      "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86"
    }
    ```

    ```json Pro Plus theme={"theme":"github-dark-dimmed"}
    {
        // Unique request identifier
        // maxLength: 20
        "requestId": "1708102555327.NLOjmg",
        // customer-provided data, for example requestType and yourCustomId
        // both the tag and the information it contains are optional
        // and only for the customer's need.
        // empty, maxLength: 16KB
        "tag": {
            "requestType": "signup",
            "yourCustomId": 45321
        },
        // user-provided scalar identifier
        // optional,maxLength: 256
        "linkedId": "any-string",
        // persistent visitor identifier
        // helpful to detect anonymous or private mode users
        // maxLength: 20
        "visitorId": "3HNey93AkBW6CRbxV6xP",
        // tells whether a visitor was found in a visits history
        "visitorFound": true,
        // timestamp in milliseconds (since unix epoch)
        // 
        "timestamp": 1554910997788,
        // time in RFC3339 format
        // 
        "time": "2019-10-12T07:20:50.52Z",
        // if the page view was made in incognito or private mode
        "incognito": false,
        // URL where the API was called in the browser
        // empty maxLength: 4096
        "url": "https://banking.example.com/signup",
        // The URL of a client-side referrer
        // optional, maxLength: 4096
        "clientReferrer": "https://google.com?search=banking+services",
        // maxLength: 40
        "ip": "216.3.128.12",
        // indicates whether a request payload was replayed
        "replayed": false,
        // optional
        "environmentId": "ae_rrETjdWcfqI6AFsk",
        // empty
        // This field is deprecated and will not return a result for applications created after January 23rd, 2024
        // See /docs/smart-signals-overview#ip-geolocation for a replacement in our Smart Signals product
        "ipLocation": {
            // kilometers
            // optional
            "accuracyRadius": 1,
            // optional
            "city": {
                // empty, maxLength: 4096
                "name": "Bolingbrook"
            },
            // optional
            "continent": {
                // empty, maxLength: 2
                "code": "NA",
                // empty, maxLength: 40
                "name": "North America"
            },
            // optional
            "country": {
                // empty, maxLength: 2
                "code": "US",
                // empty, maxLength: 250
                "name": "United States"
            },
            // optional
            "latitude": 41.12933,
            // optional
            "longitude": -88.9954,
            // optional, maxLength: 40
            "postalCode": "60547",
            // optional
            "subdivisions": [
                {
                    // empty, maxLength: 250
                    "isoCode": "IL",
                    // empty, maxLength: 250
                    "name": "Illinois"
                }
            ],
            // optional, maxLength: 250
            "timezone": "America/Chicago"
        },
        "browserDetails": {
            // empty, maxLength: 250
            "browserName": "Chrome",
            // empty, maxLength: 250
            "browserFullVersion": "73.0.3683.86",
            // empty, maxLength: 250
            "browserMajorVersion": "73",
            // empty, maxLength: 250
            "os": "Mac OS X",
            // empty, maxLength: 250
            "osVersion": "10.14.3",
            // empty, maxLength: 250
            "device": "Other",
            // empty, maxLength: 4096
            "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86"
        },
        // optional
        "confidence": {
            // 0 - 1
            "score": 0.97
        },
        "firstSeenAt": {
            // nullable
            "global": "2022-03-16T11:26:45.362Z",
            // nullable
            "subscription": "2022-03-16T11:31:01.101Z"
        },
        "lastSeenAt": {
            // nullable
            "global": "2022-03-16T11:28:34.023Z",
            // nullable
            "subscription": null
        },
        // optional, maxLength: 4096
        "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86",
        // optional, empty
        "ipInfo": {
          "v4": {
            "address": "94.142.239.124",
            "geolocation": {
              "accuracyRadius": 20,
              "latitude": 50.05,
              "longitude": 14.4,
              "postalCode": "150 00",
              "timezone": "Europe/Prague",
              "city": {
                "name": "Prague"
              },
              "country": {
                "code": "CZ",
                "name": "Czechia"
              },
              "continent": {
                "code": "EU",
                "name": "Europe"
              },
              "subdivisions": [
                {
                  "isoCode": "10",
                  "name": "Hlavni mesto Praha"
                }
              ]
            }
          },
          // optional, empty
          "asn": {
            // optional, empty
            "asn": "7922",
            // optional, empty
            "name": "COMCAST-7922",
            // optional, empty
            "network": "73.136.0.0/13"
          },
          "dataCenter": {
            "result": true,
            // optional, empty
            "name": "DediPath"
          }
        },
        // optional, empty
        "bot": {
            // "good" | "bad" | "notDetected"
            // See more info at /docs/bot-detection-quick-start-guide
            "result": "notDetected"
        },
        // optional, empty
        "vpn": {
            "result": false,
            "methods": {
                "timezoneMismatch": false,
                "publicVPN": false,
                "auxiliaryMobile": false,
                "osMismatch": false,
                "relay": false
            }
        },
        // optional, empty
        "tampering": {
            "result": false,
            "anomalyScore": 0
        },
        // Indicates if anti-fingerprinting settings are enabled for Firefox and Brave browsers
        // optional, empty
        "privacySettings": {
            "result": false
        },
        // Indicates if the request was initiated from a virtual machine
        // optional, empty
        "virtualMachine": {
            "result": false
        },
        // optional, empty
        "remoteControl": {
            "result": false
        },
        // optional, empty
        "velocity": {
          "distinctIp": {
            "intervals": {
              "5m": 1,
              "1h": 1,
              "24h": 1
            }
          },
          "distinctLinkedId": {},
          "distinctCountry": {
            "intervals": {
              "5m": 1,
              "1h": 1,
              "24h": 1
            }
          },
          "events": {
            "intervals": {
              "5m": 1,
              "1h": 1,
              "24h": 1
            }
          }
        },
        // optional, empty
        "developerTools": {
            "result": false
        },
        // Returns Suspect Score computed from other Smart Signals
        // See /docs/suspect-score
        // optional, empty
        "suspectScore": {
            "result": 0
        }
    }
    ```

    ```json Enterprise theme={"theme":"github-dark-dimmed"}
    {
        // Unique request identifier
        // maxLength: 20
        "requestId": "1708102555327.NLOjmg",
        // customer-provided data, for example requestType and yourCustomId
        // both the tag and the information it contains are optional
        // and only for the customer's need.
        // empty, maxLength: 16KB
        "tag": {
            "requestType": "signup",
            "yourCustomId": 45321
        },
        // user-provided scalar identifier
        // optional,maxLength: 256
        "linkedId": "any-string",
        // persistent visitor identifier
        // helpful to detect anonymous or private mode users
        // maxLength: 20
        "visitorId": "3HNey93AkBW6CRbxV6xP",
        // tells whether a visitor was found in a visits history
        "visitorFound": true,
        // timestamp in milliseconds (since unix epoch)
        // 
        "timestamp": 1554910997788,
        // time in RFC3339 format
        // 
        "time": "2019-10-12T07:20:50.52Z",
        // if the page view was made in incognito or private mode
        "incognito": false,
        // URL where the API was called in the browser
        // empty maxLength: 4096
        "url": "https://banking.example.com/signup",
        // The URL of a client-side referrer
        // optional, maxLength: 4096
        "clientReferrer": "https://google.com?search=banking+services",
        // maxLength: 40
        "ip": "216.3.128.12",
        // indicates whether a request payload was replayed
        "replayed": false,
        // optional
        "environmentId": "ae_rrETjdWcfqI6AFsk",
        // empty
        // This field is deprecated and will not return a result for applications created after January 23rd, 2024
        // See /docs/smart-signals-overview#ip-geolocation for a replacement in our Smart Signals product
        "ipLocation": {
            // kilometers
            // optional
            "accuracyRadius": 1,
            // optional
            "city": {
                // empty, maxLength: 4096
                "name": "Bolingbrook"
            },
            // optional
            "continent": {
                // empty, maxLength: 2
                "code": "NA",
                // empty, maxLength: 40
                "name": "North America"
            },
            // optional
            "country": {
                // empty, maxLength: 2
                "code": "US",
                // empty, maxLength: 250
                "name": "United States"
            },
            // optional
            "latitude": 41.12933,
            // optional
            "longitude": -88.9954,
            // optional, maxLength: 40
            "postalCode": "60547",
            // optional
            "subdivisions": [
                {
                    // empty, maxLength: 250
                    "isoCode": "IL",
                    // empty, maxLength: 250
                    "name": "Illinois"
                }
            ],
            // optional, maxLength: 250
            "timezone": "America/Chicago"
        },
        "browserDetails": {
            // empty, maxLength: 250
            "browserName": "Chrome",
            // empty, maxLength: 250
            "browserFullVersion": "73.0.3683.86",
            // empty, maxLength: 250
            "browserMajorVersion": "73",
            // empty, maxLength: 250
            "os": "Mac OS X",
            // empty, maxLength: 250
            "osVersion": "10.14.3",
            // empty, maxLength: 250
            "device": "Other",
            // empty, maxLength: 4096
            "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86"
        },
        // optional
        "confidence": {
            // 0 - 1
            "score": 0.97
        },
        "firstSeenAt": {
            // nullable
            "global": "2022-03-16T11:26:45.362Z",
            // nullable
            "subscription": "2022-03-16T11:31:01.101Z"
        },
        "lastSeenAt": {
            // nullable
            "global": "2022-03-16T11:28:34.023Z",
            // nullable
            "subscription": null
        },
        // optional, maxLength: 4096
        "userAgent": "(Macintosh; Intel Mac OS X 10_14_3) Chrome/73.0.3683.86",
        // optional, empty
        "ipInfo": {
          "v4": {
            "address": "94.142.239.124",
            "geolocation": {
              "accuracyRadius": 20,
              "latitude": 50.05,
              "longitude": 14.4,
              "postalCode": "150 00",
              "timezone": "Europe/Prague",
              "city": {
                "name": "Prague"
              },
              "country": {
                "code": "CZ",
                "name": "Czechia"
              },
              "continent": {
                "code": "EU",
                "name": "Europe"
              },
              "subdivisions": [
                {
                  "isoCode": "10",
                  "name": "Hlavni mesto Praha"
                }
              ]
            },
            // optional, empty
            "asn": {
              // optional, empty
              "asn": "7922",
              // optional, empty
              "name": "COMCAST-7922",
              // optional, empty
              "network": "73.136.0.0/13"
            },
            "dataCenter": {
              "result": true,
              // optional, empty
              "name": "DediPath"
            }
          }
        },
        // optional, empty
        "bot": {
            // "good" | "bad" | "notDetected"
            // See more info at /docs/bot-detection-quick-start-guide
            "result": "notDetected"
        },
        // optional, empty
        "rootApps": {
            "result": false
        },
        // optional, empty
        "emulator": {
            "result": false
        },
        // optional, empty
        "ipBlocklist": {
            "result": false,
            "details": {
                "emailSpam": false,
                "attackSource": false
            }
        },
        // optional, empty
        "tor": {
            "result": false
        },
        // optional, empty
        "vpn": {
            "result": false,
            "methods": {
                "timezoneMismatch": false,
                "publicVPN": false,
                "auxiliaryMobile": false,
                "osMismatch": false,
                "relay": false
            }
        },
        // optional, empty
        "proxy": {
            "result": true,
            "confidence": "high",
            "details": {
                "proxyType": "residential",
                "lastSeenAt": "2025-08-12T13:00:00Z"
            }
        },
        // optional, empty
        "tampering": {
            "result": false,
            "anomalyScore": 0
        },
        // Indicates if the request was initiated from a cloned app. Only for Android SDK.
        // optional, empty
        "clonedApp": {
            "result": false
        },
        // Timestamp of when a factory reset is likely to have happened. Only for Mobile SDKs.
        // optional, empty
        "factoryReset": {
            "time": "1970-01-01T00:00:00Z",
            "timestamp": 0
        },
        // Indicates if the device has been jailbroken. Only for iOS SDK.
        // optional, empty
        "jailbroken": {
            "result": false
        },
        // Indicates if frida could have been used to tamper with the app. Only for Mobile SDKs. 
        // optional, empty
        "frida": {
            "result": false
        },
        // Indicates if anti-fingerprinting settings are enabled for Firefox and Brave browsers
        // optional, empty
        "privacySettings": {
            "result": false
        },
        // Indicates if the request was initiated from a virtual machine
        // optional, empty
        "virtualMachine": {
            "result": false
        },
        // optional, empty
        "remoteControl": {
            "result": false
        },
        // optional, empty
        "velocity": {
          "distinctIp": {
            "intervals": {
              "5m": 1,
              "1h": 1,
              "24h": 1
            }
          },
          "distinctLinkedId": {},
          "distinctCountry": {
            "intervals": {
              "5m": 1,
              "1h": 1,
              "24h": 1
            }
          },
          "events": {
            "intervals": {
              "5m": 1,
              "1h": 1,
              "24h": 1
            }
          }
        },
        // optional, empty
        "developerTools": {
            "result": false
        },
        // Raw attributes that were collected from the client's browser and that were used by 
        // Fingerprint to perform identification.
        // optional, empty
        "rawDeviceAttributes": {
            // Visit /reference/server-api-get-event to learn more about the
            // 'rawDeviceAttributes' object and all the possible values that it can contain.
        },
        // Returns Suspect Score computed from other Smart Signals
        // See /docs/suspect-score
        // optional, empty
        "suspectScore": {
            "result": 0
        }
    } 
    ```
  </CodeGroup>
</Accordion>

## Protecting your webhooks

You should make your Webhook URL impossible to guess and keep it secret, as this is the most basic form of protection. It doesn't secure the URL itself, but as long as the URL does not leak, no one can send fake identification events to it.

To ensure your data is encrypted, we require using HTTPS for all webhook communication.

### Webhook signatures

All webhook requests are signed with a signing key you obtain when you create a new webhook. To make sure the request came from Fingerprint, we strongly suggest validating the signature of each webhook request.

Each request contains a special `FPJS-Event-Signature` HTTP header.

* The header signature is computed from the HTTP body of the webhook along with a symmetric key — a **secret** generated during the webhook creation.
* The signature method used is **HMAC with SHA-256 hash function**.

Since the secret remains unique to a specific webhook, it's impossible to spoof invalid data without it.

#### `FPJS-Event-Signature` Header Structure

The value of the `FPJS-Event-Signature` header is a comma-separated list of `<signatureversion>=<hash>` where the `signatureversion` is the version of the signature and `hash` is the computed signature hash.

Currently, the only supported version is `v1` and the algorithm for `v1` is a **HMAC SHA-256 of the HTTP raw payload**, using the webhook's secret. The secret is generated for each webhook during its creation.

#### 1. Get the Key from the Dashboard

When you [add a webhook](#registering-your-webhook-url), we assign a *unique symmetric key* to it and display it once. **Save this signing key** for subsequent usage on your backend so that you can compute your HMAC and validate the webhook from the signature.

<img alt="" />

#### 2. Verify Signature

The HMAC signature we assign to the `FPJS-Event-Signature` header is calculated from the raw HTTP payload of the request. An example validation code might look like this:

<CodeGroup>
  ```typescript HMAC Validation theme={"theme":"github-dark-dimmed"}
    import * as crypto from "crypto";
    import { Buffer } from 'buffer';

    const checkSignature = (signature: string, data: Buffer, secret: string) => {
        return signature === crypto.createHmac('sha256', secret).update(data).digest('hex');
    }

    const checkHeader = (header: string, data: Buffer, secret: string) => {
        const signatures = header.split(',');
        for (const signature of signatures) {
            const [version, hash] = signature.split('=');
            if (version === 'v1') {
                if (checkSignature(hash, data, secret)) {
                    return true;
                }
            }
        }
        return false
    }

    //valid (allow)
    console.log(checkHeader('v1=b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4', Buffer.from('payload'), 'secret'))

    //invalid (reject)
    console.log(checkHeader('v0=89e14bbd118da7945e4547c1b9f32fff890dc141a7162df45c1ccb7546a80b58', Buffer.from('payload'), 'wrongsecret'))
    console.log(checkHeader('v1=79e14bbd118da7945e4547c1b9f32fff890dc141a7162df45c1ccb7546a80b58', Buffer.from('payload'), 'wrongsecret'))
  ```

  ```javascript Node SDK theme={"theme":"github-dark-dimmed"}
    import { isValidWebhookSignature } from '@fingerprint/node-sdk'

    /**
     * Webhook endpoint handler example
     * @param {Request} request
     */
    export async function POST(request) {
      try {
        const secret = process.env.WEBHOOK_SIGNATURE_SECRET
        const header = request.headers.get('fpjs-event-signature')
        const data = Buffer.from(await request.arrayBuffer())

        if (!secret) {
          return Response.json({ message: 'Secret is not set.' }, { status: 500 })
        }

        if (!header) {
          return Response.json({ message: 'fpjs-event-signature header not found.' }, { status: 400 })
        }

        if (!isValidWebhookSignature({ header, data, secret })) {
          return Response.json({ message: 'Webhook signature is invalid.' }, { status: 403 })
        }

        return Response.json({ message: 'Webhook received.' }, { status: 200 })
      } catch (error) {
        return Response.json({ error }, { status: 500 })
      }
    }
  ```
</CodeGroup>

### Key Rotation

Regular key rotations minimize the risk of your signing keys being leaked. To rotate the webhook key:

1. Create another Webhook with the same URL and a distinctive name.
2. Rotate the key on your backend.
3. Once you start ingesting the new signature, delete the old webhook completely to prevent duplicated information.

### Legacy webhook security

Legacy webhooks utilize **Basic HTTP authentication** to protect your webhook handlers.

<Warning>
  **Deprecation Notice**

  This Basic HTTP authentication option for webhooks (v3) was deprecated. If you still use this version, please follow our [migration guide](/reference/migrating-from-server-api-v3-to-v4#migrating-webhooks) to migrate from this deprecated version to the new one. The [one year deprecation period](/reference/api-deprecation-policy#one-year-migration-period) will start after the entire ecosystem supports Server API v4.
</Warning>

An easy way to protect your API is through [Basic HTTP Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). You can configure your web server to require a username and password to access a URL.

To enable Basic authentication for your webhook:

1. Navigate to **[Webhooks](https://dashboard.fingerprint.com/webhooks)**.
2. Find your webhook in the table and click the **Edit** icon.
3. Expand **Basic authentication**.
4. Fill in *User* and *Password*.
5. Click **Edit webhook**.

***

What’s Next

* [Start your free trial now](https://dashboard.fingerprintjs.com/signup/)


# Zero Trust Mode
Source: https://docs.fingerprint.com/docs/zero-trust-mode



When you identify browsers or devices with Fingerprint, you get back the visitor ID value.\
You can use this value in your business logic to find suspicious activity or for marketing analytics.\
By default, this value is sent back to your browser or device where you can read it and do something with it, e.g. send it to your server for storage and analysis.\
This works fine in most cases, but sometimes you want to **not** receive the visitor ID value from Fingerprint back to your devices. In security-critical applications, you want to hide that value and only read it on the server with your secret API key.\
Instead, you get back a random event ID value that you can use later to [read the actual visitor ID server-side](/reference/server-api-get-event).\
This mode of running the identification and not sending the visitor ID back to the client device is called **Zero Trust Mode**.

The Fingerprint API supports **Zero Trust Mode** to make it very difficult to send malicious identification requests that impersonate other visitors.\
Zero Trust Mode is implemented internally by *identification result hiding* and *strict origin-checking* features.

## Identification Result Hiding

Zero Trust Mode requires this feature to avoid sending the identification results to end-user browsers.

When enabled, the `visitor_id` field will not be sent to the end-user browser. The [event\_id](/reference/js-agent-get-function#event_id) field will still be returned to get the full results later using our [Server API](/reference/server-api-get-event).\
Importantly, when Zero Trust Mode is enabled, you will still get full results through the [webhook](/reference/posteventwebhook).

In addition to the `event_id`, the [JavaScript agent response](/reference/js-agent-get-function#get-response) will include a new field called `zero_trust` that will list all the fields that were hidden:

```json theme={"theme":"github-dark-dimmed"}
{
  "event_id": "...",
  "zero_trust": {
    "hidden_fields": ["visitor_id"],
    "comment": "The result was hidden because of the workspace configuration."
  }
}
```

Likewise, the iOS and Android client agents will not receive the visitor ID directly, only an event ID and other metadata.

## Strict Origin Checking

In all modern browsers, the [Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin) header is automatically included in all cross-origin requests.\
Websites cannot spoof this header. However, some signals collected by the [JavaScript agent](/reference/js-agent) can be spoofed.

When Zero Trust Mode is enabled, the *strict origin-checking* feature detects inconsistencies between the data collected by the JavaScript agent and the request headers that cannot be spoofed by the browser. These headers are the [Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin) and the [Referer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer). Identification requests with inconsistencies are rejected by the server. This ensures that the `url` and `client_referrer` values can’t be spoofed. That is important because `url` and `client_referrer` are exposed in our Server API and Webhook responses.

You can use Zero Trust Mode with the [request filtering](/docs/request-filtering) feature for additional security.

This mode is only available for the [Enterprise](https://fingerprintjs.com/pricing/) plan. It can be enabled on a per-workspace level.

<Note>
  If you would like to try this mode or learn more, please contact [our support team](https://fingerprint.com/support/).
</Note>


# API Deprecation Policy
Source: https://docs.fingerprint.com/reference/api-deprecation-policy

At Fingerprint, we regularly release updates to our JavaScript agent, APIs, and SDKs, to give you more features, increased security, and better performance. Sometimes, this means older versions of our APIs will no longer be supported.

## Quick overview

* All of your APIs and SDKs follow [semantic versioning](#semantic-versioning).
* Major releases of the JavaScript agent, Android SDK, iOS SDK, and all server-side APIs follow our [Deprecation and notice policy](#deprecation-and-notice-policy). You will have **1 year** from the major version release date to upgrade your implementation using the provided migration guides.
* Client and Backend SDKs are wrappers for the underlying JavaScript agent, mobile SDKs, or server-side APIs. They follow their own semantic versioning. The Deprecation and notice policy applies to them [only when the underlying SDK or API is deprecated](#exceptions-to-the-deprecation-and-notice-policy).

## Semantic versioning

All of our products are versioned using the [Semantic versioning](https://semver.org/) format `MAJOR.MINOR.PATCH`.

* We increment the `PATCH` version, for example, from `1.2.0` to `1.2.1`, when we make backward-compatible bug fixes. You can upgrade to a new patch version without making any changes to your application.
* We increment the `MINOR` version, for example, from `1.2.1` to `1.3.0`, when we add new features without any breaking changes. You can upgrade to a new minor version without making any changes to your application.

> Note: We can also use MINOR releases to update mobile SDK runtime requirements, for example, dropping support for old versions of iOS or Android.

* We increment the `MAJOR` version, for example, from `1.3.0` to `2.0.0`, when we make improvements that require you to make changes to your application. Upgrading to a new major version requires updating your application’s code, dependencies, or minimum required platform version to follow the new contract.

<Info>
  **Versioning REST APIs**

  REST and server-side APIs like [Server API](/reference/server-api), [Management API](/reference/management-api), [Device Reputation Network API](/reference/drn-api-overview), [Webhooks](/docs/webhooks) and [Sealed client results](/docs/sealed-client-results) only use the `MAJOR` version.

  * Non-breaking changes and additions to these APIs can happen at any time.
  * The API endpoint version is usually indicated by a **query parameter** (e.g. `/events?version=4`) or a **path parameter** (e.g. `/<version>/events`).
</Info>

## Deprecation and notice policy

When we release a new **MAJOR** version of the JavaScript agent, mobile SDKs, REST API endpoint, or another server-side API, the following policy applies since March 2025:

### One-year migration period

* You will have **one year** from the release date to switch to the new major version.
* We recommend upgrading as soon as possible to avoid any disruptions. We will always provide detailed migration guides and our customer success team will work with individual customers to ensure a smooth transition.
* During the migration period, we will continue to support both the deprecated and the new versions. The deprecated version will receive security fixes, but no new features or improvements.
* After the migration period ends, the previous (deprecated) major version will stop working.

### Deprecation notice

* We will inform you by email when a new major version is released. From this point, the previous major version is marked as **deprecated** and will stop working in one year.
* The relevant documentation will include a clear deprecation notice including the exact date of the API/SDK removal and end of support.
* If we detect you have not upgraded to the new version (for example, you are calling a deprecated API endpoint), we will send you reminder emails from [\[email protected\]](mailto:support@fingerprint.com) *once a month*. The email frequency will increase to *once a week* in the last month before the end of support.

<Info>
  Note: Some legacy APIs or SDKs might be deprecated without a direct replacement. In those cases, we will follow the same Deprecation and notice policy outlined above, including the one-year migration period.
</Info>

The Deprecation and notice policy covers the following:

* [JavaScript Agent](/reference/js-agent)
* [iOS SDK](/docs/ios-sdk)
* [Android SDK](/docs/android-sdk)
* [Webhook format](/docs/webhooks)
* [Sealed client results format](/docs/sealed-client-results)
* [Server API](/reference/server-api) (each endpoint can be versioned and deprecated individually) — see the [v3 to v4 migration guide](/reference/migrating-from-server-api-v3-to-v4)
* [Management API](/reference/management-api) (each endpoint can be versioned and deprecated individually)
* [Device Reputation Network API](/reference/drn-api-overview) (each endpoint can be versioned and deprecated individually)

## Exceptions to the Deprecation and notice policy

### Cloud proxy integrations

[Cloud proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers#cloud-proxy-integrations) have a large number of internal dependencies (JavaScript agent, Identification API, etc.) and external dependencies (cloud platforms and their products).

* In most cases, cloud proxy integrations follow the Deprecation and notice policy.
* However, in exceptional circumstances beyond our control (for example, a sudden change in a cloud platform dependency), we might be forced to end support for a deprecated version of a cloud proxy integration in **less than one year**.

### Wrapper SDKs

The Deprecation and notice policy **does not generally apply** to the following:

* [Frontend SDKs](/docs/frontend-libraries): React, Angular, Svelte, Vue, etc.
* Multi-platform SDKs: [React Native](/docs/fingerprintjs-pro-react-native) and [Flutter](/docs/flutter).
* [Server SDKs](/reference/server-sdks): Node, PHP, Go, Java, Python, and #C.

These SDKs (let’s call them *wrapper* SDKs) give you a smoother developer experience by providing utilities *on top* *of* the underlying JavaScript agent, mobile SDKs, and server-side APIs respectively.

* Wrapper SDKs follow their own semantic versioning.
* They can regularly release new major versions independently of the underlying SDK or API.
* The [Deprecation and notice policy](#deprecation-and-notice-policy) applies to them **only when the underlying SDK or API is deprecated**.

<Accordion title="Example A (Policy does not apply)">
  If we release a major version of the Node SDK that uses the same version of the underlying Server API as before, the deprecation policy **does not apply:**

  * For example, we improve the runtime function signature of some methods in the Node SDK. This breaking change (however small) requires releasing a new major version of the Node SDK. However, the SDK still uses the same version of the underlying Server API.
  * Therefore, the previous Node SDK major version is NOT \*\*deprecated, it stays available and continues to work.
  * There are no notice emails or deprecation notices.
  * The previous Node SDK major version continues to receive security fixes, but new features or improvements are only added to the latest major version.
  * The previous Node SDK major version can become deprecated later: 
    * As a result of the [Node SDK deprecation policy](https://github.com/fingerprintjs/node-sdk?tab=readme-ov-file#requirements) (e.g., if the underlying Node version is deprecated).
    * If the underlying Server API endpoint version is deprecated, as discussed below.
</Accordion>

<Accordion title="Example B (Policy applies)">
  If we release a major version of the Node SDK that uses a new major version of the underlying Server API, the deprecation policy **applies:**

  * All previous major versions of the Node SDK, using the now deprecated version of the Server API are now also deprecated according to the [Deprecation and notice policy](#deprecation-and-notice-policy).
</Accordion>


# Create API key
Source: https://docs.fingerprint.com/reference/apikeyscontroller_create

reference/management-api_2025-11-20.json POST /api-keys
Creates an API key for the workspace associated with the Management API key. Maximum number of API keys in defined by your plan limits. If you need additional API keys, contact our support team.



# Delete API key
Source: https://docs.fingerprint.com/reference/apikeyscontroller_deleteapikey

reference/management-api_2025-11-20.json DELETE /api-keys/{id}
Deletes an API key with the given ID. Make sure that the key you are deleting is not used in production environment. This action is not reversible.



# List API keys
Source: https://docs.fingerprint.com/reference/apikeyscontroller_findall

reference/management-api_2025-11-20.json GET /api-keys
Lists all API keys for the workspace associated with the Management API key.



# Get API key
Source: https://docs.fingerprint.com/reference/apikeyscontroller_findone

reference/management-api_2025-11-20.json GET /api-keys/{id}
Fetch an API key by ID.



# Update API key
Source: https://docs.fingerprint.com/reference/apikeyscontroller_update

reference/management-api_2025-11-20.json PATCH /api-keys/{id}
Updates a single API key. You can update the keys name, description, status, and rate limit. You cannot mutate the actual key itself.



# Automation Intelligence API
Source: https://docs.fingerprint.com/reference/automation-intelligence-api

The Automation Intelligence API (in public preview) gives you the tools to determine whether traffic is legitimate and should be accepted by your application.

<Warning>
  **Feature in Public Preview**

  This feature is currently in a Public Preview testing phase. All feedback is welcome! If you encounter any issues, please [contact](https://fingerprint.com/support/) our support team.
</Warning>

The API detects automation tools like AI Agents, AI Assistants, AI Browsers, and other bot and automation tools. Additionally, it provides IP intelligence like geolocation and data center detection.

Automation Intelligence is derived from HTTP request metadata that reaches your server. It does not require the use of a Javascript agent to collect browser context. The API is fast, with average response times of less than 30ms, making it a great fit for edge, pre-origin or middleware contexts. The API is platform-agnostic and can be used with different CDN providers, cloud platforms, or any server backend. If you are a Cloudflare user, consider using [Flow](/docs/flow-deployments#using-a-flow-worker-to-detect-bots-at-the-edge).

## Regions

The Automation Intelligence API is available in the **Global**, **EU** and **Asia (Mumbai)** regions:

| Region        | Base URL                 | Server Location    |
| ------------- | ------------------------ | ------------------ |
| Global        | `https://api.fpjs.io`    | Global             |
| EU            | `https://eu.api.fpjs.io` | Frankfurt, Germany |
| Asia (Mumbai) | `https://ap.api.fpjs.io` | Mumbai, India      |

Use the **Base URL** dropdown in the right column of the endpoint to select the correct base URL according to your workspace region.

## Authentication

Use an `Authorization: Bearer` header to authenticate to the API. All unauthenticated requests will return a `HTTP 403 Forbidden` response.

### Authorization: Bearer HTTP header

When making an API request, add the `Authorization: Bearer SECRET_API_KEY` HTTP header with your [secret API key](https://dashboard.fingerprint.com/api-keys?type=api).

## Forwarding request headers

Forward **all** of the original request's headers to the API. Whenever possible, preserve header order and capitalization to provide the best accuracy, however it’s not a strict requirement if your runtime does not maintain HTTP header order or canonicalizes header names.

<Warning>
  **Send authentication and session headers with empty values — do not drop them**

  Headers that contain authentication or session data must still be included, but with their value set to an empty string. This includes headers like `Authorization` and `Cookie`, but may contain more depending on your specific project, for instance `Proxy-Authenticate` or `X-Api-Key`. Omitting the headers entirely changes the shape of the request and can affect detection. Never forward the real secret values.
</Warning>

For example, given an incoming request with these headers:

```http Incoming request theme={"theme":"github-dark-dimmed"}
User-Agent: openai-mcp/1.0.0
Authorization: Bearer sk-live-abc123
Cookie: session=9f8a7b6c
Accept: application/json
```

forward them like this, blanking only the sensitive values while keeping every header present and in order:

```json Forwarded headers theme={"theme":"github-dark-dimmed"}
{
  "headers": [
    { "name": "User-Agent", "value": "openai-mcp/1.0.0" },
    { "name": "Authorization", "value": "" },
    { "name": "Cookie", "value": "" },
    { "name": "Accept", "value": "application/json" }
  ]
}
```

## Rate limiting

If you exceed the rate limit when making an API call, you'll get an HTTP 429 error:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "error": {
    "code": "too_many_requests",
    "message": "too many requests"
  }
}
```

Retry the request after a short interval. The response may include a `Retry-After` header indicating how long to wait.

## Trying it out

You can try calling the Automation Intelligence API directly from this reference:

1. You are going to need a Secret API Key. You can create one in your Fingerprint **Dashboard** > [**API Keys**](https://dashboard.fingerprint.com/api-keys).
2. Select the [Collect Intelligence](/reference/automation-intelligence-api-collect-intelligence) endpoint.
3. Click **Try it**.
4. Set **Authentication** to your secret API key.
5. Enter a **URL**, some example **Headers**, an HTTP **Method**, and an **IP** address.
6. Make sure the **Base URL** corresponds to your workspace region.
7. Click **Send**!

A real API response will appear in the **Response** section. Alternatively, you can view the prepared response examples there.

You can also point an API client like Postman to the [OpenAPI Schema](https://fingerprintjs.github.io/fingerprint-pro-server-api-openapi/schemas/fingerprint-server-api-v4-with-examples.yaml) directly.

## Viewing results in the Dashboard

Every request you send to the Automation Intelligence API appears in the Dashboard. Go to **Dashboard** > [**Bots & AI agents**](https://dashboard.fingerprint.com/bot-detection) to see your detections broken down by category, provider, and identity, and to inspect individual events.

The **Overview** page is available to all workspaces while the API is in Public Preview, so you can evaluate your results there before integrating. See [Bots and AI agents](/docs/dashboard-bots-ai-agents) for a guide to those pages.

## Related guides

<Columns>
  <Card title="Bots and AI agents" icon="chart-line" href="/docs/dashboard-bots-ai-agents">
    Analyze your bot traffic and investigate automation events in the Dashboard.
  </Card>

  <Card title="Bot Detection Overview" icon="bot" href="/docs/bot-detection/overview">
    How Fingerprint detects AI agents, browsers, and automation tools, and what each result means.
  </Card>

  <Card title="Bot Directory" icon="book-open" href="/docs/bot-detection/bot-directory">
    The bots and AI agents Fingerprint can detect, with their result types.
  </Card>

  <Card title="Web Bot Auth Implementation" icon="shield" href="/docs/bot-detection/web-bot-auth-implementation">
    How to implement Web Bot Auth signing so your agent is verified as a signed agent.
  </Card>
</Columns>


# Collect Intelligence
Source: https://docs.fingerprint.com/reference/automation-intelligence-api-collect-intelligence

post /edge
The Automation Intelligence API gives you the tools to determine whether traffic is legitimate and should be accepted by your application.

This feature is currently in a Public Preview testing phase. All feedback is welcome! If you encounter any issues, please [contact our support team](https://fingerprint.com/support/).

The API detects automation tools like AI Agents, AI Assistants, AI Browsers, and other bots. Additionally, it provides IP intelligence like geolocation, residential proxy, VPN and data center detection.

Automation Intelligence is derived from HTTP request metadata that reaches your server. It does not require the use of a JavaScript client-side agent or mobile SDKs to collect device context.

The API is fast, with average response times of less than 30ms, making it a great fit for edge, pre-origin or middleware contexts. The API is platform-agnostic and can be used with different CDN providers, cloud platforms, or any server backend.

Because this API doesn’t require the use of a client-side device collection agent, it doesn’t support device identification via `visitor_id` and a few Smart Signals derived from deep device telemetry.

### Event Retrieval

Events created by the Automation Intelligence API can be fetched via the [`/v4/events/{event_id}`](https://docs.fingerprint.com/reference/server-api-get-event) API using the `event_id` present in the API response.

Fetch all Automation Intelligence API events via the [`/v4/events?source=edge`](https://docs.fingerprint.com/reference/server-api-search-events#parameter-source) API.




# Authentication
Source: https://docs.fingerprint.com/reference/drn-api-authentication

DRN API requests are authorized by using the **secret API key**.

You can create one in your Fingerprint Dashboard by visiting **[API Keys](https://dashboard.fingerprint.com/api-keys)**.

<Warning>
  **Your secret API keys can be used query sensitive information about Android devices, be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, or with AI tools.**
</Warning>

Authentication is done with **Bearer authentication** (also called token authentication), and it involves providing the *secret* API key in a HTTP header. Use the `Authorization` header to authenticate requests to the DRN API.

```txt theme={"theme":"github-dark-dimmed"}
Authorization: Bearer SECRET_API_KEY
```

```bash cURL theme={"theme":"github-dark-dimmed"}
curl --request GET \
  --url 'https://drn-api.fpjs.io/drn/{visitor-id-from-your-app}?signals=regional_activity' \
  --header 'Authorization: Bearer SECRET_API_KEY' \
  --header 'X-API-Version: 2024-09-01'
```

Requests without a valid Authorization header will return `HTTP 401` error:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP Status: 401
{
  "error": {
    "code": "secret_key_not_found",
    "message": "secret key not found"
  }
}
```

This error will be returned if a correct Authorization header is not provided or when a secret API key is not found.


# Changelog
Source: https://docs.fingerprint.com/reference/drn-api-changelog

This changelog lists all additions and updates to the DRN API, in chronological order.

## 2024-09-01

* Initial release.
* Adds support for `regional_activity` signal.
* Adds support for `suspect_score` signal.
* Adds support for `timestamps` signal.


# Overview
Source: https://docs.fingerprint.com/reference/drn-api-drn-endpoint

`drn`endpoint

The DRN API supports a `drn` endpoint, that has two required parameters: `visitor_id` and `signals`.

### `GET https://drn-api.fpjs.io/drn/{visitor_id}?signals={signal}`

See the [Get by visitor ID reference](/reference/drn-api-get-by-visitor-id).


# Error handling and edge cases
Source: https://docs.fingerprint.com/reference/drn-api-error-handling

Handling errors when working with the DRN

There are certain errors that are possible when working with the DRN API:

## General error format

When the DRN API cannot process your request, it will return an error in the following format:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "error": {
    "code": "fixed_code",
    "message": "descriptive error message"
  }
}
```

The `code` is fixed inside a version, but the `message` can be updated to be more clear. Only the `code` value compatibility is guaranteed inside a specific [version](/reference/drn-api-versioning) !

For specific errors related to authentication, versioning, and rate limiting please refer to the specific reference pages.

## Unknown resource path

If a request is made to an unknown resource path (the part after the domain), an HTTP 404 error will be returned:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP Status 404
{
  "error": {
    "code": "http.not_found",
    "message": "not found"
}
```

The only valid resource path (the part that goes after fpjs.io) is `drn`:

**`GET https://drn-api.fpjs.io/drn/{visitor_id}`**

## Invalid `visitor_id` parameter.

If the `visitor_id` parameter that was provided is not known to the DRN API, e.g. if it's not generated by our Android SDK or is unknown entirely, an HTTP 404 error will be returned:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP Status 404
{
  "error": {
    "code": "http.not_found",
    "message": "visitor_id is not found"
  }
}
```

## Invalid `signals` parameter

A request without at least one `signals` parameter will return an HTTP 400 error:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP Status 400
{
  "error": {
    "code": "invalid_signals_parameter",
    "message": "Invalid `signals` query parameter"
}
```

## Empty response

If you requested the signals from a device with activity older than 30 days, you'll get an empty state response:

```json JSON theme={"theme":"github-dark-dimmed"}
"regionalActivity": [
  // will be at 30 days in the past in RFC3369 format, UTC timezone
  "startDate": "2024-09-01T23:12:59Z",
  "endDate": "2024-10-01T23:12:59Z",
  "countries": []
},
"suspectScore": {
  // will be at 30 days in the past in RFC3369 format, UTC timezone
  "startDate": "2024-09-01T23:12:59Z",
  "endDate": "2024-10-01T23:12:59Z",
  "minimum": {
    "value": 0,
    "signals": {}
  },
  "maximum": {
    "value": 0,
    "percentile": 0
    "signals": {}
  }
},
"timestamps": {
  "firstSeenAt": "2024-09-01T00:00:00Z" // format RFC3339, equal to current API version 
  "lastSeenAt": "2024-09-01T00:00:00Z" // format RFC3339, equal to current API version
  }
```


# Get device reputation signals
Source: https://docs.fingerprint.com/reference/drn-api-get-by-visitor-id

get /drn/{visitorId}
Returns device reputation information of a visitor.



# Overview
Source: https://docs.fingerprint.com/reference/drn-api-overview

How to get started with Fingerprint's global device intelligence network API (DRN API)

**Device Reputation Network API** allows making requests to Fingerprint's expansive device intelligence network and get global behavior and risk information about Android devices. To understand the underlying architecture of the DRN API, please refer to this [guide](/docs/drn-overview).

<Note>
  **DRN API only supports Fingerprint's [Android SDK](/docs/android-sdk)**
</Note>

DRN API is only for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. Since Fingerprint doesn't bill for server-side API calls, DRN API is free to use and does not count toward your monthly plan, however API key rate limits apply.

<Check>
  **DRN API requests do not count toward your monthly plan and are not billed.**
</Check>

# Getting started

DRN API is available globally:

| Region | Base URL                  |
| ------ | ------------------------- |
| Global | `https://drn-api.fpjs.io` |

You can use DRN API for all your workspaces, regardless of their [region](/docs/regions).

## Authentication

DRN API requests are authorized with a **Secret API key** that can be obtained in your Fingerprint Dashboard by visiting **[API Keys](https://dashboard.fingerprint.com/api-keys)**.

Set your API key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer SECRET_API_KEY
```

Read more in [Authentication](/reference/drn-api-authentication).

## Version

DRN API is versioned by date. This date represents when a backwards-incompatible change was made. The latest version is **`2024-09-01`**.

Set the version as in the `X-API-Version` header:

```
X-API-Version: 2024-09-01
```

Read more in [Versioning](/reference/drn-api-versioning).

## Signals

DRN API supports three signals in the current version: `regional_activity`, `suspect_score`, and `timestamps`. You can request all three signals in a single request.

## Making a request

The DRN API has two required parameters: `visitor_id` and `signals`:

### `GET https://drn-api.fpjs.io/drn/{visitor_id}?signals={signals}`

We'll be using the `regional_activity` signal for our request by specifying it in the `signals` URL query parameter. Before you can make the request, you need to get a device `visitor_id`. You can [start a trial](http://dashboard.fingerprint.com/signup), run a sample project, and use your device `visitor_id` as a parameter. Once you have the `visitor_id` and the secret API key, build a curl request. The `visitor_id` goes in the path, `signals=regional_activity` as a query parameter, both `Authorization`, and `X-API-Version` as HTTP headers:

<CodeGroup>
  ```bash curl theme={"theme":"github-dark-dimmed"}
  curl --request GET \
    --url 'https://drn-api.fpjs.io/drn/{visitor-id-from-your-app}?signals=regional_activity' \
    --header 'Authorization: Bearer {secret-api-key}' \
    --header 'X-API-Version: 2024-09-01'
  ```

  ```bash wget theme={"theme":"github-dark-dimmed"}
  wget --method GET \
    --header 'X-API-Version: 2024-09-01' \
    --header 'Authorization: Bearer {secret-api-key}' \
    --output-document \
    - 'https://drn-api.fpjs.io/drn/{visitor_id}?signals=regional_activity'
  ```
</CodeGroup>

You will get a response with a list of countries where this device was active in the last 30 days:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "data": {
    "regionalActivity": {
      "startDate": "2024-08-06T23:00:13Z",
      "endDate": "2024-09-05T23:00:13Z",
      "countries": [
        {
          // this device was active in France via VPN and we detected it by IP
          "code": "FR",
          "detectors": [
            {
              "type": "ip",
              "activityPercentage": 0.20
            }
          ]
        },
        {
          // this device was also active in Russia and we detect it using our 
          // real location detection smart signal
          // /docs/smart-signals-overview#vpn-detection-for-mobile-devices
          "code": "RU",
          "detectors": [
            {
              "type": "origin",
              "activityPercentage": 1.0
            },
              {
              "type": "ip",
              "activityPercentage": 0.8
            }
          ]
        }
      ]
    }
  }
}
```

Even though you just identified this device in your app, you can get a **global** location history for any device in the Fingerprint network, including the **real location** even with VPN enabled!

### Rate limiting

DRN API is rate limited. **The** limit is enforced for every **Secret API key**, and the default rate limit per API key is **5 req/sec**. More details available in the [Rate limiting reference page](/reference/drn-api-rate-limiting). If you need a higher limit, reach out to [drn@fingerprint.com](mailto:drn@fingerprint.com).

### API client SDKs

SDKs for specific languages are coming soon! Email [drn@fingerprint.com](mailto:drn@fingerprint.com) if you want to request an SDK or integration for your stack.


# Rate limiting
Source: https://docs.fingerprint.com/reference/drn-api-rate-limiting

DRN API is rate limited. The limit is enforced for every , and the default rate limit per API key is **5 req/sec**.

If you exceed the rate limit when making a DRN API call, you'll get an HTTP 429 error:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP 429
{
  "error": {
    "code": "http.too_many_requests",
    "message": "Too many requests"
  }
}
```

You can use the `Retry-After` response header to get the number of seconds after which you can retry your request.

If you need a higher limit, reach out to [drn@fingerprint.com](mailto:drn@fingerprint.com).


# Versioning
Source: https://docs.fingerprint.com/reference/drn-api-versioning

DRN API is *versioned*. When backwards-incompatible changes are made to the API, we release a new, dated version. The current version is `2024-09-01`.

Specifying API version is required to prevent breaking changes in the new versions breaking your integration. Any breaking changes will always be released as a new API version.

When making an API request, add `X-API-Version` HTTP header with the API version you’re using.

```text theme={"theme":"github-dark-dimmed"}
X-API-Version: 2024-09-01
```

```bash cURL theme={"theme":"github-dark-dimmed"}
curl -XGET -H 'Authorization: Bearer SECRET_API_KEY' -H 'X-API-Version: 2024-09-01'\
  'https://drn-api.fpjs.io/drn/...'
```

Requests without a valid API version will return `HTTP 400` error.

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "error": {
    "code": "version_not_found",
    "message": "version is not found"
  }
}
```

Before upgrading to a new API version, you should read the **[Changelog](/reference/drn-api-changelog)** to understand what breaking changes are included and to learn more about how to upgrade to the new API version.


# Create an environment
Source: https://docs.fingerprint.com/reference/environmentcontroller_create

reference/management-api_2025-11-20.json POST /environments
Creates a new environment for the workspace associated with the Management API key. Maximum number of environments in defined by your plan limits. If you need additional environments, contact our support team.



# Delete an environment
Source: https://docs.fingerprint.com/reference/environmentcontroller_delete

reference/management-api_2025-11-20.json DELETE /environments/{id}
Deletes an environment with the given environment ID. You can only delete environments that don't have any active API keys associated with it.



# List environments
Source: https://docs.fingerprint.com/reference/environmentcontroller_findallv2

reference/management-api_2025-11-20.json GET /environments
Lists all environments for the workspace associated with the Management API key.



# Update an environment
Source: https://docs.fingerprint.com/reference/environmentcontroller_update

reference/management-api_2025-11-20.json POST /environments/{id}
Updates an environment with the given environment ID. You can update the name, description, and limit settings.



# Bulk create/update filtering rules
Source: https://docs.fingerprint.com/reference/filteringrulesv2controller_bulk

reference/management-api_2025-11-20.json POST /filtering-rules/bulk
Creates or updates multiple filtering rules at once. In "merge" mode (default), rules with IDs are updated and rules without IDs are created. In "overwrite" mode, all existing rules for the given environment are deleted and replaced with the provided rules.



# Create a filtering rule
Source: https://docs.fingerprint.com/reference/filteringrulesv2controller_create

reference/management-api_2025-11-20.json POST /filtering-rules
Creates a new filtering rule. The rule will be evaluated in order based on the placement parameter. If no placement is specified, the rule is added to the end.



# List filtering rules
Source: https://docs.fingerprint.com/reference/filteringrulesv2controller_findall

reference/management-api_2025-11-20.json GET /filtering-rules
Lists all filtering rules for the workspace associated with the Management API key. Supports filtering by environment, status, and name.



# Retrieve filtering rule
Source: https://docs.fingerprint.com/reference/filteringrulesv2controller_findone

reference/management-api_2025-11-20.json GET /filtering-rules/{id}
Retrieves a single filtering rule by ID.



# Update filtering rule
Source: https://docs.fingerprint.com/reference/filteringrulesv2controller_update

reference/management-api_2025-11-20.json POST /filtering-rules/{id}
Updates an existing filtering rule. Only provided fields will be updated.



# Flow worker request headers
Source: https://docs.fingerprint.com/reference/flow-worker-headers



When [Edge Bot Detection](/docs/flow-deployments#using-a-flow-worker-to-detect-bots-at-the-edge) is enabled on a [Cloudflare Flow worker](/docs/flow-deployments), the worker enriches requests it forwards to your origin with HTTP request headers derived from the Automation Intelligence API response.

This page maps each request header to the corresponding property on the [`Get an event by event ID`](/reference/server-api-get-event) response, so you can cross-reference field semantics, value types, and constraints between the two surfaces.

<Info>
  Header values are encoded as [RFC 9651 structured fields](https://www.rfc-editor.org/info/rfc9651/): strings are quoted (`"AWS"`), booleans are sent as `?1` only for true values (false values are omitted entirely), and Unix timestamps use the `@` prefix (`@1733943233`).

  A single request is either IPv4 or IPv6, so only the matching set of `fp-ip-info-v4-*` or `fp-ip-info-v6-*` headers is set. Headers with no detected value are omitted entirely.
</Info>

## IP intelligence headers

### Address

| Request Header          | Event property                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `fp-ip-info-v4-address` | [`ip_info.v4.address`](/reference/server-api-get-event#response-ip-info-v4-address) |
| `fp-ip-info-v6-address` | [`ip_info.v6.address`](/reference/server-api-get-event#response-ip-info-v6-address) |

### Geolocation, ASN, and datacenter

The following headers are provided for both IPv4 and IPv6 (replace `v4` with `v6` for IPv6 requests).

| Request Header                              | Event property                                                                                                              |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `fp-ip-info-v4-geolocation-accuracy-radius` | [`ip_info.v4.geolocation.accuracy_radius`](/reference/server-api-get-event#response-ip-info-v4-geolocation-accuracy-radius) |
| `fp-ip-info-v4-geolocation-latitude`        | [`ip_info.v4.geolocation.latitude`](/reference/server-api-get-event#response-ip-info-v4-geolocation-latitude)               |
| `fp-ip-info-v4-geolocation-longitude`       | [`ip_info.v4.geolocation.longitude`](/reference/server-api-get-event#response-ip-info-v4-geolocation-longitude)             |
| `fp-ip-info-v4-geolocation-postal-code`     | [`ip_info.v4.geolocation.postal_code`](/reference/server-api-get-event#response-ip-info-v4-geolocation-postal-code)         |
| `fp-ip-info-v4-geolocation-timezone`        | [`ip_info.v4.geolocation.timezone`](/reference/server-api-get-event#response-ip-info-v4-geolocation-timezone)               |
| `fp-ip-info-v4-geolocation-city-name`       | [`ip_info.v4.geolocation.city_name`](/reference/server-api-get-event#response-ip-info-v4-geolocation-city-name)             |
| `fp-ip-info-v4-geolocation-country-code`    | [`ip_info.v4.geolocation.country_code`](/reference/server-api-get-event#response-ip-info-v4-geolocation-country-code)       |
| `fp-ip-info-v4-geolocation-continent-code`  | [`ip_info.v4.geolocation.continent_code`](/reference/server-api-get-event#response-ip-info-v4-geolocation-continent-code)   |
| `fp-ip-info-v4-asn-name`                    | [`ip_info.v4.asn.name`](/reference/server-api-get-event#response-ip-info-v4-asn-name)                                       |
| `fp-ip-info-v4-asn-network`                 | [`ip_info.v4.asn.network`](/reference/server-api-get-event#response-ip-info-v4-asn-network)                                 |
| `fp-ip-info-v4-asn-type`                    | [`ip_info.v4.asn.type`](/reference/server-api-get-event#response-ip-info-v4-asn-type)                                       |
| `fp-ip-info-v4-datacenter-name`             | [`ip_info.v4.datacenter_name`](/reference/server-api-get-event#response-ip-info-v4-datacenter-name)                         |

### Proxy

Proxy headers are only set when a proxy is detected. When no proxy is detected, none of the `fp-proxy-*` headers are sent.

| Request Header                  | Event property                                                                                      |
| ------------------------------- | --------------------------------------------------------------------------------------------------- |
| `fp-proxy`                      | [`proxy`](/reference/server-api-get-event#response-proxy)                                           |
| `fp-proxy-confidence`           | [`proxy_confidence`](/reference/server-api-get-event#response-proxy-confidence)                     |
| `fp-proxy-details-proxy-type`   | [`proxy_details.proxy_type`](/reference/server-api-get-event#response-proxy-details-proxy-type)     |
| `fp-proxy-details-last-seen-at` | [`proxy_details.last_seen_at`](/reference/server-api-get-event#response-proxy-details-last-seen-at) |
| `fp-proxy-details-provider`     | [`proxy_details.provider`](/reference/server-api-get-event#response-proxy-details-provider)         |

### VPN

VPN headers are only set when a VPN is detected. Individual `fp-vpn-methods-*` headers are only set for detection methods that triggered; methods that did not trigger are omitted.

| Request Header                     | Event property                                                                                            |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `fp-vpn`                           | [`vpn`](/reference/server-api-get-event#response-vpn)                                                     |
| `fp-vpn-confidence`                | [`vpn_confidence`](/reference/server-api-get-event#response-vpn-confidence)                               |
| `fp-vpn-methods-timezone-mismatch` | [`vpn_methods.timezone_mismatch`](/reference/server-api-get-event#response-vpn-methods-timezone-mismatch) |
| `fp-vpn-methods-public-vpn`        | [`vpn_methods.public_vpn`](/reference/server-api-get-event#response-vpn-methods-public-vpn)               |
| `fp-vpn-methods-auxiliary-mobile`  | [`vpn_methods.auxiliary_mobile`](/reference/server-api-get-event#response-vpn-methods-auxiliary-mobile)   |
| `fp-vpn-methods-os-mismatch`       | [`vpn_methods.os_mismatch`](/reference/server-api-get-event#response-vpn-methods-os-mismatch)             |
| `fp-vpn-methods-relay`             | [`vpn_methods.relay`](/reference/server-api-get-event#response-vpn-methods-relay)                         |

### IP blocklist

| Request Header             | Event property                                                                            |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| `fp-ip-blocklist-tor-node` | [`ip_blocklist.tor_node`](/reference/server-api-get-event#response-ip-blocklist-tor-node) |

## Bot intelligence headers

Bot intelligence headers are only set for requests attributed to a bot or AI automation. Otherwise, none of the `fp-bot-info-*` headers are sent.

| Request Header         | Event property                                                                    |
| ---------------------- | --------------------------------------------------------------------------------- |
| `fp-bot-info-category` | [`bot_info.category`](/reference/server-api-get-event#response-bot-info-category) |
| `fp-bot-info-provider` | [`bot_info.provider`](/reference/server-api-get-event#response-bot-info-provider) |
| `fp-bot-info-name`     | [`bot_info.name`](/reference/server-api-get-event#response-bot-info-name)         |
| `fp-bot-info-identity` | [`bot_info.identity`](/reference/server-api-get-event#response-bot-info-identity) |


# Overview
Source: https://docs.fingerprint.com/reference/js-agent

The Fingerprint JavaScript agent is a high-performance JavaScript function that collects multiple device and browser signals and sends them to the Fingerprint API for visitor identification and device intelligence analysis.

This section contains the complete API Reference for the JavaScript agent, specifically:

* [The start() function](/reference/js-agent-start-function) options that are used to download and initialize the JavaScript agent.
* [The get() function](/reference/js-agent-get-function) options for sending identification requests and its response schema.

## JavaScript agent guides

If you are just getting started with Fingerprint, we recommend reading the following guides first:

* [Install the JavaScript agent](/docs/install-the-javascript-agent)
* [Identify visitors](/docs/identify-visitors)

## Framework-specific SDKs

If your web application is built using **React**, **Vue**, **Svelte**, or **Angular**, we recommend using a higher-level library wrapping the JavaScript agent made for your specific framework. See [Using a framework-specific SDK for more details](/docs/install-the-javascript-agent#using-a-framework-specific-sdk).

## Changelog

To keep track of changes and updates to the JavaScript agent, see the [JavaScript Agent Changelog](/changelog).

## Browser support

The JavaScript agent supports all currently popular browsers. For more details, see [Browser and device support](/docs/browser-and-device-support).

## TypeScript support

If you install the JavaScript agent using the [NPM loader package](/docs/install-the-javascript-agent#installing-the-agent-loader-using-npm) or one of our [client libraries](/docs/install-the-javascript-agent#using-a-framework-specific-sdk), it includes TypeScript types.

The agent officially supports TypeScript version **5.1** but may work with newer and older versions of TypeScript. Please see the [Error handling reference](/reference/js-agent-error-handling) if you encounter any problems.

## Mobile device client agents

The JavaScript agent is used to identify and provide intelligence about **browsers**. For mobile identification and device intelligence, please see:

* [Identify Android devices](/docs/native-android-integration)
* [Identify iOS devices](/docs/ios)


# Error handling
Source: https://docs.fingerprint.com/reference/js-agent-error-handling

Error handling overview and best practices for JavaScript agent

JavaScript agent exposes errors in a predictable and actionable way. This guide explains how it surfaces errors, how you can identify them, and how you should handle them in your application.

## Overview

Both the `start()` and `get()` methods can throw errors, we recommend wrapping them in a `try/catch` block to prevent any unwanted errors popping up in the browser developer console.

All JavaScript agent errors are represented by the `FingerprintError` class. These errors include both a human-readable message and an error `code`.

```ts theme={"theme":"github-dark-dimmed"}
class FingerprintError extends Error {
  name: "FingerprintError"
  code: string
  event_id: string | null
}
```

We use error codes to ensure your application logic does not depend on error message text, which may change over time.

## Handling Errors

We provide the `isFingerprintError()` helper so you can reliably distinguish JavaScript agent errors from generic JavaScript errors.

```jsx theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from "@fingerprint/agent"

try {
  const fp = Fingerprint.start({ apiKey })
} catch (error) {
  if (Fingerprint.isFingerprintError(error)) {
    console.error(error.code, error.message)
  }
}
```

You should always use this helper instead of checking error names or messages directly.

***

## Error Codes

### Configuration Errors

Configuration errors occur during initialization when required options are missing or invalid.
These errors are **not retryable** and must be fixed in your configuration.

| Code                      | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `api_key_missing`         | You did not provide the `apiKey` option        |
| `api_key_invalid`         | The `apiKey` option is not a string            |
| `endpoints_misconfigured` | The `endpoints` option is invalid              |
| `invalid_endpoint`        | An endpoint is not a valid URL                 |
| `cache_misconfigured`     | The `cache` option is misconfigured            |
| `wrong_worker_option`     | The `worker` option is not a `Worker` instance |

***

### Script and Environment Errors

These errors occur when we are unable to load or execute the agent script in the current environment.

| Code               | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `script_load_fail` | Failed to load the agent script                        |
| `csp_block`        | Script blocked by Content Security Policy (CSP)        |
| `sandboxed_iframe` | Running in an unsupported sandboxed iframe environment |

<Info>
  See our [CSP documentation](/docs/js-agent-csp) to correctly configure the exceptions needed for our JavaScript agent and WebWorker.
</Info>

### Network and Runtime Errors

These errors may occur during initialization or data collection and are often temporary.

| Code                  | Description                             |
| --------------------- | --------------------------------------- |
| `client_timeout`      | The operation timed out                 |
| `network_connection`  | A network request failed                |
| `network_abort`       | A request was aborted                   |
| `bad_response_format` | We could not parse the backend response |

We automatically retry these errors where appropriate.

## Timeouts

Two types of timeouts are possible: a server timeout and a client timeout.
​

### Server timeout

The server timeout is fixed at 10 seconds of server-side processing time. If server-side processing exceeds 10 seconds for any reason, the promise will be rejected.
​

### Client timeout

Client timeout controls the total time (both client-side and server-side) that any analysis event is allowed to run. By default, it’s 10 seconds. Note that even if the client-side timeout is exceeded, the server-side request can still be running, and its results will be sent to you via a webhook if enabled.

## Rate limiting

Every workspace API key has a rate limit. It means you cannot make more requests per second than your rate limit allows. See [Account limits](/docs/billing#account-limits) for more details.
​

## Retrying after an error

The JavaScript agent retries automatically in case of failure. If you want the agent to make more attempts, increase the timeout. If you want to retry with another endpoint, set an array of `endpoints` in the JavaScript agent option.

We don’t recommend implementing your own retry mechanism around the JavaScript agent because it can lead to excessive consumption of paid API calls.

## Handling Errors from `start()`

The `start()` method may fail due to configuration issues, script loading failures, or environment restrictions.

```js theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from "@fingerprint/agent"

try {
  const fp = Fingerprint.start({ apiKey })
} catch (error) {
  if (Fingerprint.isFingerprintError(error)) {
    switch (error.code) {
      case "csp_block":
        // Update your CSP to allow the agent script
        break
      case "api_key_missing":
        // Fix your configuration
        break
      default:
        // Log the error and fail gracefully
    }
  }
}
```

## Ad blockers

Ad blockers can interfere with identification requests or prevent the JavaScript agent from loading. This typically results in a `net::ERR_BLOCKED_BY_CLIENT` error in the browser console, along with messages such as "Failed to load the JavaScript script of the agent" or "Network connection error".

To avoid these issues, we provide several proxy integration solutions. Refer to [Protecting the JavaScript agent from ad blockers](/docs/protecting-the-javascript-agent-from-adblockers) for detailed guidance on available options.
​

## Best Practices

We recommend that you:

* Always wrap `start()` and `get()` in a `try/catch` block
* Use `isFingerprintError()` to detect and handle JavaScript agent errors
* Treat configuration errors as non-retryable


# get function
Source: https://docs.fingerprint.com/reference/js-agent-get-function

This page contains the API reference for the JavaScript agent `get()` function or its equivalent in your frontend library. The function is not exported directly from the [@fingerprint/agent](https://www.npmjs.com/package/@fingerprint/agent) NPM package. Instead, it is a method on the agent instance returned by the [start()](/reference/js-agent-start-function) function.

The `get()` function sends an identification request to Fingerprint and returns the browser's visitor ID.

* Call `get()` only when you actually need the visitor ID.
* Wait at least 1 second between [`start()`](/reference/js-agent-start-function) and `get()` so the agent has time to collect the signals required for Identification and Smart Signals.

If you are just getting started with Fingerprint, we recommend reading the following guides first:

* [Install the JavaScript agent](/docs/install-the-javascript-agent)
* [Identify visitors](/docs/identify-visitors)

## `get()` options

### `linkedId`

> **Required**: no **Default**: `undefined` **Type**: `string` **Constraint**: the number of characters must not exceed 256

`linkedId` is a way of linking the current analysis event with a custom identifier. This will allow you to filter visit information when using the [Server API](/reference/server-api).

<CodeGroup>
  ```javascript Add a custom identifier to an analysis event theme={"theme":"github-dark-dimmed"}
  // Making an API call
  var orderId = 3936532456
  fp.get({ linkedId: orderId })
  // linkedId will be saved with this event and will be available to be queried later.
  ```
</CodeGroup>

If the information stored in `linkedId` is not available on the client when the event happens, it is possible to set it through our [Update Event Server API](/reference/server-api-update-event).

To learn more about `tags` and `linkedId` use cases, see [Linking and tagging information](/docs/tagging-information).

### `tags`

> **Required**: no **Default**: `undefined` **Type**: any simple value or an object (not arrays) **Constraint**: the size must not exceed 16KB

`tags` is a customer-provided value or an object that is saved with the identification event and returned back to you in a webhook message or Server API response. You can use `tags` to associate the visit event with other information you have about the visitor.

You can use any simple value (string, number, boolean) or an object. An object is saved as provided. A simple value (for example `123`) is returned wrapped in an object like this: `{ "tags": 123 }`.

Examples of using the `tags` option:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  fp.get({ tags: 123 });
  fp.get({ tags: "signup" });
  fp.get({ tags: { id: "456", location: { city: "Atlanta", country: "US" } } });
  ```
</CodeGroup>

What comes back in a Webhook or Server API response:

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tags": { "tags": 123 },
    // ...
  }

  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tags": { "tags": "signup" },
    // ...
  }

  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tags": {
      "id": "456",
      "location": {
        "city": "Atlanta",
        "country": "US"
      }
    }
    // ...
  }
  ```
</CodeGroup>

If the information stored in `tags` is not available on the client when the event happens, it is possible to set it through our [Update Event Server API](/reference/server-api-update-event).

To learn more about `tags` and `linkedId` use cases, see [Linking and tagging information](/docs/tagging-information).

### `tag` (deprecated)

> **Required**: no **Default**: `undefined` **Type**: any simple value or an object (not arrays) **Constraint**: the size must not exceed 16KB

**This option is deprecated. Use [`tags`](#tags) instead.**

`tag` is a customer-provided value or an object that is saved with the identification event and returned back to you in a webhook message or Server API response. You can use `tag` to associate the visit event with other information you have about the visitor.

You can use any simple value (string, number, boolean) or an object. An object is saved as provided. A simple value (for example `123`) is returned wrapped in an object like this: `{ "tag": 123 }`.

Examples of using the `tag` option:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  fp.get({ tag: 123 });
  fp.get({ tag: "signup" });
  fp.get({ tag: { id: "456", location: { city: "Atlanta", country: "US" }});
  ```
</CodeGroup>

What comes back in a Webhook or Server API response:

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tag": { "tag": 123 },
    // ...
  }

  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tag": { "tag": "signup" },
    // ...
  }

  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tag": {
      "id": "456",
      "location": {
        "city": "Atlanta",
        "country": "US"
      }
    }
    // ...
  }
  ```
</CodeGroup>

If the information stored in `tag` is not available on the client when the event happens, it is possible to set it through our [Update Event Server API](/reference/server-api-update-event).

### `timeout`

> **Required**: no **Default**: `10000` **Type**: `number`

Client timeout controls the total time (both client-side and server-side) that any analysis event can run. It doesn't include the time when the page is in the background (not visible) because the browser may suspend the analysis process during that time. By default, it's 10 seconds. You can set the client-side timeout *in milliseconds* using the `timeout` option. Example usage:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  // A timeout of 20 seconds
  // An example of the client-side timeout handling
  try {
    const result = await fp.get({ timeout: 20000 })
    // ...
  } catch (error) {
    if (error.code === 'client_timeout') {
      console.log("A timeout of 20 seconds exceeded")
    }
  }
  ```
</CodeGroup>

<Warning>
  Note that setting a low timeout (less than 2000ms) could increase identification failures on weaker devices with slower internet connections.
</Warning>

## `get()` response

`fp.get()` returns a promise that resolves to a result object. Only `event_id` and `sealed_result` are always present. Every other field is conditional on either workspace configuration or the options passed to `start()` (see the field reference below). The format summary:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  const result = await fp.get()
  // response (fully-populated shape):
  {
    event_id: "8nbmT18x79m54PQ0GvPq",        // always present
    visitor_id: "2JGu1Z4d2J4IqiyzO3i4",      // absent when Zero Trust mode is enabled
    suspect_score: 10,                        // present only when Smart Signals are enabled
    sealed_result: null,                      // BinaryOutput when Sealed Client Results are enabled, else null
    cache_hit: false                          // present only when `cache` was configured in start()
  }

  // Serialize the sealed_result before transport if needed:
  const sealedResultBase64 = result.sealed_result?.base64()

  // optionally you can do the following:
  // if you will try to cast `sealed_result` into a string it will automatically call
  // toString() method which will give you the base64, eg:
  console.log(result.sealed_result) // will log base64 string

  // if you will try to call JSON.stringify(result.sealed_result) it will call
  // the toJSON() method which will return base64 as well, eg:
  console.log(JSON.stringify(result.sealed_result)) // will log base64 string
  ```
</CodeGroup>

<Warning>
  Three fields may be `undefined` and need explicit guards before use:

  * `visitor_id` and `suspect_score` depend on **workspace configuration** (Zero Trust mode and Smart Signals respectively). Both are omitted whenever [Sealed Client Results](/docs/sealed-client-results) are enabled for the [environment](https://docs.fingerprint.com/docs/multiple-environments).
  * `cache_hit` depends on the **`start()` configuration** (the `cache` option), not workspace settings.

  Use optional chaining (`result.visitor_id?.startsWith(...)`) or explicit `if` checks before relying on any of them.
</Warning>

### get() response fields

#### `event_id`

> **Required**: yes **Type**: `string`

The request identifier is unique for every request. Use it to request information about a specific identification request from the [Server API](/reference/server-api-get-event).

#### `visitor_id`

> **Required**: no **Type**: `string`

The browser identifier (or device identifier for mobile platforms).

In most configurations the field is always present. It contains an empty string if the visitor can't be identified (for example, a search bot). If the identification product is disabled, a dummy value is used.

The field is omitted from the response (`undefined`) when the workspace has Zero Trust mode enabled. In that case the backend does not return a visitor identifier to the client and you should retrieve it from the [Server API](/reference/server-api-get-event) using `event_id`.

The field is omitted when [Sealed Client Results](/docs/sealed-client-results) are enabled. In that case only `event_id` and `sealed_result` are present in the response and you should decrypt `sealed_result` on your backend to retrieve the visitor ID.

#### `sealed_result`

> **Required**: yes **Type**: `BinaryOutput | null`

The field is always present in the response. It carries a `BinaryOutput` wrapper around the sealed payload when Sealed Client Results are enabled for the workspace, and `null` otherwise. See the [Sealed Client Results](/docs/sealed-client-results) guide for setup details.

`BinaryOutput` has five serialization methods:

* `base64(): string`
* `byteArray(): Uint8Array`
* `blob(): Blob`
* `toJSON(): string`
* `toString(): string`

<Note>
  The `BinaryOutput` interface is referenced inside the public `GetResult` type but is not exported as a top-level name from the package. If you need it for typing your own code, access it via `NonNullable<GetResult['sealed_result']>` (since `GetResult['sealed_result']` itself is `BinaryOutput | null`).
</Note>

#### `cache_hit`

> **Required**: no **Type**: `boolean`

The value is included if the `cache` configuration was used during the `start()` call and is:

* `true` if the `get()` response was retrieved from the cache.
* `false` if the `get()` response came directly from the Fingerprint backend.

The field is `undefined` when the `cache` option was not set in `start()`.

#### `suspect_score`

> **Required**: no **Type**: `number`

Shows the [Suspect Score](/docs/suspect-score) value of the event when the workspace has Smart Signals enabled. The field is `undefined` otherwise.

The field is omitted when [Sealed Client Results](/docs/sealed-client-results) are enabled, regardless of the Smart Signals setting.


# start function
Source: https://docs.fingerprint.com/reference/js-agent-start-function

API reference for the JavaScript agent's `start()` function

This page contains the API Reference for the JavaScript agent's `start()` function or its equivalent in your frontend library. The function is exported from the [@fingerprint/agent](https://www.npmjs.com/package/@fingerprint/agent) NPM package.

The `start()` function initializes the JavaScript agent for your Fingerprint workspace, which you can then use to identify visitors. When you call `start()`, the agent begins collecting the signals required for Identification and Smart Signals. Call `start()` as soon as possible, ideally right after the page loads.

If you are just getting started with Fingerprint, we recommend reading the following guides first:

* [Install the JavaScript agent](/docs/install-the-javascript-agent)
* [Identify visitors](/docs/identify-visitors)

## `start()` options

To configure the agent, pass parameters into the `start()` function.

### `apiKey`

> **Required**: yes for NPM installation **Type**: `string`

Your public API key to authenticate the agent. You can get one at [dashboard.fingerprint.com](https://dashboard.fingerprint.com). If you log into this documentation portal through the dashboard, you will be able to see your personal API key in the example below.

Example usage:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  Fingerprint.start({ apiKey: "<<browserToken>>" })
  ```
</CodeGroup>

The parameter is required for the NPM installation method and optional for the CDN (where the key is a part of the URL).

### `region`

> **Required**: no **Default**: `"us"` **Type**: `string` **Available values**: `"us"`, `"eu"` and `"ap"`

Use this parameter to specify the [region](/docs/regions) you picked for your workspace during registration (defaults to `us`).

The Fingerprint Platform CDN can usually determine the region automatically using your API Key. Even so, specifying it explicitly is recommended: it keeps your JavaScript agent working correctly even if the Fingerprint internal API is temporarily disrupted. With the [Custom subdomain setup](/docs/custom-subdomain-setup), this `region` option is also how the agent picks the correct regional API.

<Note>
  **Using a proxy integration?** [Proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers) route to the correct regional API using a `region` **query parameter in the `endpoints` URL**, not this top-level `region` option. Include the region in the `endpoints` URL, for example `endpoints: 'https://yourwebsite.com/INTEGRATION_PATH/?region=eu'`. See your integration's guide for details.
</Note>

Example:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  const fp = Fingerprint.start({ region: 'eu' })
  ```
</CodeGroup>

### `endpoints`

> **Required**: no **Default**: (depends on the region) **Type**: `string | string[]`

This parameter should only be used with the [Custom subdomain](/docs/custom-subdomain-setup#3-configure-the-javascript-agent) or a cloud [proxy integration](/docs/protecting-the-javascript-agent-from-adblockers). Specify your custom endpoint URL here.

Multiple endpoints can be set using an array. The JavaScript agent will try to send the request with the first endpoint, and if the request fails, retry the request with the second endpoint, and so on. Use `Fingerprint.withoutDefault()` helper if you want to disable our standard fallback endpoints.

<CodeGroup>
  ```javascript Endpoints theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://fp.example.com'
  })
  ```

  ```javascript No default endpoints theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: Fingerprint.withoutDefault('https://fp.example.com')
  })
  ```
</CodeGroup>

JavaScript agent will throw an error if an empty array is given.

### `storageKeyPrefix`

> **Required**: no **Default**: `'_vid_'` **Type**: `string`

Name of the key to store visitor data in browsers. The data is stored in cookies and local storage. You shouldn't change this parameter once your code runs in production. The change will cause the data in visitor browsers to be purged which will decrease the identification accuracy.

### `urlHashing`

> Only for NPM installation **Required**: no **Default**: `undefined` (no hashing) **Type**: `UrlHashing` **Since**: v3.11.0

`urlHashing` flags ensure no PII or secret data get unintentionally leaked through `path`, `query` or `fragment` values in an URL by replacing raw values with a securely encoded hash.

<Info>
  `urlHashing` configuration has no effect on performance or accuracy of Identification and Smart Signals products.
</Info>

The `UrlHashing` type has the following configuration structure

<CodeGroup>
  ```typescript UrlHashing theme={"theme":"github-dark-dimmed"}
  type UrlHashing = {
    path?: boolean
    query?: boolean
    fragment?: boolean
  }
  ```
</CodeGroup>

* `path` replaces the **path** portion of the URL with a securely encoded hash if set to `true`
* `query` replaces the **query** portion of the URL with a securely encoded hash if set to `true`
* `fragment` replaces the **fragment** portion of the URL with a securely encoded hash if set to `true`

The portion of the URL that contains either `path`, `query` or `fragment` is replaced with a single value that represents a securely encoded hash of the original URL parts.

Example:

The following example illustrates the behavior of our JavaScript agent without and with the `urlHashing` flags configured. **Original URL** represents the URL we would normally send to our backend (in an obfuscated form) **Result** shows how our JavaScript agent hashes the URL if the `path`, `query` and `fragment` parameters of `urlHashing` were set to `true` respectively. The order of the query parameters has no effect on the output hash.

**Original URL**

`https://example.com/test?param1=somePII&param2=clientSecret&param3=tokenValue#id342324`

| `path` enabled | `query` enabled | `fragment` enabled | Result                                                                                                                                                    |
| -------------- | --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NO             | YES             | NO                 | `https://example.com/test?UNrfPps8c1O_mrVgqvhVju4SCMDncBNJat8_iDK-00M#id342324`                                                                           |
| YES            | NO              | NO                 | `https://example.com/n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg?param1=somePII&param2=clientSecret&param3=tokenValue#id342324`                           |
| NO             | NO              | YES                | `https://example.com/test?param1=somePII&param2=clientSecret&param3=tokenValue#rws4nbTyh7ALUYP6QsxMBWqGTa2T0QzIWHBSRr0rHDo`                               |
| YES            | YES             | YES                | `https://example.com/n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg?UNrfPps8c1O_mrVgqvhVju4SCMDncBNJat8_iDK-00M#rws4nbTyh7ALUYP6QsxMBWqGTa2T0QzIWHBSRr0rHDo` |

<Info>
  If either `query`, `param` or `fragment` part are empty, they are returned as-is without hashing. As an example URL `https://example.com/?#` stays as is.
</Info>

### `cache`

> Only for NPM installation **Required**: no **Default**: `undefined` (do not use cache) **Type**: `CacheConfig` **Since**: v4.0.0

Added in version 4, the JavaScript agent now contains predefined caching options. By default, the agent does not cache any information and every call to `get()` results in a full billable event (sending signals to our backend and receiving a result). This is because **caching can be detrimental to the accuracy** and efficacy of our products (both Identification, and more prominently Smart Signals).

#### `CacheConfig`

The full `CacheConfig` type definition is

<CodeGroup>
  ```typescript CacheConfig theme={"theme":"github-dark-dimmed"}
  type CacheConfig =
    | false
    | {
        storage: 'sessionStorage' | 'localStorage' | 'agent' // this is a "memory" storage
        duration: 'optimize-cost' | 'aggressive'  | number
        cachePrefix?: string
      }
  ```
</CodeGroup>

where

**`storage`** determines where the JavaScript agent stores the cached information, by default it stores the information in memory (`agent` option).

Each `storage` option has the following semantics

* `sessionStorage` means the cached information is stored in the [Session Storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and clears when the browser/tab gets closed. Session storage outlives page refreshes as long as the same tab and origin remain open.
* `localStorage` means that the cached information is stored in the [Local Storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) and outlives browser restarts (and never expires by default).
* `agent` means that the cached information is stored in memory and clears with page (and agent) reloads.

**`duration`** represents the amount of time needed to clear the cache, it supports two predefined values and an arbitrary number option (with an upper limit).

* `optimize-cost` stores information in cache for **1 hour**
* `aggressive` stores information in cache for **12 hours** (we don't recommend using `aggressive` in fraud protection use cases)
* when supplied with a `number`, the agent stores the cache information for the exact `number` of seconds. Maximum value is `43200` and the agent will throw an error when a higher value was used.

**`cachePrefix`** is a prefix of the string key used to store the cached information (applies to `sessionStorage` and `localStorage` **`storage`** options).

## `start()` response

The `start()` function synchronously returns the JavaScript agent instance. The instance has a [`get()`](/reference/js-agent-get-function) method you can use to identify visitors.

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent';

  async function identifyVisitor() {
    const agent = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' })
    const result = await agent.get()
    console.log(result.visitor_id)
  }
  ```
</CodeGroup>

See [Configuring the JavaScript agent](/docs/install-the-javascript-agent#configuring-the-agent) for more details.


# Overview
Source: https://docs.fingerprint.com/reference/management-api

Management API allows you to manage your Fingerprint account and workspaces programmatically from a server environment.

Management API is only for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device.

<Check>
  **Management API requests do not count toward your monthly plan and are not billed.**
</Check>

# Getting started

Management API is available globally:

| Region | Base URL                         |
| ------ | -------------------------------- |
| Global | `https://management-api.fpjs.io` |

You can use Management API for all your workspaces, regardless of their region.

### Authentication

Management API requests are authorized by using the **Management API key** that can be obtained in your Fingerprint Dashboard by visiting **[API Keys](https://dashboard.fingerprint.com/api-keys)**.

Set your API key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer your-management-api-key
```

Read more about [Authentication](/reference/management-api-authentication).

### Version

Management API is versioned by date of the backwards-incompatible change made to the API. The latest version is `2025-11-20`.

Set the version as in the `X-API-Version` header:

```
X-API-Version: 2025-11-20
```

Read more about [Versioning](/reference/management-api-versioning).

### Making a request

Now we're ready to make our first request!

We can try to list all our environments by calling `GET https://management-api.fpjs.io/environments`. Note the added `Authorization` and `X-API-Version` headers.

```bash cURL theme={"theme":"github-dark-dimmed"}
curl -XGET -H 'Authorization: Bearer your-management-api-key' -H 'X-API-Version: 2024-05-20' 'https://management-api.fpjs.io/environments'
```

You should get a response listing all your workspace environments:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "data": [
    {
      "id": "env_ff035a1dd7655da15295fa5fa89362a7",
      "name": "Default environment",
      "created_at": "2023-10-05T14:48:00.000Z"
    }
  ]
}
```

And you're all set! Feel free to explore other methods available in Management API.

### Rate limiting

Management API is rate limited. The limit is enforced for every **Management API key**, and the default rate limit per API key is **5 req/sec**.

If you are an [Enterprise plan](https://fingerprint.com/pricing/) customer and your use case requires a higher limit, please reach out to our [support team](https://fingerprint.com/support/).

### Client SDKs

SDKs for specific languages are coming soon!

# Using API reference

You can try calling the Management API directly from this documentation:

1. Go to one listed API methods, for example **[List environments](/reference/2024-05-20-environmentcontroller_findall)**.
2. Set your API key as **Authorization**  bearer token.
3. Set API version by setting **X-API-Version** header to `2025-11-20`.
4. Click **Try it!**.

A real API response will appear in the **Response** section.

# Other resources

<Info>
  If you want to get information about visitors and identification events, check the [Server API](/reference/server-api) .

  If you want to identify browsers in your web application, read our [JavaScript agent guide](/reference/js-agent).

  If you want to identify mobile devices using native mobile SDKs, see [Android](/docs/native-android-integration) or [iOS](/docs/ios).
</Info>


# Authentication
Source: https://docs.fingerprint.com/reference/management-api-authentication

Management API requests are authorized by using the **Management API key**.

You can create one in your Fingerprint Dashboard by visiting **[API Keys](https://dashboard.fingerprint.com/api-keys)**, and opening **Management API** tab.

<Warning>
  **Your API key can be used to make changes to your Fingerprint account, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.**
</Warning>

Authentication is facilitated with **Bearer authentication** (also called token authentication), and it involves providing the API key as authorization token. The caller must send this token in the `Authorization` header when making requests to Management API.

When making an API request, add `Authorization` HTTP header with your Management API key.

```
Authorization: Bearer your-management-api-key
```

```bash cURL theme={"theme":"github-dark-dimmed"}
curl -XGET -H 'Authorization: Bearer your-management-api-key' -H 'X-API-Version: 2025-11-20' 'https://management-api.fpjs.io/hello'
```

Requests without a valid Authorization header will return `HTTP 401` error.


# Changelog
Source: https://docs.fingerprint.com/reference/management-api-changelog

This changelog lists all additions and updates to the Management API, in chronological order.

## Version 2025-11-20

**Breaking changes**

* Adds support for managing [Filtering Rules V2](/docs/request-filtering-v2).
* Standardizes response format for all routes to use `snake_case` exclusively.

**Non-breaking changes**

* *\[Aug 26th, 2026]* Adds general support for managing [custom subdomains](/docs/custom-subdomain-setup) (`subdomains`).

## Version 2024-05-20

* Initial release.
* Adds general support for managing API keys (`api-keys`).
* Adds general support for managing environments (`environments`).
* Adds general support for managing request filtering rules (`filtering-rules`).

**Non-breaking changes**

* *\[Oct 1st, 2025]* Adds general support for managing webhooks (`webhooks`)


# Pagination
Source: https://docs.fingerprint.com/reference/management-api-pagination



Some API resources have support for bulk fetches through “list” API methods. For example, you can list environments, list API keys, etc. These list API methods share a common structure and accept the following two parameters: `limit` and `cursor`.

Management API list methods use cursor-based pagination through the `cursor` parameter. After fetching the first page of resources, the response body will contain `metadata` information containing `next_cursor` token used to navigate to the next page.

```json JSON theme={"theme":"github-dark-dimmed"}
"metadata": {
    "pagination": {
      "nextCursor": "938c2cc0dcc05f2b68c4287040cfcf71",
      "prevCursor": null
    }
  }
```

To navigate to the next page, simply put this cursor token in the URL query for the next request:

```html URL query theme={"theme":"github-dark-dimmed"}
?limit=10&cursor=938c2cc0dcc05f2b68c4287040cfcf71
```

If you've already navigated forward, you can also use `prev_cursor` token from the response metadata to navigate backwards.


# Versioning
Source: https://docs.fingerprint.com/reference/management-api-versioning

Management API is *versioned*. When backwards-incompatible changes are made to the API, we release a new, dated version.

**The latest version is `2025-11-20`.**

Specifying API version is required to prevent breaking changes in the new versions breaking your integration. Any breaking changes will always be released in a new API version.

When making an API request, add `X-API-Version` HTTP header with the API version you’re using.

```
X-API-Version: 2025-11-20
```

```curl cURL theme={"theme":"github-dark-dimmed"}
curl -XGET -H 'Authorization: Bearer SECRET_API_KEY' -H 'X-API-Version: 2025-11-20' 'https://management-api.fpjs.io/hello'
```

Requests without a valid API version will return `HTTP 400` error.

Before upgrading to a new API version, you should read the **[Changelog](/reference/management-api-changelog)** to understand what breaking changes are included and to learn more about how to upgrade to a new API version.


# Migrating the Fingerprint Android SDK from v2 to v4
Source: https://docs.fingerprint.com/reference/migrating-android-sdk-from-v2-to-v4

This guide covers all breaking changes introduced in version `4.0.0` of the Fingerprint Android SDK and outlines the steps required to migrate an existing v2 integration.

We have released a new major version of the Fingerprint Android SDK (version `4.0.0`), which allowed us to introduce breaking changes and requires you to manually migrate. The new Android SDK aligns with the v4 event format. This includes renamed classes and interfaces, a flattened response format, and a revised set of error types. None of these changes affect the underlying identification and smart signals accuracy; these are structural/API changes only.

<Warning>
  * Native mobile SDKs v2.x will continue to work after v4.0.0 is released - you won't be forced to upgrade right away.
  * During this period, critical client-side hotfixes will still be issued for v2.x if needed, and backend-side improvements (including smart signals detection logic) can continue to benefit v2.x integrations, as long as the required signals are already collected by that SDK version.
  * However, iOS and Android SDKs v2.x support is tied to our overall API v3 deprecation timeline: once the [one-year deprecation period](https://docs.fingerprint.com/reference/migrating-from-v3-to-v4#client-sdk-compatibility-for-javascript-agent-v4) begins (which starts only after the full ecosystem, including Flutter and React Native SDKs, supports Server API v4), mobile SDKs v2.x will no longer receive client-side hotfixes once that period ends. Backend-side improvements will still apply to v2.x wherever the SDK already collects the necessary signals.
</Warning>

# What's new

* The dependency coordinate changed from `com.fingerprint.android:pro` to `com.fingerprint.android:sdk`, and the public API types moved from the `com.fingerprintjs.android.fpjs_pro` package to `com.fingerprint.android`, dropping the legacy `js`/`pro` naming.
* `FingerprintJSFactory` and the `FingerprintJS` interface are renamed to `FingerprintFactory` and `Fingerprint`, dropping the legacy "JS" naming.
* The response object is renamed from `FingerprintJSProResponse` to `FingerprintResponse`, and several nested/legacy fields (`confidenceScore`, `ipLocation`, `firstSeenAt`, and similar) have been removed in favor of a flat response shape, along with their supporting types (`ConfidenceScore`, `Timestamp`, and `IpLocation`).
* `requestId` is renamed to `eventId` across responses, errors, and exceptions.
* The `extendedResponseFormat` configuration flag has been removed as v4 always returns the flat format.
* Several error classes have been removed or replaced, and new error classes have been added to reflect new server-side error codes.
* Kotlin upgraded from v1.9.25 to v2.3.20.

# Migration steps

The following section outlines the necessary migration steps to complete the transition from v2 to v4.

## Upgrade the MAJOR package version

Update the Fingerprint Android SDK dependency to the latest v4 version in your module's `build.gradle` (or `build.gradle.kts`) `dependencies` block. The artifact coordinate also changed from `com.fingerprint.android:pro` to `com.fingerprint.android:sdk`:

<CodeGroup>
  ```kotlin build.gradle.kts theme={"theme":"github-dark-dimmed"}
  implementation("com.fingerprint.android:sdk:4.0.0")
  ```

  ```groovy build.gradle theme={"theme":"github-dark-dimmed"}
  implementation "com.fingerprint.android:sdk:4.0.0"
  ```
</CodeGroup>

## Update imports

The public API types moved to the `com.fingerprint.android` package. Update every `import com.fingerprintjs.android.fpjs_pro.*` statement to `com.fingerprint.android.*`. A project-wide **Replace All** in your IDE is the quickest way to do this.

<CodeGroup>
  ```kotlin Update imports theme={"theme":"github-dark-dimmed"}
  import com.fingerprintjs.android.fpjs_pro.Configuration // [!code --]
  import com.fingerprintjs.android.fpjs_pro.FingerprintFactory // [!code --]
  import com.fingerprintjs.android.fpjs_pro.FingerprintException // [!code --]
  import com.fingerprint.android.Configuration // [!code ++]
  import com.fingerprint.android.FingerprintFactory // [!code ++]
  import com.fingerprint.android.FingerprintException // [!code ++]
  ```
</CodeGroup>

## Class and interface renames

Several classes and interfaces were renamed to drop the legacy `JS` naming.

| Android SDK v2              | Android SDK v4            |
| --------------------------- | ------------------------- |
| `FingerprintJSFactory`      | `FingerprintFactory`      |
| `FingerprintJS` (interface) | `Fingerprint` (interface) |
| `FingerprintJSProResponse`  | `FingerprintResponse`     |

<CodeGroup>
  ```kotlin Class and interface renames theme={"theme":"github-dark-dimmed"}
  val client: FingerprintJS = FingerprintJSFactory(context).createInstance(config) // [!code --]
  val client: Fingerprint = FingerprintFactory(context).createInstance(config) // [!code ++]

  client.getVisitorId { response: FingerprintJSProResponse -> ... } // [!code --]
  client.getVisitorId { response: FingerprintResponse -> ... } // [!code ++]
  ```
</CodeGroup>

## `FingerprintResponse` field changes

The response object is now flat and no longer exposes the nested fields that came from the old `/products/identification/data/result` response format.

### Renamed

| Android SDK v2       | Android SDK v4     |
| -------------------- | ------------------ |
| `response.requestId` | `response.eventId` |

### Added

| Field          | Type     | Notes                                             |
| -------------- | -------- | ------------------------------------------------- |
| `eventId`      | `String` | Replaces `requestId`                              |
| `suspectScore` | `Int?`   | Risk score from the server; `null` if not present |

### Removed

The following fields are no longer part of the response:

| Removed field     | Type              |
| ----------------- | ----------------- |
| `requestId`       | `String`          |
| `visitorFound`    | `Boolean`         |
| `confidenceScore` | `ConfidenceScore` |
| `ipAddress`       | `String`          |
| `ipLocation`      | `IpLocation?`     |
| `osName`          | `String`          |
| `osVersion`       | `String`          |
| `firstSeenAt`     | `Timestamp`       |
| `lastSeenAt`      | `Timestamp`       |

The data classes `ConfidenceScore`, `Timestamp`, and `IpLocation` (including the nested `City`, `Country`, `Continent`, and `Subdivisions` types) have been removed from the SDK entirely. See [IP Geolocation](https://docs.fingerprint.com/docs/smart-signals-reference#ip-geolocation) for a replacement available in our Smart Signals product.

<CodeGroup>
  ```kotlin FingerprintResponse field changes theme={"theme":"github-dark-dimmed"}
  client.getVisitorId { response ->
      println(response.requestId) // [!code --]
      println(response.visitorFound) // [!code --]
      println(response.confidenceScore) // [!code --]
      println(response.ipAddress) // [!code --]
      println(response.firstSeenAt) // [!code --]
      println(response.eventId) // [!code ++]
      println(response.visitorId) // [!code ++]
      println(response.suspectScore) // [!code ++]
      // ipAddress, confidenceScore, firstSeenAt, and similar fields are no longer available // [!code ++]
  }
  ```
</CodeGroup>

## `Configuration` changes

`extendedResponseFormat: Boolean` has been removed. The v4 API always returns a flat response, so the extended format toggle no longer exists.

<CodeGroup>
  ```kotlin Remove extendedResponseFormat theme={"theme":"github-dark-dimmed"}
  Configuration(
      apiKey = "your_api_key",
      // ...
      extendedResponseFormat = true, // [!code --]
  )
  ```
</CodeGroup>

## Rename `requestId` to `eventId` on `Error` and `FingerprintException`

The `requestId` property on both `Error` and `FingerprintException` has been renamed to `eventId`.

<CodeGroup>
  ```kotlin Listener API theme={"theme":"github-dark-dimmed"}
  client.getVisitorId(
      listener = { response -> ... },
      errorListener = { error ->
          println(error.requestId) // [!code --]
          println(error.eventId) // [!code ++]
      }
  )
  ```

  ```kotlin Coroutine API theme={"theme":"github-dark-dimmed"}
  try {
      val response = client.getVisitorId()
  } catch (e: FingerprintException) {
      println(e.requestId) // [!code --]
      println(e.eventId) // [!code ++]
  }
  ```
</CodeGroup>

## Error class changes

### Removed error classes

These error classes no longer exist in v4. Remove any `when` branches or `isErrorType<T>()` checks that reference them.

* `ApiKeyExpired`
* `UnsupportedVersion`
* `OriginNotAvailable`
* `PackageNotAuthorized`
* `HeaderRestricted`
* `NotAvailableForCrawlBots`
* `NotAvailableWithoutUA`

### New error classes

The following error classes are new in v4 and map to new server-side error codes.

| New class                | When it occurs                                 |
| ------------------------ | ---------------------------------------------- |
| `SecretApiKeyRequired`   | Secret API key header is missing               |
| `SecretApiKeyNotFound`   | No workspace found for the provided secret key |
| `VisitorNotFound`        | Requested visitor does not exist               |
| `ServiceUnavailable`     | Server-side service unavailable                |
| `SubscriptionRestricted` | Subscription is restricted                     |
| `FeatureNotEnabled`      | Feature is not enabled for this workspace      |
| `RequestNotFound`        | Event or request not found                     |
| `StateNotReady`          | Resource is not yet mutable, retry later       |
| `MissingModule`          | A required server module is missing            |
| `PayloadTooLarge`        | Request payload exceeded the size limit        |
| `RulesetNotFound`        | Specified ruleset not found                    |
| `EnvironmentRestricted`  | Environment is restricted                      |
| `SubscriptionNotFound`   | Subscription not found                         |

If you have an exhaustive `when` on `Error` subtypes, add an `else` branch (or handle the new types explicitly) to avoid compile errors.

<CodeGroup>
  ```kotlin Error handling theme={"theme":"github-dark-dimmed"}
  errorListener = { error ->
      when (error) {
          is ApiKeyExpired -> handleExpired() // [!code --]
          is ApiKeyNotFound -> handleNotFound()
          is NetworkError -> handleNetwork()
          is ClientTimeout -> handleTimeout()
          is VisitorNotFound -> handleVisitorNotFound() // [!code ++]
          is ServiceUnavailable -> handleServiceUnavailable() // [!code ++]
          else -> logUnknown(error.requestId) // [!code --]
          else -> logUnknown(error.eventId) // [!code ++]
      }
  }
  ```
</CodeGroup>

### Check out these related resources:

* [Android SDK changelog](/docs/changelog-android-sdk#august-2026)
* [Android SDK reference](/docs/android-sdk)
* [Android Quickstart](/docs/android-quickstart)
* Download our [**Android demo app**](https://play.google.com/store/apps/details?id=com.fingerprintjs.android.fpjs_pro_demo) from
  Google Play to see Fingerprint in action.


# Migrating from Server API v3 to v4
Source: https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4

Learn how to migrate your integration from the deprecated Server API v3 endpoints to the new, improved Server API v4. This guide covers endpoint changes, authentication updates, and best practices for a smooth transition.

We are dedicated to providing the best and cleanest APIs possible. Our existing [Server API](/reference/v3/server-api) (v3) and Webhooks formats had inconsistencies and legacy baggage from our rapid growth. That's why we are introducing a new major iteration of our Server API and Webhooks. Read on to learn about the most important changes.

## Server SDK compatibility for Server API v4

| Server SDK                                                                          | Support status | Minimum version with v4 support                                                                     |
| ----------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| [Node Server SDK](/reference/node-server-sdk#migration-guide-for-node-sdk-v7)       | ✅ Supported    | [v7.0.0+](https://github.com/fingerprintjs/node-sdk/releases/tag/%40fingerprint%2Fnode-sdk%407.0.0) |
| [Python Server SDK](/reference/python-server-sdk#migration-guide-for-python-sdk-v9) | ✅ Supported    | [v9.0.0+](https://github.com/fingerprintjs/python-sdk/releases/tag/v9.0.0)                          |
| [Java Server SDK](/reference/java-server-sdk#migration-guide-for-java-sdk-v8)       | ✅ Supported    | [v8.0.0+](https://github.com/fingerprintjs/java-sdk/releases/tag/v8.0.0)                            |
| [.NET Server SDK](/reference/net-server-sdk#migration-guide-for-net-sdk-v8)         | ✅ Supported    | [v8.0.0+](https://github.com/fingerprintjs/dotnet-sdk/releases/tag/v8.0.0)                          |
| [PHP Server SDK](/reference/php-server-sdk#migration-guide-for-php-sdk-v7)          | ✅ Supported    | [v7.0.0+](https://github.com/fingerprintjs/php-sdk/releases/tag/v7.0.0)                             |
| [Go Server SDK](/reference/go-server-sdk#migration-guide-for-go-sdk-v8)             | ✅ Supported    | [v8.0.0+](https://github.com/fingerprintjs/go-sdk/releases/tag/v8.0.0)                              |

# What's new

* Removed excessive nesting in responses. Payloads are no longer nested under top-level `data` and `products`, including at individual Smart Signals level (removed `result`). This makes the format and generated documentation clearer and easier to consume.
  * See [example V3 Event response](/reference/v3/server-api-get-event), [v3 OpenAPI schema](https://fingerprintjs.github.io/fingerprint-pro-server-api-openapi/schemas/fingerprint-server-api.yaml).
  * See [example V4 Event response](/reference/server-api-get-event), [v4 full OpenAPI schema](https://fingerprintjs.github.io/fingerprint-pro-server-api-openapi/schemas/fingerprint-server-api-v4.yaml).
* Unified Webhooks and Server API (events format). All Server API responses now share the same data format described in our public documentation. [Sealed Client Results](/docs/sealed-client-results) use the same format with [JavaScript agent v4](/reference/js-agent).
* **Deprecated** the `/visitors` search endpoint in favor of `/v4/events` (which provides the same and more functionality). This legacy endpoint will be removed.
* Introduced more descriptive error codes and messages. Errors now include suggestions and links to relevant documentation where applicable.
* Removed the possibility of partial payloads when an internal service fails (previously it was possible to receive Identification data with Smart Signals errors). Unreliable partial responses are replaced with a clear error instead.
* Properties are omitted from events if they are not supported for the platform they were generated on. In v3, properties were set to `null` or `false` instead.
* Replaced the `Auth-Api-Key` header and `apiKey` parameter with the standard `Authorization: Bearer` header. Existing secret API keys work with this header without issues.
* Upgraded the OpenAPI version and started using an OpenAPI definition for Webhooks alongside the rest of the Server API documentation.
* Removed the `Retry-After` header as it did not work well with our rate limiting logic.
* Renamed `request_id` to `event_id`.
* Unified usage of `snake_case` across URLs and request/response payload fields.

# Migration Overview

<Warning>
  **Deprecation Notice**

  The [previous version of Server API](/reference/v3/server-api) was deprecated. If you still use this version, follow this guide to migrate from this deprecated version to the new one. The [one year deprecation period](/reference/api-deprecation-policy#one-year-migration-period) will start after the entire ecosystem supports API v4.
</Warning>

| v3 endpoint            | v4 endpoint                | action                                                 |
| ---------------------- | -------------------------- | ------------------------------------------------------ |
| `GET /visitors`        | `GET /v4/events`           | migrate to `GET /v4/events`                            |
| `GET /events`          | `GET /v4/events/:event_id` | migrate to `GET /v4/events/:event_id`                  |
| `PUT /events` (update) | `PATCH /v4/event`          | migrate to `PATCH /v4/event`                           |
| `GET /events/search`   | `GET /v4/events`           | migrate to `GET /v4/events`                            |
| Webhooks v3            | Webhooks v4                | configure new webhooks via Dashboard or Management API |

# How to migrate from v3 to v4

Migration needs depend on which deprecated endpoints you are using. If you are not using Server API or Webhooks, there is nothing to migrate today. For JavaScript agent changes, see [Migrating JavaScript agent from v3 to v4](/reference/migrating-from-v3-to-v4).

## Migrating GET /visitors

The `GET /visitors` endpoint is fully replaced by `/v4/events`, which is an extended version of the v3 `/events/search` endpoint.

* In `v4`, use filters such as `visitor_id`, `linked_id`, `suspect`, `start`, and `end` to get the same results.
* Latency differences: `/visitors` had latency independent of event age. In `/v4/events`, most recent events (≤24h) are served from cache and are very fast. Older events may take longer to load from archival storage.
* To minimize latency, always pass a time window with `start` and `end`.

<CodeGroup>
  ```bash v3 (/visitors) to v4 (/v4/events) theme={"theme":"github-dark-dimmed"}
  curl --request GET \
       --url "https://api.fpjs.io/v4/events?start=1725148800&end=1727731199" # [!code ++]
       --url "https://api.fpjs.io/visitors?limit=100" # [!code --] 
       --header 'Accept: application/json' \
       --header 'Authorization: Bearer SECRET_API_KEY' # [!code ++]
       --header 'Auth-Api-Key: SECRET_API_KEY' # [!code --]
  ```
</CodeGroup>

## Migrating GET /events

The current version of `GET /events` uses the old nested event format and the old `Auth-Api-Key` header. To migrate to the new `/v4/event` endpoint, you have to

1. Start using the `Authorization: Bearer SECRET_API_KEY` header for authorization
2. Migrate to the new format, either by using our Server SDKs or adopting the model to the v4 [specification](/reference/server-api-get-event)

## Migrating GET /events/search

The current version of `GET /events/search` uses the old nested event format and the old `Auth-Api-Key` header. To migrate to the new `/v4/events` endpoint, you have to

1. Start using the `Authorization: Bearer SECRET_API_KEY` header for authorization
2. Migrate to the new format, either by using our Server SDKs or adopting the model to the v4 [specification](/reference/server-api-search-events)

## Migrating UPDATE /events

The update operation remains conceptually the same, but method, path, auth header, and some field names have changed.

1. Exchange the `Auth-Api-Key: SECRET_API_KEY` header for `Authorization: Bearer SECRET_API_KEY`
2. Change the method from `PUT` to `PATCH`
3. Update the path to `/v4/events/:event_id`
4. Rename fields to `snake_case` (e.g., `linkedId` -> `linked_id`)
5. (optional) Check the documentation for new error codes and adapt your implementation to handle them

<CodeGroup>
  ```bash v3 to v4 theme={"theme":"github-dark-dimmed"}
    curl --request PATCH # [!code ++]
    curl --request PUT # [!code --]
       --url https://api.fpjs.io/v4/events/:event_id # [!code ++]
       --url https://api.fpjs.io/events # [!code --]
       --header 'Accept: application/json' \
       --header 'Content-type: application/json' \
       --header 'Authorization: Bearer SECRET_API_KEY' # [!code ++]
       --header 'Auth-Api-Key: SECRET_API_KEY' # [!code --]

       --data '
      {
        "linked_id": "<user_id>" [!code ++]
        "linkedId": "<user_id>" [!code --]
      }'

  ```
</CodeGroup>

## Response Fields Mapping

The following tables describe the field names in API v3 and their API v4 equivalents.

### Core and Identification Fields

This table maps the nested `products.identification.data.*` fields to the top-level of the v4 API response.

| v3                                       | v4                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------- |
| `requestId`                              | `event_id`                                                                      |
| `timestamp`                              | `timestamp`                                                                     |
| `time` (ISO-8601)                        | removed                                                                         |
| `tag`                                    | `tags`                                                                          |
| `linkedId`                               | `linked_id`                                                                     |
| `sdk`                                    | `sdk`                                                                           |
| `environmentId`                          | `environment_id`                                                                |
| `visitorId`                              | `identification.visitor_id`                                                     |
| `confidence.score`                       | `identification.confidence.score`                                               |
| `confidence.revision`                    | `identification.confidence.version` (renamed)                                   |
| `confidence.comment`                     | `identification.confidence.comment`                                             |
| `visitorFound`                           | `identification.visitor_found`                                                  |
| `firstSeenAt` / `lastSeenAt` (ISO-8601)  | `identification.first_seen_at` / `last_seen_at` (Unix millis int64)             |
| `ip`                                     | `ip_address`                                                                    |
| `ipLocation`                             | `ip_info.(v4,v6).geolocation`                                                   |
| `url`                                    | `url` (browser) / `bundle_id` (iOS) / `package_name` (Android) — platform-gated |
| `browserDetails.userAgent`               | `user_agent`                                                                    |
| `browserDetails.{device, os, osVersion}` | `device` / `os` / `os_version` **and** still nested under `browser_details`     |
| `incognito`                              | `incognito`                                                                     |
| `suspect`                                | `suspect`                                                                       |
| `replayed`                               | `replayed`                                                                      |

The `browserDetails.{browserName, browserMajorVersion, browserFullVersion}` fields have no v4 top-level equivalent field because these parsed values are only valid for browsers. They remain accessible under the `browser_details` field.

### Bot Detection, Smart Signals and Other Fields

This table maps the nested `products.<name>.data.*` fields to the top-level of the v4 API response.

| v3                                                                      | v4                                                                                  |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `botd.data.{bot, type}`                                                 | `bot`, `bot_type`, `bot_info`                                                       |
| `vpn.data.{result, confidence, methods, originCountry, originTimezone}` | `vpn`, `vpn_confidence`, `vpn_methods`, `vpn_origin_country`, `vpn_origin_timezone` |
| `proxy.data.{result, confidence, details, mlScore}`                     | `proxy`, `proxy_confidence`, `proxy_details`, `proxy_ml_score`                      |
| `tampering.data.{result, confidence, details, mlScore}`                 | `tampering`, `tampering_confidence`, `tampering_details`, `tampering_ml_score`      |
| `tor.data.result`                                                       | `ip_blocklist { email_spam, attack_source }`                                        |
| `ipBlocklist.data.details.{emailSpam, attackSource}`                    | `ip_blocklist { tor_node }`                                                         |
| `ipInfo.data.*`                                                         | `ip_info`                                                                           |
| `incognito.data.result`                                                 | `incognito`                                                                         |
| `jailbroken.data.result`                                                | `jailbroken`                                                                        |
| `frida.data.result`                                                     | `frida`                                                                             |
| `rootApps.data.result`                                                  | `root_apps`                                                                         |
| `emulator.data.result`                                                  | `emulator`                                                                          |
| `clonedApp.data.result`                                                 | `cloned_app`                                                                        |
| `factoryReset.data.time`                                                | `factory_reset_timestamp`                                                           |
| `privacySettings.data.result`                                           | `privacy_settings`                                                                  |
| `virtualMachine.data.{result, mlScore}`                                 | `virtual_machine`, `virtual_machine_ml_score`                                       |
| `mitmAttack.data.result`                                                | `mitm_attack`                                                                       |
| `locationSpoofing.data.result`                                          | `location_spoofing`                                                                 |
| `developerTools.data.result`                                            | `developer_tools`                                                                   |
| `suspectScore.data.result`                                              | `suspect_score`                                                                     |
| `highActivity.data.result`                                              | `high_activity_device`                                                              |
| `rareDevice.data.{result, percentileBucket}`                            | `rare_device`, `rare_device_percentile_bucket`                                      |
| `velocity.data.*`                                                       | `velocity`                                                                          |
| `proximity.data.*`                                                      | `proximity`                                                                         |
| `rawDeviceAttributes.data.*`                                            | `raw_device_attributes`                                                             |
| `remoteControl` (deprecated in v3)                                      | removed                                                                             |

## Migrating Webhooks

Webhooks v4 follow the same format as `/v4/events`, so you can reuse most of the code used with other Server API endpoints.

* See [v3 legacy webhook payload](/docs/webhooks#legacy-webhook-payload)
* See [v4 webhook payload](/reference/posteventwebhook)

You can manage both new and legacy Webhooks in the Dashboard. To migrate your legacy webhook to v4, you need to re-create it, and then delete the legacy webhook.

<img alt="" />

Alternatively, you can create Webhooks v4 via Management API. Follow this basic example to create a Webhook:

<CodeGroup>
  ```bash Create v4 Webhook theme={"theme":"github-dark-dimmed"}
  curl --request POST \
       --url https://management-api.fpjs.io/webhooks \
       --header 'Accept: application/json' \
       --header 'Content-type: application/json' \
       --header 'Authorization: Bearer SECRET_API_KEY' \
       --data '
      {
      "url": "https://example.com",
      "description": "My example v4 webhook",
      "status": "enabled"
      }'
  ```
</CodeGroup>

Review the Management API documentation on [Webhooks](/reference/webhookscontroller_findallv2/) for more detail about how to manage webhooks.

<Note>
  ### Set up the old and the new webhook side by side

  We recommend setting up a new webhook alongside the old one. Create a new webhook through the Management API mentioned above, integrate it, test that it delivers the new information correctly, and then remove the old one without any loss of data.
</Note>


# Migrating JavaScript agent from v3 to v4
Source: https://docs.fingerprint.com/reference/migrating-from-v3-to-v4

Comprehensive migration guide with all migration requirements between the v3 (3.x.x) and v4 (4.x.x) JavaScript agent versions.

We have released a new major version of the agent (version `4.x.x`), which allowed us to introduce breaking changes and requires customers to manually migrate. The new agent ensures that we are ready for continuous scaling and that our customers can benefit from reliable features along with latency and accuracy improvements.

<Warning>
  Most [client libraries](/docs/frontend-libraries) and all [proxy
  integrations](/docs/protecting-the-javascript-agent-from-adblockers) support JavaScript agent v4. If you use the [Flutter
  SDK](/docs/flutter) or [React Native SDK](/docs/fingerprintjs-pro-react-native), postpone migration until v4 support
  is available. The [one year deprecation
  period](/reference/api-deprecation-policy#one-year-migration-period) only starts after the entire
  ecosystem supports JavaScript agent v4 and Server API v4.
</Warning>

## Client SDK compatibility for JavaScript agent v4

| Client SDK or integration                                                    | Support status | Minimum version with v4 support                                                                                      |
| ---------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
| [React SDK](/docs/react)                                                     | ✅ Supported    | `@fingerprint/react` [v3.0.0](https://github.com/fingerprintjs/react/releases/tag/v3.0.0)                            |
| [Vue SDK](/docs/vuejs)                                                       | ✅ Supported    | `@fingerprint/vue` [v2.0.0](https://github.com/fingerprintjs/vue/releases/tag/%40fingerprint%2Fvue%402.0.0)          |
| [Angular SDK](/docs/angular)                                                 | ✅ Supported    | `@fingerprint/angular` [v3.0.0][angular-v3]                                                                          |
| [Svelte SDK](/docs/svelte)                                                   | ✅ Supported    | `@fingerprint/svelte` [v3.0.0](https://github.com/fingerprintjs/svelte/releases/tag/%40fingerprint%2Fsvelte%403.0.0) |
| [Flutter SDK](/docs/flutter)                                                 | 🚧 In progress | Not available yet                                                                                                    |
| [React Native SDK](/docs/fingerprintjs-pro-react-native)                     | 🚧 In progress | Not available yet                                                                                                    |
| [Google Tag Manager integration](/docs/fingerprintjs-pro-google-tag-manager) | ✅ Supported    | [v2.0.0](https://github.com/fingerprintjs/gtm-integration/releases/tag/v2.0.0)                                       |

## Proxy integration compatibility for JavaScript agent v4

| Proxy integration                                                          | Support status | Minimum version with v4 support                                                                                              |
| -------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [Custom subdomain setup](/docs/custom-subdomain-setup)                     | ✅ Supported    | Not versioned                                                                                                                |
| [Cloudflare Proxy Integration](/docs/cloudflare-integration)               | ✅ Supported    | [1.7.0](https://github.com/fingerprintjs/cloudflare-worker-proxy/releases/tag/v1.7.0)                                        |
| [AWS CloudFront Proxy Integration](/docs/cloudfront-proxy-integration-v2)  | ✅ Supported    | [v2.2.0](https://github.com/fingerprintjs/aws-cloudfront-proxy/releases/tag/%40fingerprint%2Faws-cloudfront-proxy%402.2.0)   |
| [Azure FrontDoor Proxy Integration](/docs/azure-proxy-integration)         | ✅ Supported    | [v2.0.0](https://github.com/fingerprintjs/azure-frontdoor-proxy/releases/tag/%40fingerprint%2Fazure-frontdoor-proxy%402.0.0) |
| [Akamai Proxy Integration](/docs/akamai-proxy-integration)                 | ✅ Supported    | [v1.1.0](https://github.com/fingerprintjs/akamai-proxy/releases/tag/v1.1.0)                                                  |
| [Fastly VCL Proxy Integration](/docs/fastly-vcl-proxy-integration)         | ✅ Supported    | [v2.0.0](https://github.com/fingerprintjs/fastly-vcl-proxy/releases/tag/v2.0.0)                                              |
| [Fastly Compute Proxy Integration](/docs/fastly-compute-proxy-integration) | ✅ Supported    | [v0.4.0](https://github.com/fingerprintjs/fastly-compute-proxy/releases/tag/v0.4.0)                                          |

# What's new

* The new agent matches our recently released [Server API v4](/reference/server-api-get-event) in terminology and the event format. This makes it easier to integrate across frontend and backend implementations, significantly reducing the time required to adopt new features.
* Removed deprecated configuration options:
  * `tlsDisabled` and `tlsEndpoint`, which made it possible to configure the old TLS endpoint. If you used this option, use the `endpoints` option instead, and let us know if you see any missing capabilities.
  * `extendedResult` became redundant as a `get()` option after the introduction of Smart Signals and Sealed Client Results. All information is sent to the client in a secure and encrypted form instead, if configured. **`Use sealed_result instead.`**
  * `scriptUrlPattern` was **removed**. Use the `endpoints` option if you need to configure a specific domain for agent script download.
  * The `sealedResult` response type changed in v4. In v3, `sealedResult` was a base64 string. In v4, `sealed_result` is `BinaryOutput | null` and must be serialized (for example, with `base64()`) before using it or sending it to your server.
  * The `products` field has been **completely removed**, as it had no impact on agent behavior anymore. This field does not have any replacement.
* `storageKey` was renamed to `storageKeyPrefix` and it does not add a leading underscore any more. See [`storageKey migration guide`](/reference/migrating-from-v3-to-v4#migrate-storagekey-to-storagekeyprefix) below for details. **Be careful as this might have negative impact on accuracy if set up incorrectly.**
* The `endpoint` was renamed to `endpoints` and is now a string by default (instead of an array).
  * By default, the `endpoints` option accepts a string but multiple strings can be supplied as an array if fallbacks are required.
  * Fingerprint's default endpoints are included as a default fallback, if you don't want to use the fallback endpoints use the `Fingerprint.withoutDefault()` helper.
* The NPM package name changed from `@fingerprintjs/fingerprintjs-pro` to `@fingerprint/agent`
* The main namespace has changed from `FingerprintJS` to `Fingerprint`.
* Stopped supporting the IIFE installation method (NPM and ESM installation methods remain available).
* Our agent now uses the [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) to improve latency and accuracy. This requires you to set up appropriate CSP rules to enable Web Worker code download and execution.
* Added built-in caching options with the `cache` parameter along with predefined values specified in the `CacheConfig` type. This replaces the need for the [SPA wrapper library](/docs/generic-js-agent-wrapper-for-spas).
* Revamped error handling from a fixed enum to more descriptive error messages that contain the resolution steps to get rid of the error.
* The `load()` method was renamed to `start()` and is now synchronous (does not return a promise).
* The agent code is compiled to the ES2018 standard (JS features like `let`, `const` and `async` work without transpiling). This reduces the code size.

# Migration steps

The following section outlines the necessary migration steps to complete the transition from the previous to the current version. The steps are in no specific order and some of them depend on specific installation methods and utilized configuration options.

## Upgrade the MAJOR package version

### IIFE

IIFE installation method has been completely deprecated in `4.0.0`. See the migration guide from IIFE to other supported installation methods below.

### NPM

If you used the NPM installation method, you have to first change the package name from `@fingerprintjs/fingerprintjs-pro` to `@fingerprint/agent`

<CodeGroup>
  ```bash NPM theme={"theme":"github-dark-dimmed"}
  npm remove @fingerprintjs/fingerprintjs-pro
  npm install @fingerprint/agent
  ```
</CodeGroup>

And then change the import statements in the code

<CodeGroup>
  ```typescript Change imports theme={"theme":"github-dark-dimmed"}
  import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro' // [!code --]
  import * as Fingerprint from '@fingerprint/agent' // [!code ++]

  const fpPromise = FingerprintJS.load({ ... }) // [!code --]
  const fp = Fingerprint.start({ ... }) // [!code ++]

  // ...
  ```
</CodeGroup>

### ESM

If you used the ESM installation method, you need to update the URL string from `v3` to `v4`

<CodeGroup>
  ```javascript Dynamic import theme={"theme":"github-dark-dimmed"}
  // [!code --:3]
  import('https://fpjscdn.net/v3/PUBLIC_API_KEY').then((FingerprintJS) => {
    FingerprintJS.load({ ... });
  });
  const Fingerprint = await import('https://fpjscdn.net/v4/PUBLIC_API_KEY'); // [!code ++]
  const agent = Fingerprint.start({ ... }); // [!code ++]
  // ...
  ```

  ```html Module theme={"theme":"github-dark-dimmed"}
  <script type="module">
    import * as FingerprintJS from 'https://fpjscdn.net/v3/PUBLIC_API_KEY' // [!code --]
    import * as Fingerprint from 'https://fpjscdn.net/v4/PUBLIC_API_KEY' // [!code ++]

    FingerprintJS. ... // [!code --]
    Fingerprint. ... // [!code ++]
  </script>
  ```
</CodeGroup>

## Change the namespace from `FingerprintJS` to `Fingerprint`

The `FingerprintJS` namespace was renamed to `Fingerprint` to represent our current brand. The `FingerprintJS` name is supposed to exclusively represent the original open-source `@fingerprintjs/fingerprintjs` project and not the paid product this documentation focuses on.

<CodeGroup>
  ```html FingerprintJS to Fingerprint theme={"theme":"github-dark-dimmed"}
  <script type="module">
    import * as FingerprintJS from 'https://fpjscdn.net/v3/PUBLIC_API_KEY' // [!code --]
    import * as Fingerprint from 'https://fpjscdn.net/v4/PUBLIC_API_KEY' // [!code ++]

    FingerprintJS. ... // [!code --]
    Fingerprint. ... // [!code ++]
  </script>
  ```
</CodeGroup>

## Set up new CSP policy rules

If you send the `Content-Security-Policy` header, you have to update it with new rules to support our new implementation that is using WebWorkers under the hood. The following header values should be added in case of using a Custom Subdomain/Proxy or our default endpoint respectively (in case the `endpoints` parameter was not used).

<CodeGroup>
  ```txt Custom Subdomain/Proxy theme={"theme":"github-dark-dimmed"}
  script-src <your custom subdomain>;
  connect-src <your custom subdomain>;
  worker-src blob:;
  ```

  ```txt Default endpoint (CDN/ESM) theme={"theme":"github-dark-dimmed"}
  script-src https://fpjscdn.net;
  connect-src https://api.fpjs.io https://*.api.fpjs.io;
  worker-src blob:;
  ```

  ```txt Default endpoint (NPM) theme={"theme":"github-dark-dimmed"}
  script-src https://fpnpmcdn.net;
  connect-src https://api.fpjs.io https://*.api.fpjs.io;
  worker-src blob:;
  ```
</CodeGroup>

## Migrate from the IIFE installation method to NPM or ESM

The IIFE installation has been completely deprecated and we recommend migrating to the ESM or NPM installation methods.

<CodeGroup>
  ```html IIFE to ESM theme={"theme":"github-dark-dimmed"}
  <!-- [!code --:4] -->
  <script src="https://fpjscdn.net/v3/PUBLIC_API_KEY/iife.min.js"></script>
  <script>
    FingerprintJS. ...
  </script>
  <!-- [!code ++:4] -->
  <script type="module">
    import * as Fingerprint from 'https://fpjscdn.net/v4/PUBLIC_API_KEY'
    Fingerprint. ...
  </script>
  ```

  ```html IIFE to Dynamic Import theme={"theme":"github-dark-dimmed"}
  <!-- [!code --:4] -->
  <script src="https://fpjscdn.net/v3/PUBLIC_API_KEY/iife.min.js"></script>
  <script>
    // FingerprintJS...
  </script>
  <!-- [!code ++:4] -->
  <script type="module">
    const fp = await import('https://fpjscdn.net/v4/PUBLIC_API_KEY'); // [!code ++]
    const agent = fp.start({});
  </script>
  ```

  ```html IIFE to NPM theme={"theme":"github-dark-dimmed"}
  <!-- [!code --:4] -->
  <script src="https://fpjscdn.net/v3/PUBLIC_API_KEY/iife.min.js"></script>
  <script>
    FingerprintJS. ...
  </script>
  <!-- [!code ++:3] -->
  // main.js
  import * as Fingerprint from '@fingerprint/agent'
  Fingerprint. ...
  ```
</CodeGroup>

## Migrate `storageKey` to `storageKeyPrefix`

If you used the `storageKey` option in v3, you have to migrate to the new `storageKeyPrefix` option and add a trailing underscore as that is not added automatically any more.

<CodeGroup>
  ```javascript storageKey to storageKeyPrefix theme={"theme":"github-dark-dimmed"}
  FingerprintJS.load({ // [!code --]
  Fingerprint.start({ // [!code ++]
      // other start/load options
  	storageKey: '__fp', // [!code --]
  	storageKeyPrefix: '__fp_', // An underscore has to be added to prevent negative accuracy impact losing cookies // [!code ++]
  })
  ```
</CodeGroup>

## Use `endpoints` instead of `tlsEndpoint`

The `tlsEndpoint` option (along with `disableTls` were completely deprecated in favor of the new `endpoints` option. If you used the `tlsEndpoint` option to set up a specific domain for the TLS endpoint specifically, you can now use the `endpoints` option instead.

<CodeGroup>
  ```typescript v3 theme={"theme":"github-dark-dimmed"}
  FingerprintJS.load({
    tlsEndpoint: 'https://mytls.fp.mydomain.com',
  });
  ```

  ```typescript v4 theme={"theme":"github-dark-dimmed"}
  Fingerprint.start({
    endpoints: 'https://fp.mydomain.com', // no need for a separate subdomain in v4 as the tlsEndpoint was deprecated completely
  });
  ```
</CodeGroup>

## Use `endpoints` instead of `scriptUrlPattern`

`scriptUrlPattern` was historically used for two different purposes

* To set up a custom subdomain for the agent script download (CDN installation).
* To set up a proxy integration using a first party domain, using special placeholders to tell the agent how to construct the final URL.

Both of those cases fall under the ad blocker protection measures and are now folded over to the `endpoints` option which follows certain path conventions.

<CodeGroup>
  ```typescript scriptUrlPattern to endpoints theme={"theme":"github-dark-dimmed"}
  const fpPromise = Fingerprint.load({ // [!code --]
  const fp = Fingerprint.start({ // [!code ++]
      // other start/load options
    scriptUrlPattern: ['/proxy_v3/cdn/v<version>/<apiKey>/loader_v<loaderVersion>.js', FingerprintJS.defaultScriptUrlPattern], // [!code --]
    endpoints: [ // [!code ++]
       'https://proxy1.mydomain.com', // default proxy // [!code ++]
       'https://proxy2.mydomain.com', // fallback proxy // [!code ++]
    ], // [!code ++]
  })
  ```
</CodeGroup>

## Use `sealed_result` instead of `sealedResult` and serialize it

In v3, `sealedResult` is a base64 string. In v4, `sealed_result` is `BinaryOutput | null`. Before using the result or sending it to your backend, you need to serialize it with one of the `BinaryOutput` methods:

* `base64(): string`
* `byteArray(): Uint8Array`
* `blob(): Blob`

[Sealed results](/docs/sealed-client-results) must be enabled, otherwise `sealed_result` is `null`.

```javascript with sealed_result (v4) theme={"theme":"github-dark-dimmed"}
const result = await fp.get();

console.log(result.sealedResult); // [!code --]
console.log(result.sealed_result?.base64()); // [!code ++]
```

## Remove `products`, `extendedResult`, `tlsEndpoint` and `tlsDisabled` from options

All of `products`, `extendedResult`, `tlsEndpoint` and `tlsDisabled` were removed from the `get()` and `start()` calls completely. The options need to be removed from the code to prevent errors.
The agent `get()` method now returns only a minimal amount of data to ensure tighter security on the client side. Furthermore, all non-essential fields were now removed but still remain available through the encrypted `sealed_result` response field.

<CodeGroup>
  ```javascript Remove deprecated parameters from start() and get() theme={"theme":"github-dark-dimmed"}
  import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro' // [!code --]
  import * as Fingerprint from '@fingerprint/agent' // [!code ++]

  const fpPromise = FingerprintJS.load({ // [!code --]
  const fp = Fingerprint.start({ // [!code ++]
    apiKey: 'asdfghjkl',
    region: 'eu',
    tlsEndpoint: 'https://tls.fp.mydomain.com', // [!code --]
    tlsDisabled: true // [!code --]
  })

  const result = await fp.get({
    products: [], // [!code --]
    extendedResult: true // [!code --]
  })
  ```
</CodeGroup>

## Make the start() method call synchronous

The `load()` method in the previous (3.x) version returned a Promise that had to be resolved before getting the agent instance. The new `start()` method is now synchronous and returns the agent instance immediately.

<CodeGroup>
  ```typescript Promise to Synchronous theme={"theme":"github-dark-dimmed"}
  import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro' // [!code --]
  import * as Fingerprint from '@fingerprint/agent' // [!code ++]

  const fpPromise = FingerprintJS.load({ // load options }) // [!code --]
  const fp = Fingerprint.start({ // start options }) // [!code ++]
  fpPromise.then(fp => { // [!code --]
      const result = await fp.get()
  })

  // ...
  ```
</CodeGroup>

## Change the error handling approach

In v3, errors were exposed as named literals (e.g., `FingerprintJS.ERROR_RATE_LIMIT`), and it was necessary to filter specific errors by their respective string values. This made it impossible to change/update the actual message which should be designed to help resolving the errors in the first place.

The current version does not expose any string literals in an enum and the error type is decided by including a `code` field in the `error` JSON response instead.

<CodeGroup>
  ```typescript v3 vs v4 theme={"theme":"github-dark-dimmed"}
    try {
    	// The general code above...
    } catch (error) {
  	if (error.message === FingerprintJS.ERROR_RATE_LIMIT) { // [!code --]
  	if (error.code === 'too_many_requests') { // [!code ++]
    		console.error('Too many requests, try again later')
  		// The error may contain a detailed message with possible resolution steps in error.message // [!code ++]
    	} else {
  		console.error('Unexpected error. Id for debugging:', error.requestId) // [!code --]
  		console.error('Unexpected error. Id for debugging:', error.event_id) // [!code ++]
    	}
    }
  ```
</CodeGroup>

[angular-v3]: https://github.com/fingerprintjs/angular/releases/tag/%40fingerprint%2Fangular%403.0.0


# Migrating the Fingerprint iOS SDK from v2 to v4
Source: https://docs.fingerprint.com/reference/migrating-ios-sdk-from-v2-to-v4

This guide covers all breaking changes introduced in version `4.0.0` of the Fingerprint iOS SDK and outlines the steps required to migrate an existing v2 integration.

We have released a new major version of the [Fingerprint iOS SDK v4.0.0](https://docs.fingerprint.com/docs/changelog-ios-sdk#august-2026), which allowed us to introduce breaking changes and requires you to manually migrate. The new iOS SDK aligns with the v4 event format. This includes a flattened response format, removed types, and a revised set of error codes. None of these changes affect the underlying identification and smart signals accuracy; these are structural/API changes only.

<Warning>
  * Native mobile SDKs v2.x will continue to work after v4.0.0 is released - you won't be forced to upgrade right away.
  * During this period, critical client-side hotfixes will still be issued for v2.x if needed, and backend-side improvements (including smart signals detection logic) can continue to benefit v2.x integrations, as long as the required signals are already collected by that SDK version.
  * However, iOS and Android SDKs v2.x support is tied to our overall API v3 deprecation timeline: once the [one-year deprecation period](https://docs.fingerprint.com/reference/migrating-from-v3-to-v4#client-sdk-compatibility-for-javascript-agent-v4) begins (which starts only after the full ecosystem, including Flutter and React Native SDKs, supports Server API v4), mobile SDKs v2.x will no longer receive client-side hotfixes once that period ends. Backend-side improvements will still apply to v2.x wherever the SDK already collects the necessary signals.
</Warning>

# What's new

* The library and module were renamed from `FingerprintPro` to `Fingerprint`. Update your imports from `import FingerprintPro` to `import Fingerprint`.
* The `FingerprintProFactory` type was renamed to `FingerprintFactory`. Update calls such as `FingerprintProFactory.getInstance(...)` to `FingerprintFactory.getInstance(...)`.
* The SDK is now distributed from a new Swift Package Manager repository, `https://github.com/fingerprintjs/fingerprint-ios`. Because this is a new package rather than a rename, you must remove the old package and add the new one.
* The CocoaPods pod was renamed from `FingerprintPro` to `Fingerprint-iOS`. CocoaPods is still supported for now but is deprecated, see the CocoaPods section below.
* The `FPJSError` error type was renamed to `FPError`.
* The response object `FingerprintResponse` changed from a deeply nested shape to a flat one. Several legacy fields (`confidence`, `ipLocation`, `firstSeenAt`, and similar) have been removed, along with their supporting types (`IPLocation`, `IPLocationSubdivision`, `IPGeoInfo`, and `SeenAt`).
* `requestId` is renamed to `eventId` on the response.
* A new `suspectScore` field of type `Int?` is added to the response.
* The `extendedResponseFormat` configuration flag has been removed as v4 always returns the flat format.
* The `APIError.Code` enum has been revised, with some cases removed, some renamed, and new ones added to reflect new server-side error codes.
* Swift upgraded from 5.9 to 6.
* Dropped support for iOS 13.

# Migration steps

The following section outlines the necessary migration steps to complete the transition from v2 to v4.

## Upgrade the MAJOR package version

Update the Fingerprint iOS SDK to the latest v4 version.

### Swift Package Manager

v4 is distributed from a new repository, `https://github.com/fingerprintjs/fingerprint-ios`. Because a new repository URL is a new package for Swift Package Manager, you can't simply bump the version:

1. Remove the existing `fingerprintjs-pro-ios` package from your project.
2. Add the new package `https://github.com/fingerprintjs/fingerprint-ios`, and set the dependency rule to **Up to Next Major Version** starting `from: "4.0.0"`.
3. Resolve packages.

For projects that declare dependencies in `Package.swift`, update the package URL and version:

<CodeGroup>
  ```swift Package.swift theme={"theme":"github-dark-dimmed"}
  .package(url: "https://github.com/fingerprintjs/fingerprintjs-pro-ios", from: "2.0.0"), // [!code --]
  .package(url: "https://github.com/fingerprintjs/fingerprint-ios", from: "4.0.0"), // [!code ++]
  ```
</CodeGroup>

<Warning>
  To keep using a previous (v2) version, continue using the old repository `https://github.com/fingerprintjs/fingerprintjs-pro-ios`.
</Warning>

### CocoaPods

CocoaPods is still supported in v4, but the pod was renamed from `FingerprintPro` to `Fingerprint-iOS` (the Swift Package Manager product, as mentioned above, stays `Fingerprint`). Update your `Podfile`, then run `pod update`:

<CodeGroup>
  ```ruby Podfile theme={"theme":"github-dark-dimmed"}
  pod 'FingerprintPro', '~> 2.0' # [!code --]
  pod 'Fingerprint-iOS', '~> 4.0' # [!code ++]
  ```
</CodeGroup>

<Warning>
  Following the [CocoaPods project's own shutdown plans](https://blog.cocoapods.org/CocoaPods-Specs-Repo/), it will stop accepting new versions in December 2026. Existing versions will keep working, but we recommend migrating to Swift Package Manager, which is the preferred installation method.
</Warning>

## Update imports, factory, and error type

The library and module were renamed from `FingerprintPro` to `Fingerprint`. Update every import across your project. A project-wide **Replace All** in your IDE is the quickest way to do this.

<CodeGroup>
  ```swift Rename the import theme={"theme":"github-dark-dimmed"}
  import FingerprintPro // [!code --]
  import Fingerprint // [!code ++]
  ```
</CodeGroup>

The `FingerprintProFactory` type was renamed to `FingerprintFactory`. Update any calls that create a client instance.

<CodeGroup>
  ```swift Rename the factory theme={"theme":"github-dark-dimmed"}
  let client = FingerprintProFactory.getInstance(configuration) // [!code --]
  let client = FingerprintFactory.getInstance(configuration) // [!code ++]
  ```
</CodeGroup>

The `FPJSError` error type was renamed to `FPError`. Update any typed error handling that references it.

<CodeGroup>
  ```swift Rename the error type theme={"theme":"github-dark-dimmed"}
  } catch let error as FPJSError { // [!code --]
  } catch let error as FPError { // [!code ++]
  ```
</CodeGroup>

## `FingerprintResponse` field changes

The response object is now flat and no longer exposes the nested fields that came from the v3 response format.

### Renamed

| iOS SDK v2           | iOS SDK v4         |
| -------------------- | ------------------ |
| `response.requestId` | `response.eventId` |

### Added

| Field          | Type     | Notes                                             |
| -------------- | -------- | ------------------------------------------------- |
| `eventId`      | `String` | Replaces `requestId`                              |
| `suspectScore` | `Int?`   | Risk score from the server; `null` if not present |

### Removed

The following fields are no longer part of the response:

| Removed field  | Type          |
| -------------- | ------------- |
| `requestId`    | `String`      |
| `visitorFound` | `Bool`        |
| `confidence`   | `Float`       |
| `ipAddress`    | `String?`     |
| `ipLocation`   | `IPLocation?` |
| `firstSeenAt`  | `SeenAt?`     |
| `lastSeenAt`   | `SeenAt?`     |

The `IPLocation`, `IPLocationSubdivision`, `IPGeoInfo`, and `SeenAt` structs have been removed from the SDK entirely. See [IP Geolocation](https://docs.fingerprint.com/docs/smart-signals-reference#ip-geolocation) for a replacement available in our Smart Signals product. Indicates the location as deduced from the IP address.

<CodeGroup>
  ```swift FingerprintResponse field changes theme={"theme":"github-dark-dimmed"}
  let response = try await fingerprintClient.getVisitorIdResponse()

  print(response.requestId) // [!code --]
  print(response.visitorFound) // [!code --]
  print(response.confidence) // [!code --]
  print(response.ipAddress) // [!code --]
  print(response.firstSeenAt) // [!code --]
  print(response.eventId) // [!code ++]
  print(response.visitorId) // [!code ++]
  print(response.suspectScore) // [!code ++]
  // ipAddress, confidence, firstSeenAt, and similar fields are no longer available // [!code ++]
  ```
</CodeGroup>

## `Configuration` changes

`extendedResponseFormat` has been removed. The v4 API always returns a flat response, so the extended format toggle no longer exists.

<CodeGroup>
  ```swift Remove extendedResponseFormat theme={"theme":"github-dark-dimmed"}
  let configuration = Configuration(
      apiKey: "your_api_key",
      // ...
      extendedResponseFormat: true // [!code --]
  )
  ```
</CodeGroup>

## Error handling changes

The `APIError.Code` enum has been revised for v4. Some cases were removed, some renamed, and new ones added to reflect new server-side error codes. Update any exhaustive `switch` statements over `APIError.Code` to handle the current set of cases.

The complete set of `APIError.Code` cases in v4:

| Case                                        | Raw value                                       |
| ------------------------------------------- | ----------------------------------------------- |
| `requestCannotBeParsed`                     | `request_cannot_be_parsed`                      |
| `requestReadTimeout`                        | `request_read_timeout`                          |
| `secretApiKeyRequired`                      | `secret_api_key_required`                       |
| `secretApiKeyNotFound`                      | `secret_api_key_not_found`                      |
| `publicApiKeyRequired`                      | `public_api_key_required`                       |
| `publicApiKeyNotFound`                      | `public_api_key_not_found`                      |
| `subscriptionNotActive`                     | `subscription_not_active`                       |
| `wrongRegion`                               | `wrong_region`                                  |
| `featureNotEnabled`                         | `feature_not_enabled`                           |
| `visitorNotFound`                           | `visitor_not_found`                             |
| `tooManyRequests`                           | `too_many_requests`                             |
| `stateNotReady`                             | `state_not_ready`                               |
| `failed`                                    | `failed`                                        |
| `eventNotFound`                             | `event_not_found`                               |
| `missingModule`                             | `missing_module`                                |
| `payloadTooLarge`                           | `payload_too_large`                             |
| `serviceUnavailable`                        | `service_unavailable`                           |
| `rulesetNotFound`                           | `ruleset_not_found`                             |
| `invalidProxyIntegrationSecret`             | `invalid_proxy_integration_secret`              |
| `proxyIntegrationSecretEnvironmentMismatch` | `proxy_integration_secret_environment_mismatch` |
| `invalidProxyIntegrationHeaders`            | `invalid_proxy_integration_headers`             |
| `subscriptionRestricted`                    | `subscription_restricted`                       |
| `environmentRestricted`                     | `environment_restricted`                        |
| `subscriptionNotFound`                      | `subscription_not_found`                        |
| `installationMethodRestricted`              | `installation_method_restricted`                |

If you have an exhaustive `switch` on `APIError.Code`, add a `default` branch (or handle the new cases explicitly) to avoid compile errors.

### Check out these related resources:

* [iOS SDK changelog](/docs/changelog-ios-sdk#august-2026)
* [iOS SDK reference](/docs/ios-sdk)
* [iOS Quickstart](/docs/ios-quickstart)
* Download our [**iOS demo app**](https://apps.apple.com/us/app/fingerprint-pro/id1644105278) from App Store to see Fingerprint in action.


# Webhook
Source: https://docs.fingerprint.com/reference/posteventwebhook

webhook event



# Server API
Source: https://docs.fingerprint.com/reference/server-api

Fingerprint Server API enables you to get more information about your visitors or about individual identification events.

Server API enables you to retrieve, search, and update identification event data, and manage visitor data. It is designed for use only from server-side environments — never directly from client-facing surfaces such as browsers or mobile devices.

Server API requests are not billed and do not count towards your monthly allowance.

The following Server APIs are available:

* [`/v4/events/:event_id`](/reference/server-api-get-event)
  * [GET](/reference/server-api-get-event) a detailed payload for a **single** event defined by an `event_id`
  * [PATCH](/reference/server-api-update-event) an event with `linked_id`, `tag` and `suspect` flag

* [`/v4/events`](/reference/server-api-search-events)
  * [GET](/reference/server-api-search-events)  a list of event details using on a wide range of built-in filters (`linked_id`, `visitor_id`, `start`, `end` and `suspect` fields among others).

* [`/v4/events/:event_id/feedback`](/reference/server-api-submit-event-feedback)
  * [POST](/reference/server-api-submit-event-feedback) feedback for an identification event

* [`/v4/visitors/:visitor_id`](/reference/server-api-delete-visitor-id)
  * [DELETE](/reference/server-api-delete-visitor-id) all data associated with a specific visitor ID

### See Also

* To identify the browsers that visit your web application, see our documentation for [JavaScript agent](/reference/js-agent).
* To identify the mobile devices that use your mobile app, see our documentation for [Android](/docs/native-android-integration) and [iOS](/docs/ios).

## Regions

The server API is available in the **Global**, **EU** and **Asia (Mumbai)** regions:

| Region        | Base URL                 | Server Location    |
| ------------- | ------------------------ | ------------------ |
| Global        | `https://api.fpjs.io`    | Global             |
| EU            | `https://eu.api.fpjs.io` | Frankfurt, Germany |
| Asia (Mumbai) | `https://ap.api.fpjs.io` | Mumbai, India      |

Use the **Base URL** dropdown in the right column of each endpoint to select the correct base URL according to your workspace region.

## Authentication

Use an `Authorization: Bearer` header to authenticate to the API. All unauthenticated requests will return a `HTTP 403 Forbidden` response.

### Authorization: Bearer HTTP header

When making an API request, add the `Authorization: Bearer SECRET_API_KEY` HTTP header with your [secret API key](https://dashboard.fingerprint.com/api-keys?type=api).

Example request including the API key in the `Authorization` header

<CodeGroup>
  ```bash bash theme={"theme":"github-dark-dimmed"}
  curl https://api.fpjs.io/v4/events/EVENT_ID  \
       -H `Authorization: Bearer SECRET_API_KEY`
  ```
</CodeGroup>

## Query parameter syntax

For query parameters with multiple values, use the repeated keys syntax (`parameter=value1&parameter=value2`).
Other notations like comma-separated (`parameter=value1,value2`) or bracket notation (`parameter[]=value1&parameter[]=value2`) are not supported.

## Rate limiting

If you exceed the rate limit when making a Server API call, you'll get an HTTP 429 error:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "error": {
    "code": "too_many_requests",
    "message": "too many requests"
  }
}
```

Retry the request after a short interval. The response may include a `Retry-After` header indicating how long to wait.

## Error handling

Handle Server API responses according to the error type instead of retrying every failure the same way.

| HTTP status | Meaning                                                           | Recommended action                                                                  |
| ----------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `400`       | Invalid parameter such as a malformed ID, date, or pagination key | Fix the request and do not retry as-is                                              |
| `403`       | Missing or invalid secret API key                                 | Check the API key and retry only after fixing it                                    |
| `404`       | Event, visitor, or other resource not found                       | Confirm the identifier exists in your workspace                                     |
| `429`       | Rate limited or the service is under heavy load                   | Retry with exponential backoff and honor a numeric `Retry-After` delay when present |
| `504`       | Query timed out                                                   | Narrow the time range or add a more specific filter before retrying                 |

### Retry with backoff for `429`

```python theme={"theme":"github-dark-dimmed"}
import time, requests

def call_server_api(url, params=None, headers=None, max_retries=5):
    delay = 1.0
    for attempt in range(max_retries):
        response = requests.get(url, params=params, headers=headers)
        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        if retry_after and retry_after.isdigit():
            delay = max(delay, float(retry_after))

        if attempt == max_retries - 1:
            break

        time.sleep(delay)
        delay = min(delay * 2, 60)

    return response
```

## Best practices

Use these guidelines when querying [`GET /v4/events`](/reference/server-api-search-events) so searches stay fast, predictable, and complete.

### Overview

Keep these limits and defaults in mind:

* **Default time window**: The API searches the last 7 days when `start` and `end` are omitted.
* **Maximum lookback**: Depending on your [Fingerprint plan](/docs/billing#account-limits), searches can look back 30-90 days.
* **Page size cap**: `limit` is capped at 500 events per request.
* **Query timeout**: Broad queries can return `504 Gateway Timeout` after 30 seconds.
* **Rate limiting**: Under load, the API can return `429 Too Many Requests`, so your integration should retry with backoff.

### 1. Retrieve a single known event with `GET /v4/events/{event_id}`

If you already know the `event_id`, use [Get event by event ID](/reference/server-api-get-event) instead of the search endpoint:

```http theme={"theme":"github-dark-dimmed"}
GET /v4/events/EVENT_ID
```

Use it for:

* Server-side verification of a specific identification result
* Fetching full Smart Signals for one event
* Confirming an event exists before taking action on it

### 2. Always filter by an indexed field

The most important performance rule is to include at least one of `visitor_id`, `linked_id`, or `ip_address`.

Without one of these filters, the API must scan all events for your workspace across the requested time range. On large workspaces, that is the most common cause of `504` timeouts.

| Filter       | Use case                                                                      |
| ------------ | ----------------------------------------------------------------------------- |
| `visitor_id` | Look up the history of a specific browser or device                           |
| `linked_id`  | Look up events tied to your internal user, session, or transaction ID         |
| `ip_address` | Look up events from a specific IP address or CIDR range such as `10.0.0.0/24` |

**Good: scoped query**

```http theme={"theme":"github-dark-dimmed"}
GET /v4/events?visitor_id=VISITOR_ID&start=2024-01-01T00:00:00Z&end=2024-01-02T00:00:00Z
```

**Avoid: broad unscoped query**

```http theme={"theme":"github-dark-dimmed"}
GET /v4/events?start=2024-01-01T00:00:00Z&end=2024-01-31T00:00:00Z
```

### 3. Use narrow time ranges

Always provide both `start` and `end`, and keep the time window as narrow as your use case allows.

* The default 7-day window is useful for recent lookups, but explicit timestamps are more predictable.
* For monitoring and alerting, query the last few minutes rather than hours.
* For historical exports, split the work into smaller windows such as one day at a time.

```http theme={"theme":"github-dark-dimmed"}
GET /v4/events?visitor_id=VISITOR_ID&start=2024-06-01T00:00:00Z&end=2024-06-02T00:00:00Z
```

### 4. Use cursor-based pagination for large result sets

When a response includes `pagination_key`, repeat the same request with that value until no new `pagination_key` is returned.

Do not adjust `start` and `end` to simulate pagination. That can miss or duplicate events, especially when multiple events share the same timestamp.

**First page**

```http theme={"theme":"github-dark-dimmed"}
GET /v4/events?visitor_id=VISITOR_ID&start=2024-06-01T00:00:00Z&end=2024-06-02T00:00:00Z&limit=100
```

**Next page**

```http theme={"theme":"github-dark-dimmed"}
GET /v4/events?visitor_id=VISITOR_ID&start=2024-06-01T00:00:00Z&end=2024-06-02T00:00:00Z&limit=100&pagination_key=PAGINATION_KEY
```

Notes:

* The pagination key is an opaque cursor. Do not parse or modify it.
* Do not store pagination keys for long-term reuse.
* If you receive a `400` invalid pagination key error, restart pagination from the beginning.

### 5. Use `reverse=true` for chronological processing

By default, search results are returned newest first. If you are replaying events into a processing pipeline or data warehouse, use `reverse=true` so the oldest events are returned first.

```http theme={"theme":"github-dark-dimmed"}
GET /v4/events?visitor_id=VISITOR_ID&start=2024-06-01T00:00:00Z&end=2024-06-02T00:00:00Z&reverse=true&limit=100
```

### 6. Use built-in filters to reduce result size

Use the search endpoint's filters to narrow results before they are returned instead of filtering client-side.

| Filter         | Values                       | Use case                                                                               |
| -------------- | ---------------------------- | -------------------------------------------------------------------------------------- |
| `bot`          | `all`, `good`, `bad`, `none` | Exclude or isolate bot traffic                                                         |
| `suspect`      | `true`, `false`              | [Find events you previously flagged as fraudulent](/reference/server-api-update-event) |
| `vpn`          | `true`, `false`              | Isolate events where a VPN was detected                                                |
| `url`          | URL string                   | Filter by the page or app where identification ran                                     |
| `bundle_id`    | iOS bundle ID                | Filter by iOS app                                                                      |
| `package_name` | Android package              | Filter by Android app                                                                  |
| `asn`          | ASN number string            | Filter by network or carrier                                                           |

```http theme={"theme":"github-dark-dimmed"}
GET /v4/events?suspect=true&start=2024-06-01T00:00:00Z&end=2024-06-02T00:00:00Z
```

### 7. Understand environment scoping

If your workspace uses [environments](/docs/multiple-environments), search results are automatically scoped by the API key you use:

* A workspace-scoped API key returns events across all environments.
* An environment-scoped API key returns only events from that environment.

If you expect events but receive an empty response, confirm that the API key matches the environment where identification ran.

### 8. Use day-by-day iteration for bulk exports

The Events API is a search API, not a streaming export API. For large exports:

1. Iterate by day instead of querying the full time range at once.
2. Include a filter such as `visitor_id`, `linked_id`, `ip_address`, or `url` whenever possible.
3. Follow `pagination_key` within each window until it is exhausted.
4. Add a small delay between paginated requests to reduce the chance of `429` responses.
5. Use `reverse=true` for append-only processing so restarts remain idempotent.

## Server API SDKs

For a smoother developer experience, we offer typed SDKs for these languages:

* [Node SDK](https://github.com/fingerprintjs/node-sdk)
* [PHP SDK](https://github.com/fingerprintjs/php-sdk)
* [Python SDK](https://github.com/fingerprintjs/python-sdk)
* [C# SDK](https://github.com/fingerprintjs/dotnet-sdk/)
* [Java SDK](https://github.com/fingerprintjs/java-sdk)
* [Go SDK](https://github.com/fingerprintjs/go-sdk)

Pick one of them as the **Language** on the endpoint page's top right corner to see an example request using that SDK.

The SDKs (and this reference) are based on a Server API OpenAPI schema, which is also available on GitHub:

* [Server API OpenAPI schema](https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi)

## Trying it out

You can try calling the Server API directly from this reference:

1. You are going to need a Secret API Key. You can create one in your Fingerprint **Dashboard** > [**API Keys**](https://dashboard.fingerprint.com/api-keys).
2. To make a request, you will need an `event_id` of an identification event associated with your workspace. Go to **Dashboard** > [**Identification**](https://dashboard.fingerprint.com/visits) to see your identification events.
3. Scroll down to one of the endpoints, for example, [Get event by event ID](/reference/server-api-get-event).
4. Set **Authentication** to your secret API key.
5. Set the **event\_id** path parameter to some `event_id` from your dashboard.
6. Make sure the **Base URL** corresponds to your workspace region.
7. Click **Try it!**

A real API response will appear in the **Response** section. Alternatively, you can view the prepared response examples there.


# Delete a visitor ID
Source: https://docs.fingerprint.com/reference/server-api-delete-visitor-id

delete /visitors/{visitor_id}
Use this API to request the deletion of all data associated with a specific visitor ID.

Upon a request to delete data for a visitor ID,
- The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID.
- The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. 
- The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention).

The following timeline illustrates which events are deleted and which remain after a DELETE API request:
```
Day 1:  First visit from browser A. (Assigned visitor ID: VID1000)
Day 2:  Browser A revisits. (Assigned the same visitor ID: VID1000)
Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000)
Day 14: Delete VID1000
Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999)
Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted)
Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available)
```

### Availability
This API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/).

### Rate limits and daily quota
The rate limits and daily quota for this API **differ** from those for our other API.

The maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD.

You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/).    




# Get an event by event ID
Source: https://docs.fingerprint.com/reference/server-api-get-event

get /events/{event_id}
Get a detailed analysis of an individual identification event, including Smart Signals.

Use `event_id` as the URL path parameter. This API method is scoped to a request, i.e. all returned information is by `event_id`.




# Search events
Source: https://docs.fingerprint.com/reference/server-api-search-events

get /events
## Search

The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include:

- Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor.
- Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier.
- Excluding all bot traffic from the query (`good` and `bad` bots)

By default, the API searches events from the last 7 days, sorts them by newest first and returns the last 10 events.

- Use `start` and `end` to specify the time range of the search.
- Use `reverse=true` to sort the results oldest first.
- Use `limit` to specify the number of events to return.
- Use `pagination_key` to get the next page of results if there are more than `limit` events.

### Filtering events with the `suspect` flag

The `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API.

You can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior.

### Environment scoping

If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments.

Smart Signals not activated for your workspace or are not included in the response.


<Info>
  See [Best practices](/reference/server-api#best-practices) for guidance on filtering, time ranges, pagination, and bulk exports with `GET /v4/events`.
</Info>


# Submit feedback for an event
Source: https://docs.fingerprint.com/reference/server-api-submit-event-feedback

post /events/{event_id}/feedback
Use this API to submit feedback for a specific, existing event, identified by `event_id`.

Feedback is queued and processed asynchronously. Subsequent Server API responses may not reflect the feedback immediately.

Duplicate feedback requests for the same event are allowed; however, the most recent feedback overrides all previous submissions for that event.

### Availability
This API is currently in beta and available only for Enterprise plans. If you are interested, please [contact our support team](https://fingerprint.com/support/).

### Rate limits and daily quota
The rate limits and daily quota for this API **differ** from those for our other APIs.

Feedback can be submitted at a maximum of 30 requests per hour (RPH) and cannot exceed 500 requests per day (RPD).

You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). 




# Update an event
Source: https://docs.fingerprint.com/reference/server-api-update-event

patch /events/{event_id}
Change information in existing events specified by `event_id` or *flag suspicious events*.

When an event is created, it can be assigned `linked_id` and `tags` submitted through the JS agent parameters. 
This information might not have been available on the client initially, so the Server API permits updating these attributes after the fact.

**Warning** It's not possible to update events older than one month. 

**Warning** Trying to update an event immediately after creation may temporarily result in an 
error (HTTP 409 Conflict. The event is not mutable yet.) as the event is fully propagated across our systems. In such a case, simply retry the request.




# Browser and device support
Source: https://docs.fingerprint.com/docs/browser-and-device-support

An overview of Fingerprint compatibility across various browsers and devices.

## Browsers

Fingerprint supports all popular browsers. We aim to cover at least 99% of all users according to our Fingerprint Identification statistics. The overall identification accuracy of traffic coming from supported browsers is industry-leading based on all Fingerprint identification statistics. Our research and development team continuously monitors releases of supported browsers and adjusts our identification algorithm if necessary.

At the moment, the supported browsers are:

| Browser                 | Version   | Notes                                                                  |
| ----------------------- | --------- | ---------------------------------------------------------------------- |
| Edge                    | **140+**  |                                                                        |
| Chrome                  | **110+**  |                                                                        |
| Firefox                 | **128+**  |                                                                        |
| Desktop Safari          | **16.0+** | See [below](#safari-intelligent-tracking-prevention) for more details. |
| Mobile Safari           | **16.0+** |                                                                        |
| Mobile Samsung Internet | **29.0+** | See [below](#samsung-internet-browser-support) for more information    |
| Brave                   | **1.48+** | See [below](#brave-browser-support) for more details.                  |

Browsers not listed here may work, but we don't make guarantees about identification functionality or accuracy.

The identification accuracy of individual browsers may vary, and their impact on your overall identification accuracy depends on their prevalence in your traffic. See [Understanding our accuracy](/docs/identification-accuracy-and-confidence) for an explanation of how we measure our accuracy.

### Safari Intelligent Tracking Prevention

Apple Safari has an on-by-default privacy protection feature called [Intelligent Tracking Protection](https://webkit.org/blog/9521/intelligent-tracking-prevention-2-3/), or ITP. ITP has been very effective in preventing cross-site tracking by completely disabling 3rd-party cookies and capping the lifetime of all script-writable website data.

By default, the Fingerprint API uses 3rd party cookies (both client-side set with `document.cookie` and server-side set with the `Set-Cookie` HTTP header) and script-writable website data (localStorage) to more reliably [identify returning visitors](https://fingerprint.com/blog/browser-fingerprinting-techniques/). All of these methods are affected by ITP, lowering identification accuracy. View the methods for [keeping identification accuracy high](#keeping-identification-accuracy-high) to maximize identification accuracy.

### Brave browser support

[Brave](https://brave.com/) is a privacy-focused browser based on Chromium. For our purposes, it behaves similarly to Chrome with a strict ad-blocking extension installed. That means it blocks the agent download and identification requests to Fingerprint CDN and API. View the methods for [keeping identification accuracy high](#keeping-identification-accuracy-high) to ensure your requests are not blocked.

### Samsung Internet browser support

[Samsung Internet](https://play.google.com/store/apps/details?id=com.sec.android.app.sbrowser\&hl=en_US\$0) is a browser optimized for Samsung Galaxy devices, but available for all Androids. Fingerprint only supports the Android version of this browser. iOS, desktop, and TV versions of Samsung browser are not supported.

### Keeping identification accuracy high

Ad-blocking extensions and browser features can disrupt visitor identification. To maintain high identification accuracy even with Safari and Brave, you need to use a [custom subdomain setup](/docs/custom-subdomain-setup) or a cloud proxy integration like [Cloudflare](/docs/cloudflare-integration) or [Cloudfront](/docs/cloudfront-proxy-integration-v2). These methods allow you to route Fingerprint HTTP requests through your domain, preventing browsers from blocking them and making cookies set by Fingerprint considered "first-party." See [Protecting the JavaScript agent from ad-blockers](/docs/protecting-the-javascript-agent-from-adblockers) for more details.

## Mobile devices

Fingerprint supports most iOS and Android devices in circulation today. The overall identification accuracy of traffic coming from mobile devices is even higher than that of browsers, thanks to long-lasting system-level attributes available on mobile platforms.

At the moment, the supported OS versions are:

| OS      | Version                               | Notes                                                                                |
| ------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
| Android | 5.0 Lollipop (API Level 21) or higher | See [Android](/docs/native-android-integration#supported-versions) for more details. |
| iOS     | 13+                                   | See [iOS](/docs/ios#supported-versions) for more details.                            |

***

[Regions and data retention](/docs/regions)


# Android SDK
Source: https://docs.fingerprint.com/docs/changelog-android-sdk

This changelog lists all additions and updates to the Fingerprint Android SDK, in chronological order.

<Update label="September 2026">
  ## v4.1.0

  ### What's new

  * Bug fixes and internal improvements.
  * Reduced SDK size.

  Android SDK v4.1.0 size info: 3.51MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**2.3.20** (`org.jetbrains.kotlin:kotlin-*:2.3.20`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="August 2026">
  ## v4.0.0

  <Warning>
    This version includes breaking changes and requires you to manually migrate. For more details on upgrading to Android SDK v4.0.0, refer to the [Migrating the Fingerprint Android SDK from v2 to v4](https://docs.fingerprint.com/reference/migrating-android-sdk-from-v2-to-v4) page.
  </Warning>

  ### What's new

  * `FingerprintJSFactory` and the `FingerprintJS` interface are renamed to `FingerprintFactory` and `Fingerprint`, dropping the legacy "JS" naming.
  * The response object is renamed from `FingerprintJSProResponse` to `FingerprintResponse`, and several nested/legacy fields (`confidenceScore`, `ipLocation`, `firstSeenAt`, and similar) have been removed in favor of a flat response shape, along with their supporting types (`ConfidenceScore`, `Timestamp`, and `IpLocation`). Check the [migration guide](https://docs.fingerprint.com/reference/migrating-android-sdk-from-v2-to-v4) to see the full list.
  * `requestId` is renamed to `eventId` across responses, errors, and exceptions.
  * The `extendedResponseFormat` configuration flag has been removed as v4 always returns the flat format.
  * Several error classes have been removed or replaced, and new error classes have been added to reflect new server-side error codes. Check the [migration guide](https://docs.fingerprint.com/reference/migrating-android-sdk-from-v2-to-v4) for more details about error classes.
  * Kotlin upgraded from v1.9.25 to v2.3.20.
  * Added in-code documentation for better DX: API documentation is published as a Javadoc JAR alongside the Maven artifacts, so it's available directly in your IDE when you add the dependency.
  * Bug fixes and stability improvements for low-end Android devices.
  * Reduced SDK size.

  Android SDK v4.0.0 size info: 3.94MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**2.3.20** (`org.jetbrains.kotlin:kotlin-*:2.3.20`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="August 2026">
  ## v2.17.1

  ### What's new

  * Started collecting additional signals to support upcoming improvements to Android identification.

  Android SDK v2.17.1 size info: 4.23MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="July 2026">
  ## v2.17.0

  ### What's new

  * Added internal improvements to enhance fraud detection capabilities. These updates lay the groundwork for upcoming backend enhancements.
  * Reduced false positives in emulator and rooted device detection.
  * Internal bug fixes and security updates.

  Android SDK v2.17.0 size info: 4.13MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="June 2026">
  ## v2.16.0

  ### What's new

  * Added internal improvements to support enhanced detection logic and upcoming backend updates.

  Android SDK v2.16.0 size info: 4.12MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="April 2026">
  ## v2.15.0

  ### What's new

  * Updated client-level logic to improve the accuracy and reliability of [rooted device detection](https://docs.fingerprint.com/docs/smart-signals-reference#rooted-device-detection).
  * Expanded the range of device-level signals collected for deeper device integrity insights.
  * Internal bug fixes and performance improvements.

  Android SDK v2.15.0 size info: 3.53MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="March 2026">
  ## v2.14.0

  ### What's new

  * Reduced Android SDK AAR size by 1.5MB (from 4.7MB to 3.2MB)
  * Fixed crashes during app initialization on low-end devices running Android 12, 13, and 15, including devices with limited available RAM.
  * Added [coroutine support](/docs/android-quickstart#4-initialize-the-sdk) for cleaner, more idiomatic integration in Kotlin-based Android projects.
  * Internal bug fixes and performance improvements.

  Android SDK v2.14.0 size info: 3.2MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="February 2026">
  ## v2.13.1

  ### What's new

  * Added internal improvements to support enhanced detection logic and upcoming backend updates.
  * Security updates and minor bug fixes.

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="December 2025">
  ## v2.12.0

  ### What's new

  * Added internal improvements to enhance fraud detection capabilities. These updates lay the groundwork for upcoming backend enhancements.
  * Improved [cloned app detection](/docs/smart-signals-reference#cloned-app-detection) on Android.

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="October 2025">
  ## v2.11.0

  ### What's new

  **Recommendation**: We strongly encourage upgrading to the version **2.11.0** to benefit from improved security and stronger protection against tampering and reverse-engineering attempts.

  * Implemented additional security measures to protect Android SDK requests from manipulation, tampering, and reverse-engineering attempts.
  * Deprecated support for Android 5.x.
  * Improved [rooted device detection](/docs/smart-signals-reference#rooted-device-detection) on Android.
  * Improved [emulator detection](/docs/smart-signals-reference#android-emulator-detection) logic on Android.
  * The total SDK size increased from 800kB to 4.5MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 35 (`targetSdk = 35`)
  * **Compiled using** API Level 35 (`compileSdk = 35`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="September 2025">
  ## v2.10.0

  ### What's new

  * Introduced a new proximity detection location-based signal for mobile devices. Instead of representing a unique device, the new proximity ID corresponds to a fixed geographical zone within which the device is observed. This additional layer of context makes it possible to identify groups of devices in the same physical area or a single device that may have changed its identity but remained in the same location. See [Proximity detection for Android devices](/docs/smart-signals-reference#proximity-detection) reference for more info.
    * The Android SDK will only collect location data if the new [`allowUseOfLocationData`](/docs/android-sdk#allowuseoflocationdata) option is set to `true`.
    * It's possible to configure the location retrieval timeout by setting the new [`locationTimeoutMillis`](/docs/android-sdk#locationtimeoutmillis) option to a desired value. By default, it's set to 5 seconds. Refer to [Using Location Data for Proximity Detection](/docs/android-sdk#using-location-data-for-proximity-detection) page for configuration details.
  * Enhanced the detection logic to more accurately identify true [factory resets](/docs/smart-signals-reference#factory-reset-detection) on Android devices. This update reduces false positives and improves signal reliability for fraud prevention workflows.

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 35 (`targetSdk = 35`)
  * **Compiled using** API Level 35 (`compileSdk = 35`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.7.3** (`com.android.tools.build:gradle:8.7.3`)
  * Gradle: v**8.10.2**
  * jvmTarget : **Java 8**
</Update>

<Update label="August 2025">
  ## v2.9.0

  ### What's new

  * Introduced internal architecture updates and performance improvements to support upcoming capabilities.
  * Addressed minor data collection issues to improve SDK reliability.
  * Added new error codes
    * `InvalidProxyIntegrationSecret`
    * `InvalidProxyIntegrationHeaders`
    * `ProxyIntegrationSecretEnvironmentMismatch`

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 35 (`targetSdk = 35`)
  * **Compiled using** API Level 35 (`compileSdk = 35`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="February 2025">
  ## v2.8.0

  ### What's new

  * Introduced the ability to detect if requests from the app were subject to MitM attacks. See [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection) to learn more.
  * Added support for [Open Client Response](/docs/v3/open-client-response).
  * Minor enhancements to identification and detection of Smart Signals.

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 35 (`targetSdk = 35`)
  * **Compiled using** API Level 35 (`compileSdk = 35`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.7.3** (`com.android.tools.build:gradle:8.7.3`)
  * Gradle: v**8.10.2**
  * jvmTarget : **Java 8**
</Update>

<Update label="October 2024">
  ## v2.7.0

  ### What's new

  * Added support for [Sealed Client Results](/docs/android-sdk#reading-the-response).

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 34 (`targetSdk = 34`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**

  ## v2.6.0

  ### What's new

  * Introduced the ability to configure the timeout interval for the client session. To learn more, see [Specifying a custom timeout](/docs/android-sdk#specifying-a-custom-timeout).
  * Added internal improvements to enhance fraud detection capabilities. These updates lay the groundwork for upcoming backend enhancements.

  ### What's changed

  * Information about Installed Applications is no longer collected and used.
  * Removed dependency `com.github.fingerprintjs:fingerprint-android`

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 34 (`targetSdk = 34`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="August 2024">
  ## v2.5.0

  ### What's new

  * Introduced the ability to redirect failed requests to alternate endpoints. The list `Configuration.fallbackEndpointUrls` can be used to specify one or more alternate endpoints. For a complete example, see [Getting a visitorId](/docs/android-sdk#getting-a-visitorid).

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 34 (`targetSdk = 34`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.10** (`org.jetbrains.kotlin:kotlin-*:1.9.10`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="January 2024">
  ## v2.4.0

  ### What's new

  * Introduced a new child class, `PackageNotAuthorized` to the sealed class, `Error`. This error is returned when an unauthorized app makes identification requests using a stolen API key. See [Request filtering for mobile apps](/docs/mobile-app-filtering) for more information.
  * Enhanced our [VPN Detection Smart Signal](/docs/smart-signals-reference#vpn-detection-for-mobile-devices) with a new data point, [`originCountry`](/docs/smart-signals-reference#vpn_origin_country) that indicates the country in which the mobile device is currently located at.

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 34 (`targetSdk = 34`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.10** (`org.jetbrains.kotlin:kotlin-*:1.9.10`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="October 2023">
  ## v2.3.4

  ### What's new

  * Introduced the ability to detect if the device location has been spoofed. To learn more, see [Geolocation Spoofing Detection](/docs/smart-signals-reference#geolocation-spoofing-detection).
  * Added runtime dependency `com.google.android.gms:play-services-location`

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.10** (`org.jetbrains.kotlin:kotlin-*:1.9.10`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**

  ## v2.3.3

  ### What's new

  * Introduced the ability to detect if a device is using VPN. To learn more, see [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices).
  * Introduced the ability to detect if an app using this SDK is being instrumented by Frida. To learn more, see [Frida Detection](/docs/smart-signals-reference#frida-detection).
  * Added runtime dependency `androidx.core:core`

  ### What's changed

  * Upgraded dependency `com.github.fingerprintjs:fingerprint-android` to v**2.1.0**

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.10** (`org.jetbrains.kotlin:kotlin-*:1.9.10`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="July 2023">
  ## v2.3.2

  ### What's changed

  * Upgraded dependency `com.github.fingerprintjs:fingerprint-android` to v**2.0.2**

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 33 (`compileSdk = 33`)

  ### Build Info

  * Kotlin: v**1.8.21** (`org.jetbrains.kotlin:kotlin-*:1.8.21`)
  * Android Gradle Plugin: v**7.4.2** (`com.android.tools.build:gradle:7.4.2`)
  * Gradle: v**7.5.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="April 2023">
  ## v2.3.1

  ### What's changed

  * The following dependencies have now been declared within `com.fingerprint.android:pro`. They need not anymore be individually included in build.gradle.
    * `org.jetbrains.kotlin:kotlin-stdlib`
    * `com.github.fingerprintjs:fingerprint-android`
  * Reduced the size of the payload that is transmitted from the device to Fingerprint’s servers.

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 33 (`compileSdk = 33`)

  ### Build Info

  * Kotlin: v**1.8.0** (`org.jetbrains.kotlin:kotlin-*:1.8.0`)
  * Android Gradle Plugin: v**7.4.2** (`com.android.tools.build:gradle:7.4.2`)
  * Gradle: v**7.5.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="March 2023">
  ## v2.3.0

  ### What's changed

  * Introduced the ability to detect if the requests to the app are being made from
    * An emulated device. To learn more, see [Android Emulator Detection](/docs/smart-signals-reference#android-emulator-detection).
    * A rooted device. To learn more, see [Rooted Device Detection](/docs/smart-signals-reference#rooted-device-detection).
    * A factory-reset device. To learn more, see [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection).
  * Introduced the ability to detect if a cloned version of the app is being used to make requests to your servers. To learn more, see [Cloned App Detection](/docs/smart-signals-reference#cloned-app-detection).

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 33 (`compileSdk = 33`)

  ### Build Info

  * Kotlin: v**1.7.0** (`org.jetbrains.kotlin:kotlin-*:1.7.0`)
  * Android Gradle Plugin: v**7.2.2** (`com.android.tools.build:gradle:7.2.2`)
  * Gradle: v**7.4.2**
  * jvmTarget : **Java 8**
</Update>


# CLI
Source: https://docs.fingerprint.com/docs/changelog-cli

This changelog lists all additions and updates to the Fingerprint CLI, in chronological order.

<Update label="September 2026">
  ## Fingerprint CLI is now available

  Set up Fingerprint in your project from the terminal with the new `fingerprint` CLI. Run `npx fingerprint integrate` to sign in through your browser, provision API keys into your `.env`, and add client-side identification and server-side verification to your project. Running `npx fingerprint` starts the same guided setup.

  The CLI also includes the `keys`, `login`, `signup`, `whoami`, and `logout` commands. It is open source in the [GitHub repository](https://github.com/fingerprintjs/fingerprint-cli).
</Update>


# Dashboard
Source: https://docs.fingerprint.com/docs/changelog-dashboard

This changelog lists all additions and updates to the Fingerprint Dashboard, in chronological order.

<Update label="September 2026">
  ## Breakdown charts on the Overview page

  The timeline chart on the Overview page has a new **Breakdowns** group in the chart selector. A breakdown plots the composition of your identification events over time, so you can see a trend shift as it happens instead of comparing two point-in-time distribution lists.

  Six breakdowns are available: **Browsers**, **Client types**, **Client versions**, **Countries**, **Operating systems**, and **URLs**. Each one renders as a stacked chart of the top 5 entities for the selected period, with everything else grouped into **Other**, and can be switched between absolute counts and percentage share, or between a chart and a table.

  Breakdowns are available in all workspaces.

  See [Analytics](/docs/analytics).
</Update>

<Update label="September 2026">
  ## Bots & AI agents replaces the Bot Detection page

  The Dashboard sidebar has a new **Bots & AI agents** section, with an **Overview** page for bot traffic analytics and an **Events** page for individual automation events. It replaces the Bot Detection page under Smart Signals, and existing links to that page redirect to the new Overview.

  The Overview page reports your traffic against the full bot taxonomy: metrics for total bots, AI traffic, and trusted, spoofed, and unknown identities; six timeline charts; top bot names, providers, and categories; and an identity breakdown of every category against its identity results. Switch between the **Automation Intelligence API** and **JS Agent** tabs to change the data source behind the page.

  The Overview page is available to all workspaces while the [Automation Intelligence API](/reference/automation-intelligence-api) is in Public Preview. The **JS Agent** tab requires the Bot Detection Smart Signal in your plan.

  See [Bots and AI agents](/docs/dashboard-bots-ai-agents) for the full guide.
</Update>

<Update label="September 2026">
  ## One-click subdomain setup with Domain Connect

  You can now set up a custom subdomain without editing any DNS records. The Dashboard detects whether your domain's DNS provider supports Domain Connect and shows a one-click setup card. You authorize the change with your provider, records are applied instantly, and verification and certificate issuance continue automatically.

  * Cloudflare is the first supported provider. Fingerprint is onboarding others next.
  * Records are applied as **DNS only**, which avoids Cloudflare proxying misconfiguration.
  * Domains on providers without Domain Connect support keep the manual setup flow.

  See [Custom subdomain setup](/docs/custom-subdomain-setup).
</Update>

<Update label="July 2026">
  ## Subdomain setup improvements

  Custom subdomain setup now fits into a single visit instead of several. On **Settings** > **Subdomains**:

  * All DNS records appear upfront. The page shows the `CNAME` verification record and both `A` routing records together, rather than hiding the `A` records until the certificate is issued.
  * **Copy** and **Download** controls grab every record in one action, including a pasteable zone-file format for providers that support bulk import, such as Cloudflare and Route 53. Per-record copy buttons remain.
  * Subdomain status updates live while you are on the page, with a progress indicator during verification and a success state once the subdomain is **Active**.
  * **Check DNS records** triggers an on-demand DNS check instead of waiting for the background cycle.

  See [Custom subdomain setup](/docs/custom-subdomain-setup).
</Update>

<Update label="June 2026">
  ## Health page restructure

  The Health page is now a high-level triage view that links out to entity-specific pages for detail, instead of a single detail-heavy surface. It features three widgets:

  * **Throttled requests**: the number of requests throttled in the current period, and the API keys responsible.
  * **Webhooks**: your webhook failure rate, and the webhooks with the most recent delivery failures.
  * **SDK versions**: how many updates are available across your integrations.

  Below the widgets, the charts are merged into one view with a selector for **API Latency**, **API Errors**, and **Webhook Failed Calls**.

  SDK health moved to **Libraries & Integrations**, where each active library shows recent usage and current version information. Version tracking is now origin-first: you see each domain or app, the URLs within it, and the SDK versions found there. The previous version-first view could not distinguish an origin that still needs updating from stale cached clients still sending old requests.

  See [Health](/docs/health).
</Update>

<Update label="June 2026">
  ## Top IP addresses and Top visitor IDs distributions

  The Overview page has two additional distribution lists: **IP address** and **Visitor ID**. Both rank items by the number of identification events in the selected time range, which helps you spot a small number of visitors generating a disproportionate share of your traffic.

  See [Overview page](/docs/analytics#overview-page).
</Update>

<Update label="May 2026">
  ## Suspect Score weights by confidence level

  You can now set Suspect Score weights according to how confident a detection is, instead of applying one weight per Smart Signal regardless of confidence.

  * For **VPN detection**, apply weights by method (public service, relay, timezone mismatch, and others) or by confidence (`low`, `medium`, `high`).
  * For **Residential proxy**, apply a flat weight or weights by confidence (`low`, `medium`, `high`).

  See [Configuring weights by confidence level](/docs/suspect-score#configuring-weights-by-confidence-level).
</Update>

<Update label="May 2026">
  ## Stripe Checkout and Stripe Customer Portal

  Billing flows now use Stripe's hosted Checkout page instead of an in-app card form, and payment methods are managed in the Stripe Customer Portal instead of a custom Dashboard screen.

  * Apple Pay, Google Pay, Cash App Pay, and Link, including Instant Bank Payments, are available alongside cards for a first paid workspace, an upgrade, or a reactivation.
  * Invoices are visible in both the Dashboard and the Stripe Portal.
  * Card data is collected on Stripe's domain, so Fingerprint never handles raw card details.

  Existing customers keep the previous flow. See [Payment methods](/docs/billing#payment-methods).
</Update>

<Update label="April 2026">
  ## Proximity ID in event search, details, and CSV export

  Proximity information for iOS events is now visible throughout the Identification pages.

  * The Event Details page shows the proximity ID in the device and identification section, and in the quick reference sidebar.
  * The Identification page has a proximity ID filter, and you can add proximity ID as a column from the column display dropdown.
  * Proximity data is included in the CSV export for both Server API v3 and v4.

  See [Proximity Detection](/docs/smart-signals-reference#proximity-detection).
</Update>

<Update label="April 2026">
  ## Server API v4 by default

  The Dashboard now presents Server API v4, which is the recommended and actively developed version, rather than v3.

  * Smart Signals snippets on the Event Details page use the Server API v4 format.
  * The event JSON viewer defaults to v4.
  * The CSV export dialog has a v3 and v4 selector that changes the column names in the exported file.

  See [Migrating from Server API v3 to v4](/reference/migrating-from-server-api-v3-to-v4).
</Update>

<Update label="March 2026">
  ## Workspace reactivation

  Reactivating a canceled workspace no longer requires contacting support.

  * Canceled workspaces show a reactivation banner in the sidebar with a link to choose a plan.
  * The Plans page offers **Reactivate free** and **Reactivate** options based on your eligibility.

  See [Fingerprint Platform Billing](/docs/billing).
</Update>


# iOS SDK
Source: https://docs.fingerprint.com/docs/changelog-ios-sdk

This changelog lists all additions and updates to the Fingerprint iOS SDK, in chronological order.

<Update label="August 2026">
  ## v4.0.0

  <Warning>
    This version includes breaking changes and requires you to manually migrate. For more details on upgrading to iOS SDK v4.0.0, refer to the [Migrating the Fingerprint iOS SDK from v2 to v4](https://docs.fingerprint.com/reference/migrating-ios-sdk-from-v2-to-v4) page.
  </Warning>

  ### What's new

  * The library and module were renamed from `FingerprintPro` to `Fingerprint`. Update your imports from `import FingerprintPro` to `import Fingerprint`.
  * The `FingerprintProFactory` type was renamed to `FingerprintFactory`. Update calls such as `FingerprintProFactory.getInstance(...)` to `FingerprintFactory.getInstance(...)`.
  * The SDK is now distributed from a new Swift Package Manager repository, `https://github.com/fingerprintjs/fingerprint-ios`. Because this is a new package rather than a rename, you must remove the old package and add the new one.
  * The CocoaPods pod was renamed from `FingerprintPro` to `Fingerprint-iOS`. CocoaPods is still supported for now but is deprecated.
  * The `FPJSError` error type was renamed to `FPError`.
  * The response object `FingerprintResponse` changed from a deeply nested shape to a flat one. Several legacy fields (`confidence`, `ipLocation`, `firstSeenAt`, and similar) have been removed, along with their supporting types (`IPLocation`, `IPLocationSubdivision`, `IPGeoInfo`, and `SeenAt`).
  * `requestId` is renamed to `eventId` on the response.
  * A new `suspectScore` field of type `Int?` is added to the response.
  * The `extendedResponseFormat` configuration flag has been removed as v4 always returns the flat format.
  * The `APIError.Code` enum has been revised to reflect new server-side error codes.
  * Swift upgraded from 5.9 to 6.
  * Dropped support for iOS 13.
  * Reduced latency.
  * Reduced SDK size.
  * Added DocC documentation to the iOS SDK. It is automatically bundled with the package, so it appears in Xcode's Developer Documentation once the dependency is added, and it is also published online via GitHub Pages.

  iOS SDK v4.0.0 size info: 2.8MB

  ### Requirements

  #### IDE

  * Minimum Xcode is now [16.0](https://developer.apple.com/documentation/xcode-release-notes/xcode-16-release-notes). Support for [Xcode 15](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes) has been dropped. See [App Store submission requirements](https://developer.apple.com/app-store/submitting/) for more information.
  * The iOS SDK is now built in the Swift 6 language mode. This does not require your app to adopt the Swift 6 language mode - `Fingerprint` remains compatible with projects using the Swift 5 language mode.

  #### Minimum supported versions

  * [**iOS 14**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-14-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="August 2026">
  ## v2.17.2

  ### What's new

  * Refined signal collection logic on devices located in mainland China, improving App Store review compliance in that region.
  * Optimized signal collection to reduce latency during app launch.

  iOS SDK v2.17.2 size info: 3.1MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="July 2026">
  ## v2.17.1

  ### What's new

  * Added additional signal data to improve the accuracy of Factory Reset detection on iOS 26.6 and iOS 27.

  iOS SDK v2.17.1 size info: 3.1MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)

  ## v2.17.0

  ### What's new

  * Added internal improvements to enhance fraud detection capabilities. These updates lay the groundwork for upcoming backend enhancements.
  * Internal bug fixes.

  iOS SDK v2.17.0 size info: 3.1MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="June 2026">
  ## v2.16.0

  ### What's new

  * Added internal improvements to support enhanced detection logic and upcoming backend updates.
  * Added support for the iOS device memory attribute as part of the [Raw Device Attributes](https://docs.fingerprint.com/docs/smart-signals-reference#raw-device-attributes) smart signal.

  iOS SDK v2.16.0 size info: 3.0MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="May 2026">
  ## v2.15.1

  ### What's new

  * Fixed a crash occurring when the SDK was initialized with a proxy configuration on devices with an A18 Pro chip or newer.
  * Introduced performance optimizations which resulted in reducing the iOS SDK binary size from 4 MB to 2.9 MB - a 27.5% decrease. This reduces the overall size impact on host apps when building for device.
  * Reduced latency.

  iOS SDK v2.15.1 size info: 2.9MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="May 2026">
  ## v2.15.0

  ### What's new

  * Improved [MitM detection](https://docs.fingerprint.com/docs/smart-signals-reference#mitm-attack-detection) reliability on iOS. Certificate chain collection now happens directly from the visitor identification request, eliminating a separate preliminary network request. This resolves false positive MitM detections for users whose network environment (VPNs, corporate proxies) blocked or intercepted the previous preliminary request.
  * Expanded the range of device-level signals collected for deeper device integrity insights.
  * Performance improvements.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="March 2026">
  ## v2.14.0

  ### What's new

  * Expanded signal collection to support upcoming factory reset detection.
  * Improved [jailbroken device detection](https://docs.fingerprint.com/docs/smart-signals-reference#jailbroken-device-detection) and [Frida detection](https://docs.fingerprint.com/docs/smart-signals-reference#frida-detection) logic.
  * Performance improvements and minor bug fixes.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="February 2026">
  ## v2.13.0

  ### What's new

  * Added internal improvements to support enhanced detection logic and upcoming backend updates.
  * Improved data handling logic in virtualized and simulator environments to strengthen privacy and security protections.
  * Improved the underlying logic for [Geolocation spoofing Smart Signal](https://docs.fingerprint.com/docs/smart-signals-reference#geolocation-spoofing-detection)
  * Minor bug fixes.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="December 2025">
  ## v2.12.0

  ### What's new

  * Added internal improvements to enhance fraud detection capabilities.
  * Introduced a new [iOS simulator detection](/docs/smart-signals-reference#ios-simulator-detection) Smart Signal.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="October 2025">
  ## v2.11.0

  ### What's new

  **Recommendation**: We strongly encourage upgrading to the version **2.11.0** to benefit from improved security and stronger protection against tampering and reverse-engineering attempts.

  * Implemented additional security measures to protect iOS SDK requests from manipulation, tampering, and reverse-engineering attempts.
  * Fixed two bugs related to `LocationPermissionHelper`:
    * Resolved an issue with the `locationPermissionHelper(_:shouldShowLocationRationale:)` delegate method being triggered more than once for the same authorization status change, which previously led to duplicate permission dialogs for clients who use `LocationPermissionHelper`.
    * Fixed an issue where calling `LocationPermissionHelper.requestTemporaryPrecisePermission` could cause an infinite loop if an error occurred, such as when the required purpose string for temporary precise location permission was missing from the Info.plist.
  * The total SDK size increased from 1MB to 3.6MB

  Note: Simulators running iOS 15 or lower are no longer supported for testing Fingerprint integrations. If you use simulators to test your Fingerprint integration, please update to iOS 16 or higher.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="September 2025">
  ## v2.10.1

  ### What's new

  * Optimized signal collection to reduce latency during app launch.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)

  ## v2.10.0

  ### What's new

  * Introduced a new proximity detection location-based signal for mobile devices. Instead of representing a unique device, the new proximity ID corresponds to a fixed geographical zone within which the device is observed. This additional layer of context makes it possible to identify groups of devices in the same physical area or a single device that may have changed its identity but remained in the same location. See [Proximity detection for iOS devices](/docs/smart-signals-reference#proximity-detection) reference for more info.
    * Added `allowUseOfLocationData` property to the `Configuration` structure in order to start receiving proximity detection signal. This flag allows the Fingerprint client to access device location data when enabled and the necessary permissions are granted. Default value is `false`. See [using location data for proximity detection](/docs/ios-sdk#using-location-data-for-proximity-detection) for integration details.
    * Added `NSPrivacyCollectedDataTypePreciseLocation` and `NSPrivacyCollectedDataTypeCoarseLocation` to `NSPrivacyCollectedDataTypes` in the iOS SDK’s [Privacy Manifest](/docs/mobile-devices-understanding-privacy-manifest-files#nsprivacycollecteddatatypes), indicating that the SDK may collect both precise and coarse user location data from host apps.
    * Added an optional `LocationPermissionHelper` utility to simplify integration of location permission handling for host apps that do not implement their own flow. This utility provides an easy way to request, observe, and respond to location permission changes using a `LocationPermissionDelegate` callback. See a detailed integration example in the [Handling Location Permissions](/docs/ios-sdk#handling-location-permissions) section.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="August 2025">
  ## v2.9.0

  ### What's new

  * Introduced internal architecture updates and performance improvements to support upcoming capabilities.
  * Added new error code:
    * `ProxyIntegrationSecretEnvironmentMismatch`
  * Addressed minor issues to improve SDK reliability.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="April 2025">
  ## v2.8.2

  ### What's new

  * Introduced the ability to detect if requests from the app were subject to MitM attacks. See [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection) to learn more.
  * Added support for [Open Client Response](/docs/v3/open-client-response).

  ### What's changed

  * The following changes were made to the error handling API. To ensure backward compatibility, the old symbols have been preserved and annotated with the `@available(*, deprecated, renamed: "<new-name>")` attribute.
    * Enum `APIErrorType` has been renamed to `APIError.Code`.
    * Property `APIError.error` has been renamed to `APIError.errorDetails`.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="October 2024">
  ## v2.7.0

  ### What's new

  * Introduced the ability to configure the timeout interval for the client session. To learn more, see [Specifying a custom timeout](/docs/ios-sdk#specifying-a-custom-timeout).
  * Added support for [Sealed Client Results](/docs/ios-sdk#reading-the-response).
  * Extended compatibility for use with projects that have [enabled Swift 6 language mode](https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/featuremigration/).

  ### Bug fixes

  * Fixed a regression introduced in v2.5.0 in which the API errors were incorrectly parsed as `FPJSError.invalidResponseType`. The API errors are now correctly parsed and returned as `FPJSError.apiError`.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="August 2024">
  ## v2.6.0

  ### What’s new

  * Introduced the ability to redirect failed requests to alternate endpoints. The `Region.custom(domain:fallback:)` can be used to specify the `fallback` array of one or more alternate endpoints. For a complete example, see [Getting a visitorId](/docs/ios-sdk#getting-a-visitorid).

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="July 2024">
  ## v2.5.0

  ### What’s new

  * Enhanced our [Jailbroken Device Detection Smart Signal](/docs/smart-signals-reference#jailbroken-device-detection) with the ability to detect rootless jailbreaks.
  * [Factory Reset Smart Signal](/docs/smart-signals-reference#factory-reset-detection) is no longer reported as true for brand-new iOS devices.
  * In accordance with [Apple's third-party SDK requirements](https://developer.apple.com/support/third-party-SDK-requirements/), the XCFramework bundle is now code signed with an Apple Distribution certificate. The dependency signature verification feature, introduced in Xcode 15, allows the XCFramework's code signing identity to be verified, thus enabling SDK consumers to protect their software supply chain integrity.

  ### What's changed

  * Dropped support for Swift 5.7 and 5.8.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="January 2024">
  ## v2.4.0

  ### What's new

  * Introduced a new `packageNotAuthorized` value to the `APIErrorType` enum. This error is thrown when an unauthorized app makes identification requests using a stolen API key. See [Request filtering for mobile apps](/docs/mobile-app-filtering) for more information.
  * Extended several public APIs (e.g. `FingerprintResponse`, `IPLocation`, etc) with memberwise initializers so that they can be easily stubbed for unit tests.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="December 2023">
  ## v2.3.2

  ### What's new

  * Added `PrivacyInfo.xcprivacy`, the privacy manifest file. See [Understanding privacy manifest files](/docs/mobile-devices-understanding-privacy-manifest-files) for more information.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="October 2023">
  ## v2.3.1

  ### What's new

  * Introduced the ability to detect [Geolocation Spoofing](/docs/smart-signals-reference#geolocation-spoofing-detection).

  ### What's changed

  * Removed the limitation in which the Smart Signals could not be made available in the response of the very first [`/events API`](/reference/server-api-get-event) request.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)

  ## v2.3.0

  ### What's new

  * Introduced the ability to detect if a device is using a VPN. See [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices) for more information.
  * Introduced a new Smart Signal, [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection) that provides the timestamp of the most recent factory reset of the device.
  * Added support for Swift 5.9 and Xcode 15.

  ### What's changed

  * Dropped support for iOS 12, tvOS 12, tvOS 13, and tvOS 14.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="June 2023">
  ## v2.2.0

  ### What's new

  * Introduced the ability to detect
    * If Frida is being used to instrument your app. See [Frida Detection](/docs/smart-signals-reference#frida-detection) for more information.
    * If your app is running on a jailbroken device. See [Jailbroken Device Detection](/docs/smart-signals-reference#jailbroken-device-detection) for more information.
  * Introduced a new field, `visitorFound` in `FingerprintResponse`. This field indicates if a device was already seen by your mobile app.

  ### What's changed

  * Dropped support for Swift 5.5 and Swift 5.6.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 12](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-12-release-notes)
  * [tvOS 12](https://developer.apple.com/documentation/tvos-release-notes/tvos-12-release-notes)
</Update>


# JavaScript agent
Source: https://docs.fingerprint.com/docs/changelog-javascript-agent

This changelog lists all additions and updates to the Fingerprint documentation, in chronological order.

<Update label="September 2026">
  ## v4.1.5

  * Add [`tags`](/reference/js-agent-get-function#tags) to replace deprecated [`tag`](/reference/js-agent-get-function#tag-deprecated)
  * Improve stability and security

  ## v3.12.15

  * Improve stability and security
</Update>

<Update label="July 2026">
  ## v4.1.4

  * Minor bug fixes, stability, and security improvements

  ## v4.1.3

  * Minor bug fixes, stability, and security improvements

  ## v4.1.2

  * Minor bug fixes, stability, and security improvements

  ## v3.12.14

  * Minor bug fixes, stability, and security improvements

  ## v3.12.13

  * Minor bug fixes, stability, and security improvements

  ## v3.12.12

  * Minor bug fixes, stability, and security improvements
</Update>

<Update label="June 2026">
  ## v4.1.1

  * Minor bug fixes, stability, and security improvements

  ## v4.1.0

  * Minor bug fixes, stability, and security improvements
  * Added new methods to [BinaryOutput](https://docs.fingerprint.com/reference/js-agent-get-function#sealed_result): `toJSON`, `toString`, and `[Symbol.toPrimitive]`. These return a base64 representation of the binary data:
    ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
    const result = await agent.get();
    console.log(result.sealed_result.toString()); // <<< will log the base64 string now, instead of `[object Object]`
    ```

  ## v3.12.11

  * Minor bug fixes, stability, and security improvements

  ## v3.12.10

  * Minor bug fixes, stability, and security improvements
</Update>

<Update label="March 2026">
  ## v4.0.3

  * Minor bug fixes, stability, and security improvements

  ## v4.0.2

  * Minor bug fixes, stability, and security improvements

  ## v3.12.9

  * Minor bug fixes, stability, and security improvements

  ## v3.12.8

  * Minor bug fixes, stability, and security improvements
</Update>

<Update label="February 2026">
  ## v4.0.1

  * Minor bug fixes, stability, and security improvements

  ## v3.12.7

  * Improve Identification accuracy
</Update>

<Update label="January 2026">
  ## v4.0.0

  * New major API version has been released. This version contains a major overhaul of the API surface, configuration options, and introduces breaking changes. See the [full migration guide](/reference/migrating-from-v3-to-v4) for all the details to start the transition to this new version.
  * The deprecation period for JavaScript agent version 3 begins once all server, client, and proxy integrations get released. The deprecation period is **12 months** from that date, following our [API deprecation policy](/reference/api-deprecation-policy).

  ## v3.12.6

  * Improve Identification and Smart Signal accuracy
</Update>

<Update label="December 2025">
  ## v3.12.5

  * Minor bug fixes, stability and security improvements
</Update>

<Update label="November 2025">
  ## v3.12.4

  * Improve Identification accuracy in Safari 26
  * Drop support for older browsers and updated our [list of supported browsers](/docs/browser-and-device-support)
</Update>

<Update label="October 2025">
  ## v3.12.3

  * Improve Smart Signals accuracy
</Update>

<Update label="September 2025">
  ## v3.12.2

  * Add a check for `SecurityError` in all affected signals

  ## v3.12.1

  * Improve Smart Signals accuracy
</Update>

<Update label="August 2025">
  ## v3.12.0

  * Move to ES2018 JavaScript language version target.
  * Decrease overall latency and bundle size

  ## v3.11.14

  * Improve identification accuracy
  * Improve performance (minor improvement)
</Update>

<Update label="July 2025">
  ## v3.11.13

  * Improve accuracy of [Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection) Smart Signal
  * Optimize latency
  * Introduce `FingerprintJS.ERROR_PROXY_INTEGRATION_SECRET_ENVIRONMENT_MISMATCH`, returned when the proxy secret belongs to a different environment than the Public API key (but same workspace)

  ## v3.11.12

  * Improve performance (signal collection latency)

  ## v3.11.11

  * Optimize agent size
  * Remove unused signals to decrease latency
</Update>

<Update label="May 2025">
  ## v3.11.10

  * Improve general performance by decreasing the total bundle size
  * Improve signal collection performance in Safari
  * Improve Smart Signals accuracy
  * ImproveIdentification accuracy in Firefox
</Update>

<Update label="April 2025">
  ## v3.11.9

  * Add specific behavior for [AI bot request filtering](/docs/ai-bot-filtering)
</Update>

<Update label="February 2025">
  ## v3.11.8

  * Signal accuracy improvements
</Update>

<Update label="January 2025">
  ## v3.11.7

  * Introduce [more granular errors](/docs/changelog-javascript-agent#more-granular-errors) for proxy integration failures and request filtering
  * Increase [Smart Signals accuracy](/docs/changelog-javascript-agent#smart-signals-accuracy)

  ### More granular errors

  Introduce more granular [error constants](/reference/v3/js-agent-error-handling#errors) for [network request filtering](/docs/network-request-filtering) and [proxy integration](/docs/protecting-the-javascript-agent-from-adblockers) failures:

  * `FingerprintJS.ERROR_NETWORK_RESTRICTED`, triggered when a request is filtered out based on an IP address or IP address range
  * `FingerprintJS.ERROR_INVALID_PROXY_INTEGRATION_SECRET`, occurs when the `Fpjs-Proxy-Secret` header contains an empty, invalid, or non-matching value
  * `FingerprintJS.ERROR_INVALID_PROXY_INTEGRATION_HEADERS`, triggered when the proxy integration headers are misconfigured or partially provided in those specific cases:
    * Missing required headers (`Fpjs-Proxy-Client-IP`, `Fpjs-Proxy-Forwarded-Host`).
    * Duplicate headers
    * Invalid patterns for `Client-IP` or `Forwarded-Host`

  ### Smart Signals accuracy

  Significantly improve the accuracy of the [Virtual Machine Detection](/docs/smart-signals-reference#virtual-machine-detection) Smart Signal.

  ## v3.11.6

  * Minor bug fixes and improvements
</Update>

<Update label="December 2024">
  ## v3.11.5

  * Minor bug fixes and improvements impacting signal collection
</Update>

<Update label="November 2024">
  ## v3.11.4

  * Minor bug fixes and stability improvements
</Update>

<Update label="October 2024">
  ## v3.11.3

  * Drop official support for older browsers (older versions should still work but it is not guaranteed). Updated list is available in the [browser and device support documentation](/docs/browser-and-device-support).
  * JavaScript agent now throws the error from the first attempt instead of the one from the last retry. This makes it more clear what the error was because our retry/fallback endpoints are prone to get blocked by ad blockers.

  ## v3.11.2

  * Minor bug fixes and stability improvements
</Update>

<Update label="September 2024">
  ## v3.11.1

  * Improve the identification accuracy in some Android browsers
  * Improve the accuracy of [Smart Signals](/docs/smart-signals-reference)
</Update>

<Update label="August 2024">
  ## v3.11.0

  * Minor bug fixes in signal collection
  * Improve back/forward cache support to prevent full page reloads
  * Add [`urlHashing option`](/reference/v3/js-agent-load-function#urlhashing)
</Update>

<Update label="July 2024">
  ## v3.10.1

  * Improved accuracy of identification
  * Improved performance

  ## v3.10.0

  * A new JavaScript agent option: `remoteControlDetection` (has been deprecated since)
  * Fix incompatibility with some iOS versions
  * Remove the `Feature policy 'Payment' check failed...` console error in cross-origin iframes in Safari

  ## v3.9.10

  * Improved performance.
  * Improved accuracy of identification.
</Update>

<Update label="June 2024">
  ## v3.9.9

  * Improve the performance

  ## v3.9.8

  * fix: A message related to `AudioContext` is printed to the browser console
  * Improve the performance

  ## v3.9.7

  * Improve the identification and bot detection accuracy
  * Improve the performance
</Update>

<Update label="May 2024">
  ## v3.9.6

  * Improve the performance

  ## v3.9.5

  * Minor improvements
</Update>

<Update label="April 2024">
  ## v3.9.4

  * Improve the Smart Signals accuracy
  * The [ipLocation](/reference/v3/js-agent-get-function#iplocation) response field is marked as deprecated. It will not return a result for **applications created after January 23rd, 2024**. See [IP Geolocation](/docs/smart-signals-reference#ip-geolocation) for a replacement available in our Smart Signals product.

  ## v3.9.3

  * Deprecate option [products](/reference/v3/js-agent-get-function#products). The option to configure products became obsolete with the introduction of Smart Signals. Billed amount is determined by the billing plan and the products option does not influence it. Just remove it from your [JavaScript agent configuration](/reference/v3/js-agent-get-function). It will likely be removed in the next major version.
  * Fix unexpected popup appearing in Android Chrome in rare cases.
</Update>

<Update label="March 2024">
  ## v3.9.2

  * Fixed an unhandled promise rejection happening in rare cases

  ## v3.9.1

  * Minor improvements
</Update>

<Update label="January 2024">
  ## v3.9.0

  * [Sealed Client Results](/docs/sealed-client-results) support. Namely, added a new `get()` response field: [`sealedResult`](/reference/v3/js-agent-get-function#sealedresult).

  ## v3.8.7

  * Improve the [retry](/reference/v3/js-agent-load-function#scripturlpattern) algorithm used in case JavaScript agent fails to load from the CDN.
</Update>

<Update label="October 2023">
  ## v3.8.6

  * Deprecate options [`tlsEndpoint`](/reference/v3/js-agent-load-function#tlsendpoint-deprecated) and [`disableTls`](/reference/v3/js-agent-load-function#disabletls-deprecated). They are not necessary because of recent improvements to the ad blocker protection. Just remove them from your [JavaScript agent configuration](/reference/v3/js-agent-load-function). They will likely be removed in the next major version.
</Update>

<Update label="July 2023">
  ## v3.8.5

  * Minor improvements
</Update>

<Update label="June 2023">
  ## v3.8.4

  * Fix the [`subdivisions`](/reference/v3/js-agent-get-function#iplocation) field type in the TypeScript declarations
</Update>

<Update label="April 2023">
  ## v3.8.3

  * Add an [error constant](/reference/v3/js-agent-error-handling) `ERROR_INVALID_ENDPOINT` which is used then the `endpoint` option value is not a valid URL
</Update>

<Update label="February 2023">
  ## v3.8.2

  * Add a license file to the NPM package
</Update>

<Update label="November 2022">
  ## v3.8.1

  * Add an [error constant](/reference/v3/js-agent-error-handling) `ERROR_INTEGRATION_FAILURE` which will be used for errors that happen on the [integration](/docs/protecting-the-javascript-agent-from-adblockers) side

  ## v3.8.0

  * Fallback endpoint. You can set multiple endpoints; JavaScript agent will try to send the request with the first endpoint, and if the request fails, retry the request with the second endpoint and so on. Supported by all options: [scriptUrlPattern](/reference/v3/js-agent-load-function#scripturlpattern), [endpoint](/reference/v3/js-agent-load-function#endpoint) and [tlsEndpoint](/reference/v3/js-agent-load-function#tlsendpoint-deprecated).
  * Placeholder values for cases where you want to use the default endpoint as a fallback endpoint: - `FingerprintJS.defaultScriptUrlPattern` for [scriptUrlPattern](/reference/v3/js-agent-load-function#scripturlpattern) - `FingerprintJS.defaultEndpoint` for [endpoint](/reference/v3/js-agent-load-function#endpoint) - `FingerprintJS.defaultTlsEndpoint` for [tlsEndpoint](/reference/v3/js-agent-load-function#tlsendpoint-deprecated)
</Update>

<Update label="August 2022">
  ## v3.7.1

  * A new [error is thrown](/reference/v3/js-agent-error-handling) when JavaScript agent is blocked by [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP): `FingerprintJS.ERROR_CSP_BLOCK`. JavaScript agent doesn't retry network requests blocked by CSP. In previous versions a common error was thrown in this case: `FingerprintJS.ERROR_NETWORK_CONNECTION`.
</Update>

<Update label="July 2022">
  ## v3.7.0

  * [Bot Detection agent](https://fingerprint.com/products/bot-detection/) is embedded into FingerprintJS Pro agent
  * A new `fp.get()` option [products](/reference/v3/js-agent-get-function#products) to enable or disable Fingerprint products (Browser Identification, BotDetection)

  ## v3.6.4

  * Security improvements
</Update>

<Update label="May 2022">
  ## v3.6.3

  * Add the [`zeroTrust`](/docs/zero-trust-mode) field to the TypeScript declaration of JavaScript agent result object

  ## v3.6.2

  * New error type: `ERROR_FORBIDDEN_ENDPOINT`. See the [error handling guide](/reference/v3/js-agent-error-handling) for more details.
</Update>

<Update label="April 2022">
  ## v3.6.1

  * fix: JavaScript agent installed from jsDelivr makes a network request to fpnpmcdn.io that can be blocked by your Content Security Policy. This is a temporary fix, it will be reverted. Please [switch to our CDN](/docs/migrating-from-fingerprintjs-to-fingerprint-pro#cdn-installation) to avoid this problem in future.
</Update>

<Update label="March 2022">
  ## v3.6.0

  * A new CDN for the CDN installation methods. Follow [this guide](/docs/migrating-from-fingerprintjs-to-fingerprint-pro#cdn-installation) to update. The old CDN URLs pointing to jsDelivr continue working, but we recommend switching to our CDN to avoid excess network requests.
  * JavaScript agent installed from NPM loads its code from our CDN in runtime. It guarantees that you always use the latest and the most accurate version of JavaScript agent.
    * If you use a Content Security Policy, add the CDN domain to the CSP as described in the [JavaScript agent CSP documentation](/docs/js-agent-csp) (see the "NPM installation" tab).
    * If you do an HTML preconnect, consider preconnecting to the CDN too as described in the [API preconnect documentation](/docs/optimize-javascript-agent#pre-connect-to-fingerprint-urls) (see the "NPM installation" tab).
  * Add `firstSeenAt` and `lastSeenAt` fields to JavaScript agent responses. See more details in [Visitor Footprint Timestamps](/docs/useful-timestamps).
  * New error types: ERROR\_SCRIPT\_LOAD\_FAIL and ERROR\_INSTALLATION\_METHOD\_RESTRICTED. See the [error handling guide](/reference/v3/js-agent-error-handling) for more details.
  * A new `load()` option in the NPM package of JavaScript agent: [`scriptUrlPattern`](/reference/v3/js-agent-load-function#scripturlpattern). See more details in the [JavaScript agent guide](/reference/v3/js-agent-load-function#scripturlpattern).

  ## v3.5.7

  * fix: If your project uses TypeScript and has the TypeScript's [isolatedModules](https://www.typescriptlang.org/tsconfig#isolatedModules) option is enabled, JavaScript agent causes an error: "TS2748: Cannot access ambient const enums"

  ## v3.5.6

  * Rename the token option of the `load` method of JavaScript agent to `apiKey`. The token option keeps working for backward compatibility. Also rename some error constants (the old names work too):
    * `ERROR_TOKEN_MISSING` → `ERROR_API_KEY_MISSING`
    * `ERROR_TOKEN_INVALID` → `ERROR_API_KEY_INVALID`
    * `ERROR_TOKEN_EXPIRED` → `ERROR_API_KEY_EXPIRED`
  * fix: JavaScript agent triggers a console error message unless the page's Content Security Policy allows `unsafe-inline` for `style-src`.
</Update>

<Update label="January 2022">
  ## v3.5.5

  * A new region: `ap` (Mumbai, India)
</Update>

<Update label="December 2021">
  ## v3.5.4

  * Improve incognito mode detection accuracy in Safari
  * Deprecate the `ipResolution` parameter because it affects nothing
  * The `get()` result's `ipLocation` field is marked is optional in the TypeScript declaration. The field could be undefined in fact, so this is a fix of the type declaration.
  * Actualize the [list of supported browsers](/docs/browser-and-device-support).
  * A new [error code](/reference/v3/js-agent-error-handling) for cases when the JavaScript agent version is not supported: `FingerprintJS.ERROR_UNSUPPORTED_VERSION`
  * Decrease the JavaScript agent code size by removing legacy parts
  * fix: An indefinite `setTimeout` loop in Firefox
</Update>

<Update label="September 2021">
  ## v3.5.3

  * Improve the tree-shaking capability
  * Confidence score calculations moved to server for increased accuracy (Pro version)

  ## v3.5.2

  * Improve the performance slightly
</Update>

<Update label="August 2021">
  ## v3.5.1

  * Improve identification time for visitors who use an ad blocker or an M1 Mac
  * Improve identification accuracy
</Update>

<Update label="July 2021">
  ## v3.5.0

  * Add a new result field: confidence score. The confidence score field tells how much the agent is sure about the visitor identifier. See [the API reference](/reference/v3/js-agent-get-function#confidence) for more details.
  * Fix an error that occurs in Firefox Add-ons
</Update>

<Update label="June 2021">
  ## v3.4.0

  * Makes `get` run much faster when some time passes between calling `load()` and `get()`. See the [JavaScript agent preloading guide](/docs/optimize-javascript-agent#preload-the-javascript-agent) to learn how to leverage it.
  * Added an error constant for bad server response format: `FingerprintJS.ERROR_BAD_RESPONSE_FORMAT`. The error can be caused by wrong endpoint.
  * The `disableTls` option is moved from the get options to the load options. It still works when set within get options for compatibility, but doesn't actually disable the TLS request. So we recommend updating your code if you use `disableTls`.
  * fix: JavaScript agent may never complete getting the visitor identifier when the page is in background.

  ## v3.3.3

  * Fix client timeouts in WeChat built-in browser on iOS 13
  * Increase the accuracy of agent when the page runs in background
</Update>

<Update label="May 2021">
  ## v3.3.2

  * Fix "Client timeout" errors that happen in bots that run `setTimeout` too quickly
  * Fix console WebGL warnings in IE 11
</Update>

<Update label="April 2021">
  ## v3.3.1

  * Incognito detection accuracy improvement
  * TypeScript compatibility improvement
  * Fix an error in Android 5.1 Browser: Failed to parse the response
  * Fix client timeouts in iOS WeChat built-in browser

  ## v3.3.0

  * Many new identification methods under the hood
  * JavaScript agent retries visitor identification request in case of error
  * A new billing model. Identifications are billed per a unique visitor instead of a request.
  * New [expected JavaScript agent errors](/reference/v3/js-agent-error-handling): `FingerprintJS.ERROR_WRONG_REGION`, `FingerprintJS.ERROR_SUBSCRIPTION_NOT_FOUND`.

  ## v3.2.6

  * fix: Remote monitoring doesn't work in Android Browser 4.1
  * fix: JavaScript agent script encoding can change the canvas fingerprint, that can reduce accuracy in rare cases
  * Add internal request encryption
  * Improve the fingerprinting performance

  ## v2.8.5

  * Fix incognito detection in some browsers based on Blink
  * Decrease the chance of getting `send()` call timeout by decreasing the TLS request timeout
  * Improve the fingerprinting performance
</Update>

<Update label="February 2021">
  ## v3.2.5

  * Increase the TLS request stability by retrying
  * Decrease the chance of getting `get()` call timeout by decreasing the TLS request timeout
  * fix: Monitoring reports aren't sent sometimes

  ## v3.2.4

  * Improve the accuracy of Chrome incognito detection
  * Add the `requestId` field to errors emitted by the servers
  * Make JavaScript agent [easier to use](https://github.com/fingerprintjs/fingerprintjs/pull/610) in server side rendering environments like Next.js and Gatsby

  ## v2.8.4

  * Fix cookie `SameSite` attribute warnings in Firefox
  * Increase the accuracy of Chrome incognito detection
  * Add the `requestId` field to errors emitted by the servers
</Update>

<Update label="January 2021">
  ## v3.2.3

  * Add [JavaScript agent constants](/reference/v3/js-agent-error-handling) for the new [request filtering](/docs/request-filtering) errors
  * Fix cookie `SameSite` attribute warnings in Firefox
  * Improve the identification mechanism
</Update>

<Update label="December 2020">
  ## v3.2.2

  * fix: `load()` takes a huge time to run in some conditions
  * Handle cases where `navigator.deviceMemory` is a string

  ## v3.2.1

  * Add more information to JavaScript agent monitoring

  ## v3.2.0

  * Add an experimental API for JavaScript agent debugging. We can use it to analyze agent operation on your side and solve problems faster. [Contact support](mailto:support@fingerprintjs.com) for more details.
  * The minimal supported version of TypeScript is 4.0.0.
  * Amend Safari private mode detection. It always detected `incognito: true` in desktop Safari controlled by Karma or BrowserStack Automate.

  ## v2.8.3

  * fix: `FP.load()` takes a huge time to run in some conditions
  * Handle cases where `navigator.deviceMemory` is a string
</Update>

<Update label="November 2020">
  ## v3.1.0

  * Increased stability of the audio fingerprint component on iPhone
  * Made JavaScript agent use a TLS server located in Europe when the region is set to EU, for example:
    ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
    FingerprintJS.load({
      token: "your-token",
      region: "eu",
    });
    ```
  * Added an option to set a custom TLS endpoint:
    ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
    FingerprintJS.load({
        token: 'your-token',
        tlsEndpoint: 'https://mytls.example.com'
    })
    ```

  ## v3.0.3

  * fix: Incognito detection doesn't work in mobile Safari 13 and newer

  ## v3.0.2

  * fix: It's impossible to set an endpoint that is relative to the current domain in the `FingerprintJS.load()` function. For example, the following code didn't work:
    ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
    const fp = await FingerprintJS.load({ token: 'your-token', endpoint: '/metrics' })
    const result = await fp.get()
    ```
    Warning. If you set the endpoint option to something like `metrics.example.com`, it will break because this is not an expected behavior. Change the endpoint to `https://metrics.example.com`.

  ## v2.8.2

  * Amend Safari private mode detection. It always detected `incognito: true` in desktop Safari controlled by Karma or BrowserStack Automate.

  ## v2.8.0

  * Increased stability of the audio fingerprint component on iPhone
  * Made JavaScript agent use a TLS server located in Europe when the region is set to EU, for example:

    <CodeGroup>
      ```javascript NPM installation theme={"theme":"github-dark-dimmed"}
      import { FP } from "@fp-pro/client";
      FP.load({
        client: "your-token",
        region: "eu",
      });
      ```

      ```html CDN installation theme={"theme":"github-dark-dimmed"}
      <head>
        <script>
          window.fpLayer = window.fpLayer || [];
          function fp() {
            fpLayer.push(arguments);
          }
          fp("config", "client", "your-token");
          fp("config", "region", "eu");
        </script>
        <script async src="https://cdn.fpjs.io/@2/fp.js"></script>
      </head>
      ```
    </CodeGroup>
  * Added an option to set a custom TLS endpoint:

    <CodeGroup>
      ```javascript NPM installation theme={"theme":"github-dark-dimmed"}
      import { FP } from '@fp-pro/client';
      FP.load({
          client: 'your-token',
          tlsEndpoint: 'https://mytls.example.com'
      })
      ```

      ```html CDN installation theme={"theme":"github-dark-dimmed"}
      <head>
          <script>
          window.fpLayer = window.fpLayer || [];
          function fp() { fpLayer.push(arguments); }
          fp('config', 'client', 'your-token');
          fp('config', 'tlsEndpoint', 'https://mytls.example.com');
          </script>
          <script async src="https://cdn.fpjs.io/@2/fp.js"></script>
      </head>
      ```
    </CodeGroup>
</Update>

<Update label="October 2020">
  ## v3.0.1

  * Unexpected entropy component errors are printed in the [debug mode](/reference/js-agent-error-handling#handling-errors) of the JavaScript agent. Such errors should be reported to us.
  * Support elder browsers like IE 11, Chrome 42 and Firefox 48 (a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) polyfill is required)
  * Handle cases where `new Date().getTimezoneOffset()` returns a string
  * fix: Getting the visitor identifier takes a huge time in some conditions

  ## v3.0.0

  * The JavaScript agent API is changed to provide a simple transition from the [open-source version of the agent](https://github.com/fingerprintjs/fingerprintjs).
  * The installation methods have been unified so that they have same options and same usage methods. Also we've added a couple new ways to install.
  * Result and error handling has been simplified. A single value type is returned (resolved) and a single value type is thrown (rejected). The agent throws error only when a visitor identification fails due to incorrect agent setup or network issues; special kinds of visitors don't cause errors.

  Learn how to migrate:

  * [From FingerprintJS Pro version 2](/docs/migrating-from-fingerprintjs-to-fingerprint-pro)
  * [From FingerprintJS Open-Source version 3](/docs/migrating-from-fingerprintjs-to-fingerprint-pro#migrating-from-fingerprintjs-v3-open-source-to-fingerprint-identification)
  * [From FingerprintJS Open-Source version 2](/docs/migrating-from-open-source-v2)

  ## v2.7.7

  * fix: An error that occurs in a very rare case when `navigator.permissions` is present while `window.Notification` isn't.
  * Handle cases where `new Date().getTimezoneOffset()` returns a string
  * fix: Visitor identifier can change due to a daylight saving time shift
</Update>


# MCP server
Source: https://docs.fingerprint.com/docs/changelog-mcp-server

This changelog lists all additions and updates to the Fingerprint MCP server, in chronological order.

<Update label="August 2026">
  ## Available in the Anthropic connectors directory

  Fingerprint is now listed in the Anthropic connectors directory. In Claude, go to **Settings** > **Connectors**, click **Browse**, and search for `Fingerprint`. You no longer need to add a custom connector or enter the server URL.

  Adding Fingerprint as a custom connector still works, and remains the setup path for Claude Code, Cursor, VS Code, and other MCP clients. See the [MCP server guide](/docs/mcp-server).
</Update>

<Update label="August 2026">
  ## Tool list stays current without reconnecting

  Added three tools that keep newly released tools reachable without disconnecting and reconnecting your AI client:

  * `list_tools` reports the tools the server is currently serving.
  * `call_tool` runs any tool that `list_tools` reports.
  * `call_write_tool` runs write actions through a separate proxy with its own approval prompt.

  Some AI clients cache the tool list for a conversation, so tools added in a release did not appear until you reconnected or started a new conversation. These three tools stay constant, so once they are in your tool list, future tools stay reachable through them.

  After this update, start one new conversation for the three tools to appear. From then on, your tool list stays current.
</Update>

<Update label="July 2026">
  ## New `get_current_time` tool

  Added a `get_current_time` tool that returns the current time as a UTC RFC3339 timestamp and Unix epoch. Pass an optional IANA time zone (such as `America/New_York`) to also get the local time in that zone.

  This gives AI clients a reliable clock when building relative time ranges for `search_events`, instead of inferring the date from their training data.
</Update>

<Update label="June 2026">
  ## Bot detection filters for `search_events`

  Added bot detection filters to `search_events`: `bot_info`, `bot_info_category`, `bot_info_identity`, `bot_info_confidence`, `bot_info_provider`, and `bot_info_name`. You can now have your AI client search identification events by bot activity, confidence, and provider.
</Update>

<Update label="May 2026">
  ## Human-readable timestamps for `search_events`

  The `start` and `end` parameters on `search_events` now use human-readable RFC3339 timestamps instead of Unix milliseconds. This helps AI clients build correct time ranges and avoid querying dates outside the supported 90-day window.
</Update>

<Update label="March 2026">
  ## Fingerprint MCP server is now available

  Connect AI assistants and agents to Fingerprint device intelligence with the new [Fingerprint MCP server](/docs/mcp-server). Your AI tools can query identification events, detect anomalies, investigate fraud patterns, and manage your Fingerprint workspace through natural language.

  The server is available in two forms:

  * **Managed service**: Hosted by Fingerprint at `https://mcp.fpjs.io/mcp`, with no setup or maintenance required.
  * **Open source**: Self-host from the [GitHub repository](https://github.com/fingerprintjs/fingerprint-mcp-server) for full control over deployment.

  See the [MCP server guide](/docs/mcp-server) to get started.
</Update>


# Smart Signals
Source: https://docs.fingerprint.com/docs/changelog-smart-signals

This changelog lists all additions and updates to the Fingerprint Smart Signals documentation, in chronological order.

<Update label="September 2026">
  ## Factory Reset Detection — Android improvements

  Improved factory reset detection accuracy for Samsung (series A, S) and Xiaomi devices, where filesystem behavior specific to these manufacturers was previously causing some devices to be misclassified as factory reset.

  * New logic is available in [Android SDK 2.10.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#v2-10-0)
</Update>

<Update label="April 2026">
  ## Suspect Score Recommendations — New Smart Signals Capability ML-based

  Allows you to upload labeled fraud data and receive optimized signal weights tailored to your traffic. You can review, accept, or reject recommendations in the dashboard. Check the [Suspect Score](https://docs.fingerprint.com/docs/suspect-score) page for more details.
</Update>

<Update label="August 2026">
  ## Raw Device Attributes - New Web Attributes

  Expanded the `raw_device_attributes` Smart Signal with new web attributes: `battery_level`, `battery_charging`, `keyboard_layout_name`, `keyboard_layout_hash`, `font_hash`, and `timezone_offset`.

  * `keyboard_layout_name`, `keyboard_layout_hash`, `font_hash`, `battery_level`, and `battery_charging` are only available in Chrome and other Chromium-based browsers.
  * Available to Enterprise plan customers.

  See the [full list of supported attributes](https://docs.fingerprint.com/docs/smart-signals-reference#raw-device-attributes) for details.
</Update>

<Update label="August 2026">
  ## Active Call Detection - Available for iOS and Android

  Introduced a new mobile Smart Signal that detects whether the user's device has an active cellular or internet (VoIP) call in progress. See [Smart Signals reference](/docs/smart-signals-reference#active-call-detection) for additional details.

  * Requires [iOS SDK 2.16.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#june-2026) and [Android SDK 2.16.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#june-2026).
  * Supported via [API v4](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) responses.
</Update>

<Update label="July 2026">
  ## **Device Rarity Detection - New Browser Smart Signal**

  Introduced a new Smart Signal that identifies devices whose combination of core attributes is statistically uncommon or previously unseen across global traffic.

  * Requires JavaScript Agent version 3.8.10 or higher.
</Update>

<Update label="June 2026">
  ## **ML-Based VPN, Proxy & Virtual Machine Detection**

  Strengthened the detection of VPNs, proxies, and virtual machines using machine learning-based models.

  * Requires JavaScript Agent version 3.12.9 or higher.
</Update>

<Update label="June 2026">
  ## Rooted Device Detection - Android Improvements

  Strengthened the detection logic for identifying rooted Android devices.

  * New logic is available in [Android SDK v2.15.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#april-2026).
</Update>

<Update label="May 2026">
  ## Proximity Detection - Available on Web

  Proximity detection is now available on web. The proximity ID represents a fixed geographical zone rather than a unique device, it is useful for detecting device clusters in the same area or a device that changed identity but not location. See the [Proximity detection reference](/docs/smart-signals-reference#proximity-detection).

  * Requires JavaScript Agent version 3.12.9 or higher.
</Update>

<Update label="May 2026">
  ## Developer Tools Detection - Available for iOS and Android

  Detect whether developer tools are active on a mobile device via the [Developer Tools Detection](https://docs.fingerprint.com/docs/smart-signals-reference#developer-tools-detection-for-mobile-devices) smart signal.

  * Helps identify environments where developer tools are active, which may indicate reverse engineering, dynamic instrumentation, or automated abuse when combined with other signals.
  * Requires [iOS SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#december-2025) and [Android SDK 2.6.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#v2-6-0).
  * Supported via [API v4](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) and API v3 responses.
</Update>

<Update label="May 2026">
  ## Raw Device Attributes Now Available on Mobile

  The following Raw Device Attributes are now collected by native mobile SDKs:

  * Android: screen resolution, device memory, languages, battery level, low power mode
  * iOS: screen resolution, device memory, languages, battery level, low power mode

    Notes:

    * Requires [iOS SDK 2.15.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#may-2026-2) and [Android SDK 2.15.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#april-2026).
    * Supported via [API v4](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) responses.
    * The device memory attribute on iOS is available starting in [iOS SDK 2.16.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#june-2026)

    See the [full list of supported attributes](https://docs.fingerprint.com/docs/smart-signals-reference#raw-device-attributes) for details.
</Update>

<Update label="May 2026">
  ## Frida detection — iOS improvements

  Improved the detection mechanism for active Frida connections in the [iOS SDK v2.14.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#march-2026).
</Update>

<Update label="April 2026">
  ## Suspect Score Recommendations — New Smart Signals Capability ML-based

  Allows you to upload labeled fraud data and receive optimized signal weights tailored to your traffic. You can review, accept, or reject recommendations in the dashboard. Check the [Suspect Score](https://docs.fingerprint.com/docs/suspect-score) page for more details.
</Update>

<Update label="March 2026">
  ## iOS Simulator Detection — New Mobile Smart Signal

  Detect whether your app is running on an [iOS simulator](https://docs.fingerprint.com/docs/smart-signals-reference#ios-simulator-detection) instead of a physical device.

  * Helps detecting whether your app is running on an iOS simulator rather than a physical device.
  * Requires [iOS SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#december-2025).
  * Supported via [API v4](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) responses.
</Update>

<Update label="March 2026">
  ## Geolocation Spoofing Detection — iOS Improvements

  Improved accuracy in detecting mocked locations on iOS devices.

  * Requires geolocation permissions
  * Available in [iOS SDK 2.13.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#february-2026).
</Update>

<Update label="March 2026">
  ## ML-based Anti-Detect Browser Detection — Tampering Signal Enhancement

  Introduced an ML-based layer for [Anti-Detect Browser detection](https://docs.fingerprint.com/docs/smart-signals-reference#anti_detect_browser), improving coverage and accuracy. Added `tampering_confidence` and `tampering_score` fields to the response.

  * Supported across API v3 and v4.
</Update>

<Update label="January 2026">
  ## Detecting real location — iOS VPN detection improvements

  [Origin country field](https://docs.fingerprint.com/docs/smart-signals-reference#vpn_origin_country-2) on iOS has been enhanced to infer a user's true country even without location permissions, helping teams go beyond broad VPN-based risk assumptions and focus on genuine location mismatches. Check out the full [*product updates article*](https://fingerprint.com/blog/q1-2026-product-roundup/#real-location-detection-mobile-see-past-vpns-to-reveal-true-device-origin) for more details.

  * Doesn't require geolocation permission
  * New logic is available in [iOS SDK 2.9.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#august-2025).
</Update>

<Update label="January 2026">
  ## Proxy Provider Name — Proxy Signal Enhancement

  Added proxy provider name to API responses for improved transparency.

  * Supported across API v3 and v4.
</Update>

<Update label="January 2026">
  ## Raw Device Attributes

  Introduced a curated set of stable and reliable [device and browser attributes](https://docs.fingerprint.com/docs/smart-signals-reference#raw-device-attributes).

  * Supported on API v4.
</Update>

<Update label="December 2025">
  ## Organization name and type fields — IP Geolocation Signal Enhancement

  Added `organization name` and `type` fields to the [IP Geolocation signal](https://docs.fingerprint.com/docs/smart-signals-reference#ip-geolocation). Improved network-level insights.

  * Supported across API v3 and v4.
</Update>

<Update label="December 2025">
  ## Cloned App Detection — Android Improvements

  Strengthened [cloned app detection](https://docs.fingerprint.com/docs/smart-signals-reference#cloned-app-detection) on Android through improvements to the core detection logic.

  * New logic is available in [Android SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#december-2025).
</Update>

<Update label="October 2025">
  ## Rooted Device Detection — Android Improvements

  Refined the underlying detection algorithm for identifying [rooted devices](https://docs.fingerprint.com/docs/smart-signals-reference#rooted-device-detection) and [emulators](https://docs.fingerprint.com/docs/smart-signals-reference#android-emulator-detection) on Android.

  * New logic is available in [Android SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#december-2025).
</Update>

<Update label="September 2025">
  ## Factory Reset Detection — Android Improvements

  Enhanced the detection logic to more accurately identify true [factory resets on Android devices](https://docs.fingerprint.com/docs/smart-signals-reference#factory-reset-detection).

  * This update reduces false positives and improves signal reliability for fraud prevention workflows.
  * New logic is available in [Android SDK 2.10.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#september-2025).
</Update>


# Configuring resources
Source: https://docs.fingerprint.com/docs/configuration

The Dashboard allows you to manage all the resources and settings that govern how your Fingerprint implementation operates.

## API keys

API keys are necessary for your Fingerprint setup. Primarily to be able to identify visitors and generate visitor IDs, but also interact with other Fingerprint APIs and features.

To manage API keys, go to **Dashboard** > [**API keys**](https://dashboard.fingerprint.com/api-keys).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 51 22@2x" />
</Frame>

| Keys                      | Description                                                                                                                                                                              |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Public**                | Used to make **client-side requests** to identify visitors and generate the visitor ID. Used in the [browser](/docs/identify-visitors) or in [mobile apps](/docs/mobile-identification). |
| **Server API**            | Used to make **server-side requests** to the Fingerprint [Server API](/reference/server-api) to securely obtain visitor and request information.                                         |
| **Management API**        | Used to access the [**Management API**](/reference/management-api), allowing management of dashboard resources.                                                                          |
| **Sealed Client Results** | Used to enable **Sealed Client Results** to [encrypt client-side payloads](/docs/sealed-client-results).                                                                                 |
| **Proxy**                 | Used to authenticate with third-party **proxy integrations** which allow you to [evade ad blockers](/docs/protecting-the-javascript-agent-from-adblockers).                              |

To monitor API key usage, throttling, and latency, see [API key monitoring](/docs/health#api-key-monitoring).

## Request filtering

Request filtering is a feature that enables you to filter out unwanted identification requests using specific rules. On the Dashboard, you can **manage filtering rules** by adjusting which events should be allowed or denied.

To learn more information, see [request filtering](/docs/request-filtering).

To manage webhooks, go to **Dashboard** > [**Security**](https://dashboard.fingerprint.com/traffic-rules).

## Webhooks

Webhooks allow you to receive an HTTP request to your server with Fingerprint results for every identification event the moment it happens. On the Dashboard, you can **manage webhooks** and monitor their activity.

To learn more information, see [webhooks](/docs/webhooks).

To manage webhooks, go to **Dashboard** > [**Webhooks**](https://dashboard.fingerprint.com/webhooks).

To inspect webhook delivery attempts and diagnose failures, see [Webhook monitoring](/docs/health#webhook-monitoring).

## Custom subdomains

By using a custom subdomain, Fingerprint cookies are treated as "first-party", which increases identification accuracy while also allows you to avoid ad blockers. On the Dashboard, you can **register your subdomains** and manage their certificates.

To learn more information, see [Custom subdomain setup](/docs/custom-subdomain-setup).

To manage subdomains, go to **Settings** > [**Subdomains**](https://dashboard.fingerprint.com/subdomains).

## Proxy integrations

Proxy integrations are an alternative to custom subdomains, they allow you to proxy requests to Fingerprint through your own domain. Our cookies are treated as "first-party", which increased identification accuracy while allowing you to avoid ad blockers. On the Dashboard, you can **setup proxy integrations** and monitor their status and activity.

To learn more information, see [Evading ad blockers with proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers).

To manage proxy integrations, go to **Dashboard** > [**Libraries & integrations**](https://dashboard.fpjs.sh/integrations/active)

## Suspect Score

Suspect Score is an easy way to integrate Smart Signals into your fraud protection workflow. It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. On the Dashboard, you can configure the **weights for suspect scoring** by adjusting for each detected Smart Signal.

To learn more information, see [Suspect Score](/docs/suspect-score).

To manage suspect score weights, go to **Dashboard** > **Smart Signals** > [**Suspect Score**](https://dashboard.fpjs.sh/suspect-score)

***

[Viewing analytics](/docs/analytics)


# Bots and AI agents
Source: https://docs.fingerprint.com/docs/dashboard-bots-ai-agents

Analyze bot and AI agent traffic in the Fingerprint Dashboard, and investigate individual automation events.

The **Bots & AI agents** section of the Dashboard shows the automated traffic Fingerprint detected in your workspace, from AI agents and assistants to search crawlers and browser automation tools.

It groups your detections by category, provider, and identity, so you can see which bots reach your application and whether each one is who it claims to be. Use it to understand how much of your traffic is automated, find bots that fail identity verification, and inspect the full context of a single automation event.

<Warning>
  **Feature in Public Preview**

  The [Automation Intelligence API](/reference/automation-intelligence-api) is currently in a Public Preview testing phase. All feedback is welcome! If you encounter any issues, [contact the Fingerprint support team](https://fingerprint.com/support/).
</Warning>

## Availability

While the Automation Intelligence API is in Public Preview, the **Overview** page is available to every Fingerprint workspace on any plan.

| Surface                             | Availability                                                 |
| ----------------------------------- | ------------------------------------------------------------ |
| **Overview** page                   | All workspaces                                               |
| **Automation Intelligence API** tab | All workspaces, while the API is in Public Preview           |
| **JS Agent** tab                    | Workspaces with the Bot Detection Smart Signal in their plan |
| **Events** page                     | All workspaces, while the API is in Public Preview           |

To add Bot Detection to your plan, upgrade to Pro Plus. If you have an Enterprise plan, contact your Customer Success Manager or the [Fingerprint support team](https://fingerprint.com/support/).

## Overview page

The Overview page shows bot traffic trends across your workspace as a row of key metrics, a timeline chart, distribution lists, and an identity breakdown.

You can access the Overview page by visiting **Dashboard** > [**Bots & AI agents**](https://dashboard.fingerprint.com/bot-detection) > **Overview**.

<Frame>
  <img alt="The Bots and AI agents Overview page, showing key metrics, a timeline chart of bots by category, distribution lists, and the identity breakdown table" />
</Frame>

### Data sources

Fingerprint detects automation in two ways. Switching tabs changes the data behind every metric, chart, and list on the page.

| Tab                             | Data source                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| **Automation Intelligence API** | Automation tools detected at the edge from HTTP request metadata, without a JavaScript agent |
| **JS Agent**                    | Automation tools identified in the browser by the JavaScript agent                           |

Each tab shows the number of events recorded from that source. For guidance on which detection method fits your traffic, see [Bot Detection overview](/docs/bot-detection/overview#automation-intelligence-api-detecting-automation-without-a-browser).

### Filters

The filter bar applies to every metric, chart, and list on the page. Filter state is stored in the page URL, so **Copy link** shares the exact view you are looking at.

<Expandable title="available filters">
  | Filter          | Description                                                             |
  | --------------- | ----------------------------------------------------------------------- |
  | **Bot name**    | Find detections of a specific bot, such as `Claude-User` or `Googlebot` |
  | **Category**    | Find detections in a specific bot category                              |
  | **Provider**    | Find detections of bots operated by a specific provider                 |
  | **Identity**    | Find detections with a specific identity verification result            |
  | **Confidence**  | Find detections reported with high, medium, or low confidence           |
  | **Proxy**       | Find detections coming from an IP address detected as a proxy           |
  | **VPN**         | Find detections coming from an IP address detected as a VPN             |
  | **Environment** | Find detections associated with a specific environment                  |
</Expandable>

### Key metrics

The key metrics show the size and composition of your bot traffic for the selected period, each with a change compared to the previous period.

| Metric           | Description                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| **Total events** | Number of events recorded for the selected data source                                             |
| **Total bots**   | Number of events classified as a bot, and the share of all events they represent                   |
| **AI traffic**   | Share of bot detections that came from an AI category, such as AI agents, assistants, and crawlers |
| **Trusted**      | Share of bot detections with a verified identity                                                   |
| **Spoofed**      | Share of bot detections that claim a public identity but fail verification                         |
| **Unknown**      | Share of bot detections that do not publish a verifiable identity                                  |

**Spoofed** and **Unknown** are highlighted only when the count is above zero.

### Timeline charts

The timeline chart plots one view of your bot traffic over time. Select the chart from the dropdown above it, and switch between **Hourly** and **Daily** granularity.

| Timeline chart            | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| **Bots by category**      | Shows detected bots over time, split by category          |
| **AI agents by provider** | Shows AI bot traffic over time, split by provider         |
| **Trusted bots**          | Shows trusted bot detections over time, split by identity |
| **Total bots**            | Shows total events and detected bots over time            |
| **Spoofed bots**          | Shows spoofed bot detections over time                    |
| **Unknown bots**          | Shows unknown bot detections over time                    |

### Distribution lists

The distribution lists rank the entities that generated the most detections for your current filters.

| Distribution list  | Description                                      |
| ------------------ | ------------------------------------------------ |
| **Top bot names**  | The individual bots detected most often          |
| **Top providers**  | The bot providers generating the most detections |
| **Top categories** | The most common bot categories detected          |

### Identity breakdown

The identity breakdown is a matrix of bot categories against identity results, with the number of detections in each cell. Use it to see how trust varies by category. Verified AI assistants and unknown AI agents are different kinds of traffic, even though both appear as bots.

<Expandable title="identity results">
  | Identity     | Description                                                                            |
  | ------------ | -------------------------------------------------------------------------------------- |
  | **Verified** | Well-known bot with publicly verifiable identity, directed by the bot provider         |
  | **Signed**   | Bot that signs its platform via Web Bot Auth, directed by the bot provider's customers |
  | **Unknown**  | Bot that does not publish a verifiable identity                                        |
  | **Spoofed**  | Bot that claims a public identity but fails verification                               |
</Expandable>

<Expandable title="bot categories">
  * **AI Agent**
  * **AI Assistant**
  * **AI Browser**
  * **AI Crawler**
  * **AI Search**
  * **Advertising and Marketing**
  * **Aggregator**
  * **Browser Automation**
  * **Ecommerce**
  * **Monitoring and Analytics**
  * **Scraping**
  * **Search Engine Crawler**
  * **Search Engine Optimization**
  * **Security**
  * **Other**
  * **Unknown**
</Expandable>

To register your own bot so it is detected with a verified identity, use **Submit bot** on the Overview page, or see [Web Bot Auth implementation](/docs/bot-detection/web-bot-auth-implementation).

## Events page

The Events page lists individual automation events, so you can find a specific event and open its full details.

You can access the Events page by visiting **Dashboard** > [**Bots & AI agents**](https://dashboard.fingerprint.com/bot-detection) > **Events**.

<Frame>
  <img alt="The Events page, showing the activity scrubber above the filter bar and a table of individual bot events" />
</Frame>

<Info>
  The Events page lists events recorded with the Automation Intelligence API only. To investigate bots detected by the JavaScript agent, use the [Identification](/docs/analytics#identification-events) page and filter by bot detection.
</Info>

Above the filter bar, the activity scrubber shows event volume across the whole retention window. Drag the selection to narrow the table to a shorter period, or use the date range picker for a fixed range.

The Events page uses the same filters as the Overview page, plus two more:

| Filter           | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| **Bot detected** | Find only events that were, or were not, classified as a bot |
| **IP address**   | Find events coming from a specific IP address                |

Select any row to open its event details.

<Expandable title="Available columns">
  * **Date**
  * **Bot**
  * **Identity**
  * **Category**
  * **URL**
  * **IP Address**
  * **Country**
  * **Provider**
  * **Confidence**
  * **Proxy**
  * **VPN**
  * **Event ID**
</Expandable>

## Event details page

The event details page shows the full context Fingerprint recorded for a single automation event.

<Frame>
  <img alt="The event details page, showing the bot identity card, geolocation with a map, network details, and VPN and proxy results" />
</Frame>

On the page you can find:

1. **Bot identity**: the category, provider, name, and confidence of the detection. The card is titled with the identity result, and reads **Bot not detected** when the event was not classified as a bot.
2. **Geolocation**: the IP address, country, city, timezone, coordinates, postal code, ASN, and a map of the approximate location.
3. **Network**: the origin, referrer, and User-Agent of the request.
4. **VPN**: whether a VPN was detected, with confidence and the methods that contributed to the result.
5. **Proxy**: whether a proxy was detected, with confidence.

Use **Show JSON** to explore the entire event payload, and **Copy link** to share the event with your team.

## Data retention

Retention differs by data source, because Automation Intelligence API events are stored separately from identification events.

| Data source                     | Available history                                         |
| ------------------------------- | --------------------------------------------------------- |
| **Automation Intelligence API** | Up to the last 7 days, while the API is in Public Preview |
| **JS Agent**                    | Up to the last 30 days                                    |

## Related guides

<Columns>
  <Card title="Bot Detection overview" icon="bot" href="/docs/bot-detection/overview">
    How Fingerprint detects AI agents, browsers, and automation tools, and what each result means.
  </Card>

  <Card title="Automation Intelligence API" icon="code" href="/reference/automation-intelligence-api">
    Detect automation from HTTP request metadata alone, without a JavaScript agent.
  </Card>

  <Card title="Bot Directory" icon="book-open" href="/docs/bot-detection/bot-directory">
    The bots and AI agents Fingerprint can detect, with their result types.
  </Card>
</Columns>


# Monitoring health
Source: https://docs.fingerprint.com/docs/health



The Dashboard allows you to stay on top of **integration health**, by informing you of required SDK updates, and monitoring throttling, latency, and error rates.

## Health overview

The Health page gives you a high-level view of your Fingerprint setup, surfacing issues that need attention and pointing you to where to fix them.

To check it out, visit **Dashboard** > [**Health**](https://dashboard.fingerprint.com/health).

<Frame>
  <img alt="Clean Shot 2026 06 09 At 14 15 40@2x" />
</Frame>

Three status widgets at the top of the page highlight anything that needs your attention:

* **Throttled requests** (1) shows the total number of requests throttled in the current period, along with the API keys responsible. Each key links to its API key details, where you can adjust the [RPS limit](/docs/billing#rate-limiting-burst-protection) or investigate the traffic pattern.
* **Webhooks** (2) shows your webhook failure rate and the webhooks with the most recent delivery failures. Each entry links to its delivery logs.
* **SDK versions** (3) shows how many SDK updates are available across your integrations. Each entry shows the current version and the latest available version, and links to corresponding library page for the full breakdown.

When everything is healthy, each widget shows a neutral state - no action needed.

Below the widgets, a single timeline chart (4) lets you switch between three views using the dropdown:

* **API Latency** show the average latency for JavaScript agent requests, in 5-minute buckets. This is the time it takes a Fingerprint identification request to return data from the server. Only requests from client-side JavaScript SDKs are counted.
* **API Errors** shows requests that timed out or returned an error, including both client and server-side errors from the JavaScript agent.
* **Webhook Failed Calls** shows webhook delivery failures over time, broken down by webhook endpoint.

## API key monitoring

For Public and Server API keys, you can view detailed monitoring information on the key details page.

To check it out, visit **Dashboard** > [**API keys**](https://dashboard.fingerprint.com/api-keys) and select a key to view its details.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 55 12@2x" />
</Frame>

The key details page shows when the key was last used, by which library version, and on what origin domains or mobile apps.

Two charts give you a closer look at how the key is being used:

* The Request usage chart shows incoming identification requests using this API key, broken down into:
  * **Success** - successful requests with response HTTP 200
  * **Throttled** - requests over the configured RPS limit, responded with HTTP 429
  * **Restricted** - requests filtered out by request filtering rules or that exceeded workspace/environment limits, responded with HTTP 403
* The Server-side latency chart shows percentiles for the average time to process identification requests. Client-side signal collection latency is not included.

## Webhook monitoring

For each registered webhook, you can view a log of every delivery attempt by clicking into the webhook on the Webhooks page.

To check it out, visit **Dashboard** > [**Webhooks**](https://dashboard.fingerprint.com/webhooks) and select a webhook.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 53 33@2x" />
</Frame>

The Webhook events page lists each delivery attempt with:

* **Request ID** - the identification request this delivery is associated with
* **Visitor ID** - the visitor ID from the event payload
* **Status** - whether the delivery succeeded or failed
* **Status code** - the HTTP response code returned by your endpoint
* **Date** - when the delivery was attempted

Clicking on a request row will expand it, so you can inspect the full request and response when diagnosing why a delivery failed.

For details on retry behavior and the expected response contract, see [Webhooks > Timeout and errors](https://docs.fingerprint.com/docs/webhooks#timeout-and-errors).

## Outdated libraries

The **Libraries & integrations** page shows you a detailed view of all SDKs in use across your integrations, including both web and mobile SDKs as well as Server API SDKs.

To check it out, visit **Dashboard** > [**Libraries & integrations**](https://dashboard.fingerprint.com/integrations/active).

<Frame>
  <img alt="Clean Shot 2026 06 09 At 14 19 38@2x" />
</Frame>

Each row in the Libraries list shows:

* The library (e.g. JavaScript, Next.js, Node.js, iOS) and where it runs (Website, Server, or App)
* The number of requests in the last 24 hours
* The version in use, and the latest version available

Libraries are refreshed once every 24 hours.

### Per-library health

Clicking an active library opens its **Health** tab, which gives you a detailed view of where that SDK is running and which deployments are out of date.

<Frame>
  <img alt="Clean Shot 2026 06 09 At 14 22 14@2x" />
</Frame>

At the top of the page, four summary cards show:

* The latest version of the library
* The number of outdated origins out of the total observed
* Total requests in the selected window
* How many of those requests came from outdated versions

Below the summary, the origins table lists every domain (for web SDKs) or app (for mobile SDKs) where this library is running:

* **Origin** - the domain or app ID
* **Version** - the SDK version in use, or a "Multiple" label when more than one version is detected
* **Requests** - the number of identification requests from this origin in the selected window
* **Last request** - timestamp of the most recent request
* **Severity** - whether the origin is up to date, or how far behind it is

**Domains**

For web SDKs, clicking a domain row expands it to show the specific URLs observed on that domain and the SDK version detected on each. When more than one version appears on the same URL, each version is listed with its own request count, so you can see whether stale clients are still trickling in or whether a deployment really is out of date.

**Mobile apps**

Mobile apps often have multiple SDK versions in use at once, since users update apps at different rates. Each version is shown with its request count so you can see the adoption of your latest release.

**Activity**

Below the origins table, the Activity chart shows total request volume over time, with errors and timeouts called out separately. This helps you spot whether an outdated origin is also experiencing reliability issues.


# Identification, accuracy, and confidence score
Source: https://docs.fingerprint.com/docs/identification-accuracy-and-confidence

Learn about the different methods Fingerprint uses to identify visitors, how Fingerprint defines and maintains accuracy, and how to use confidence score in your applications.

To identify a browser or a device, Fingerprint collects several properties from them. Our advanced machine-learning models use these properties to create a unique visitor ID.

# Identification methods

Fingerprint uses one of the following approaches to identify browsers and devices:

* **Deterministic Identification**: This method uses browser or device properties that are unique and reliable (*aka* deterministic properties). [HTTP cookie](https://en.wikipedia.org/wiki/HTTP_cookie) is an example of such a property. These properties are accurate, but may not be available in situations like:

  * Private or incognito browsing modes.
  * Browser storage is cleared.
  * Third-party cookies are not available in certain browsers. See [Safari Intelligent Tracking Prevention](/docs/browser-and-device-support#safari-intelligent-tracking-prevention). In such situations, Fingerprint identifies visitors using probabilistic identification.

* **Probabilistic identification:** This method uses non-deterministic properties such as screen resolution, timezone, etc. These properties are combined to create a unique identifier for a browser or device. To learn more, see [What is browser fingerprinting? 6 top techniques to fight fraud](https://fingerprint.com/blog/browser-fingerprinting-techniques/). This method introduces a probability of error because non-deterministic properties change over time and their values could be the same between two identical browsers. These factors can cause Fingerprint to create the same identifier for two different visitors or identify the same visitor differently.

# Identification accuracy

Identification accuracy primarily applies to probabilistic identification. It defines the ability to identify returning browsers and devices precisely.

## How is identification accuracy measured?

We measure accuracy by performing prediction experiments with two sets of data in which:

* The *control* dataset is the set of deterministically identified events.
* The *test* dataset is created by removing the deterministic properties.
* The events in the test dataset are re-identified.
* The visitor IDs in the test dataset are compared with the visitor IDs in the control dataset.

The comparison results can be categorized as one of:

* **True-positive:** The visitor ID remained the same in both control and test datasets.
* **False-positive:** The visitor ID in the test dataset is different from that of the control. This browser has been incorrectly identified as another **existing** browser.
* **False-negative:** The visitor ID does not exist in the control dataset. This browser has been incorrectly identified as a new browser.

<Check>
  **Identification accuracy for mobile devices is higher than that of browsers**

  We identify mobile devices using properties that remain stable for longer durations than those used to identify browsers.
</Check>

At Fingerprint, we maintain industry-leading accuracy by continually striving to minimize the false-positive and false-negative rates.

# Confidence Score

For every identification request, a confidence score is computed internally. You can get the confidence score for a specific request in one of the following ways:

* Via the [Server API](/reference/server-api-get-event)
* Via [webhooks](/reference/posteventwebhook)

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  {
    "event_id": "1708102555327.NLOjmg",
    "identification": {
      "visitor_id": "Ibk1527CUFmcnjLwIs4A9",
      "confidence": {
        "score": 0.97,
        "version": "1.1"
      },
      "visitor_found": false,
      "first_seen_at": 1708102555327,
      "last_seen_at": 1708102555327
    },
  }
  ```
</CodeGroup>

The confidence score indicates the probability of a false-positive identification. It is a floating-point number whose value ranges from 0 to 1. The higher the value, the more confident Fingerprint is about not misidentifying this browser as another.

## Using confidence score in your application

You can use the confidence score to improve security and user experience. A few examples:

* **Prevent account takeover**: You can use the confidence score to request additional verification. For example, request OTP for browsers whose confidence score is below 0.95.
* **Increase conversion:** You can use the confidence score to profile an anonymous user. For example, you can offer tailor-made promotions and enhance the user experience.

The thresholds given here are only examples. Finding the optimal threshold for your use case may require iterative experiments.

## How is the confidence score calculated?

In simple terms, the confidence score is calculated as

```
confidenceScore = 1 - falsePositiveProbability
```

Where `falsePositiveProbability` is deduced from our prediction experiments and represents the probability of a false-positive identification.

## Understanding the confidence score

**First-time browsers or devices**

Fingerprint identifies a browser or a device as new only when it cannot find a match for this browser in your data. In this case, the probability of a false-positive identification becomes 0. Hence, the confidence score for such new browsers or devices is **1.0**

An existing browser could also be incorrectly identified as a first-time browser. The confidence score in this case will still be 1.0. Because it doesn't state the probability of a false-negative identification, only false-positive rather.

**Returning visitors identified deterministically**

The deterministic properties are unique, even among identical browsers. It is not possible to incorrectly identify one browser as another. In other words, the `falsePositiveProbability` is **0**. Hence, the confidence score for these browsers or devices is **1.0.**

**Returning visitors identified probabilistically**

The probabilistic properties are not as unique as the deterministic properties. This increases the chances of incorrectly identifying a browser as another. In other words, the `falsePositiveProbability` is greater than 0. Hence the confidence score for these browsers or devices is always **less than 1.0.** Even when future identifications are deterministic (see Example).

## Example: Confidence score for different scenarios

<img alt="" />

# How is accuracy different from confidence score?

### Accuracy

* Represents the **overall value** that Fingerprint provides you. For example, a 98% true-positive rate would mean that, in the absence of deterministic properties, only 2% of your visitors may be identified incorrectly.
* It is not associated with an individual identification request.

### Confidence Score

* For an identification request, it represents the probability of **only** the false-positive identification. It should not be used to determine the overall accuracy of the product.
* Unlike accuracy, confidence score enables you to make real-time decisions as described in [using confidence score in your application](/docs/identification-accuracy-and-confidence#using-confidence-score-in-your-application).

***

[Planning your implementation](/docs/planning-implementation)


# Introduction
Source: https://docs.fingerprint.com/docs/introduction

Learn how you can prevent fraud and improve user experiences with Fingerprint.

<iframe title="YouTube video player" />

## What is Fingerprint?

**Fingerprint is a software-as-a-service that identifies online devices and provides valuable information about them.** Fingerprint doesn't scan human fingerprints like biometric systems do. Instead, it creates a unique identifier for each device, called a "Visitor ID," which stays permanently tied to that device. It works on both web browsers and mobile devices, making sure the devices are accurately identified on any platform.

### How it works

Fingerprint uses browser and device fingerprinting along with advanced server techniques, like statistical ID generation and machine learning, to create a unique visitor ID such as **`xPFysGV25VxZcGQUxVIt`**. This ID stays the same over time, even if the device’s settings or software changes or if cookies are deleted or unavailable.

You can see your own device ID by visiting [our demo](https://demo.fingerprint.com/playground). While there, try revisiting in incognito mode or with your VPN on. Your visitor ID will be the same.

Our stable visitor IDs are helpful when people try to hide their identity online, like in fraud detection or protecting accounts. They also make things easier for trusted users by reducing the need for constant logins or CAPTCHA checks because trusted users can be recognized easily. Fingerprint is designed to not need any permissions, so users won’t see permission prompts in their browser or on their phone.

### Our products

Fingerprint has two main products that work together to help you identify and understand your visitors better.

* [**Identification**](https://fingerprint.com/products/identification/): Our main product creates very accurate and stable visitor IDs. These IDs help stop fraud by looking at how devices are used and can also make the user experience better.
* [**Smart Signals**](https://fingerprint.com/products/smart-signals/): Along with Identification, Smart Signals provide extra insights into visitor behavior, like spotting [bots](/docs/smart-signals-reference#browser-bot-detection), [VPN use](/docs/smart-signals-reference#vpn-detection-for-browsers), or [tampered browsers](/docs/smart-signals-reference#browser-tamper-detection). These insights help you identify and respond to suspicious activity more effectively.

## Fingerprint Identification vs. FingerprintJS

Fingerprint's [Identification](https://fingerprint.com/products/identification/) is significantly better than its open-source counterpart, **FingerprintJS**. While both the open-source and proprietary versions identify devices, the proprietary version, Fingerprint Identification, is more accurate and provides detailed, additional information about the device. Please see the FingerprintJS vs. Fingerprint Identification [comparison table](https://github.com/fingerprintjs/fingerprintjs/blob/master/docs/comparison.md) for a feature-by-feature breakdown of the differences.

### FingerprintJS

FingerprintJS has been a key tool for browser fingerprinting since it was created on [GitHub](https://github.com/fingerprintjs/fingerprintjs) in 2012. It’s still the most accurate open-source fingerprinting library, available to all users at no cost.

FingerprintJS is a JavaScript library that collects browser details to make a unique ID called a "fingerprint." It works quickly and runs on the client side, so no backend is needed. However, it has some limits:

* **Same fingerprints on similar devices**: FingerprintJS can give the same fingerprint for devices with the same setup. For example, two iPhone 15s using Safari will have the same fingerprint, which makes it hard to tell them apart.
* **Changes affect fingerprints**: The fingerprints can change when things like time zone, OS, or browser updates happen. This makes them less reliable for long-term use.

### The advantages of Fingerprint Identification

Fingerprint Identification is our main commercial product, offering big improvements over FingerprintJS. It works as a client-server system, using a client-side SDK to gather data and send it to Fingerprint for processing. This allows Fingerprint Identification to:

* **Give more accurate identification**: Unlike FingerprintJS, it can tell apart devices with the same setup (like two iPhone 15s), making sure each device gets a unique and steady visitor ID.
* **Work on more platforms**: It works not just on web browsers but also on mobile devices and connects easily with APIs, webhooks, and cloud tools.
* **Stay stable over time**: The visitor IDs it creates stay the same for months, even with changes to the device or software, making it more reliable for long-term use.

## Fingerprint design patterns

Fingerprint can be used in various ways to prevent fraud and improve user experience. Here are some common patterns to use its visitor IDs effectively:

* Comparing visitor IDs
* Counting visitor IDs linked to data
* Counting data linked to a visitor ID

### Comparing visitor IDs

This pattern generates a visitor ID before important actions, like a login. It is then compared to the previous ID for the same user. If they match, the user can continue without extra checks. If they don’t match, it could mean a different device or an unauthorized attempt, so extra verification, like a one-time code, is recommended. This helps to make sure only authorized users can perform sensitive actions.

### Counting visitor IDs linked to data

Here, each time a key action happens — like logging in, creating an account, or making a purchase — a visitor ID is added to a list for that user or account. If the list gets too big (e.g., more than five IDs), it might mean several devices are being used by the same user. This could suggest account sharing or unauthorized access. This could trigger alerts or ask for extra verification to protect the account.

### Counting data linked to a visitor ID

This pattern tracks how many internal IDs (like account IDs or transaction IDs) are connected to one visitor ID. For example, if a visitor ID is linked to many new account attempts, it could signal possible fraud, like multiple account creation. By looking at these connections, you can spot and prevent fraud, such as account farming or coupon abuse.

## Use cases

Fingerprint can be used in many ways to prevent fraud and improve user experience based on the design patterns mentioned above. Here are three common examples. You can find more on our [demo hub](https://demo.fingerprint.com/).

### Reducing login friction

The pattern used here is ***comparing visitor IDs***.

Compare the visitor IDs from past and current logins to make logging in easier without compromising security. The first time a user logs in, create and save a visitor ID. For future logins, create a new ID and compare it to the saved one. If they match, the login can go through without extra checks. This reduces friction while keeping the login process secure.

### Account sharing prevention

The pattern used here is ***counting visitor IDs linked to data***.

By counting the number of visitor IDs accessing a single account, you can effectively prevent account sharing. For example, if more than a certain number of devices (e.g., more than 3) are used to log into the same account, you can prompt the user to verify their identity or restrict further logins until they confirm ownership. This approach ensures that the account is used as intended without relying on frequent MFA or other disruptive measures.

### New account fraud

The pattern used here is ***counting data linked to a visitor ID***.

In some use cases, users shouldn’t be able to create multiple accounts. Instead of using methods like Single Sign-On or phone validation every time, which can hurt the user experience, generate a visitor ID each time a new account is created. If the number of accounts linked to that ID is small (e.g., 3 or fewer), let it continue. If the number is high (e.g., more than 3), trigger extra checks, like phone validation, to prevent fraud.

## Future-proof, reliable, and secure

Browsers like Safari, Chrome, and Brave are adding more privacy features, like Safari 17's updates, Google’s Privacy Sandbox, and Brave’s anti-fingerprinting. It’s normal to wonder what this means for the future of fingerprinting. However, Fingerprint is still a strong and reliable solution.

For over 10 years, Fingerprint has provided industry-leading accuracy. Some browsers have added tools to block fingerprinting. These tools haven’t worked well because fingerprinting uses basic browser APIs required for building web applications. Blocking it completely would break parts of the internet.

Even if future updates make fingerprinting less effective, Fingerprint Identification will still be one of the most accurate for two reasons:

1. **Universal Impact**: Any browser changes will affect all identification solutions, but Fingerprint will remain highly accurate in comparison, even if slightly less so.
2. **Hybrid Approach**: Fingerprint Identification combines server data with browser data to create stable visitor IDs. The server-side component keeps accuracy high as browsers change.

Fingerprint is also built to perform well without crashing your app. It has strong error handling and a timeout feature, making integration smooth. If generating a visitor ID takes too long (like on older devices), the process stops safely, avoiding disruptions for users.

On the security side, Fingerprint makes it very hard for attackers to fake a visitor ID. Developers can check for ID mismatches and add extra security checks when needed without annoying users. With these protections, Fingerprint stays a reliable and secure solution that can adapt to browser changes while keeping its accuracy and performance high.

## Want to get help?

If you're a developer, please join our [Discord channel](https://discord.com/invite/39EpE2neBg) for technical discussions.

If you’re a GitHub user, please use [discussions](https://github.com/fingerprintjs/fingerprintjs/discussions) and open [issues](https://github.com/fingerprintjs/fingerprintjs/issues).

If you’re a customer, our [US-based support](https://fingerprint.com/support/) is always ready to help!

***

What’s Next

* [Start your free workspace now](https://dashboard.fingerprintjs.com/signup/)
* [Quick Start Guide](/docs/quick-start-guide)
* [Install the JavaScript agent](/docs/install-the-javascript-agent)


# Planning your implementation
Source: https://docs.fingerprint.com/docs/planning-implementation

Key considerations to think through before implementing Fingerprint

Before adding Fingerprint to your platform, it's important to plan how you'll use device intelligence to meet your needs. Fingerprint gives you the data, but you decide how to use it. It's flexible and easy to integrate, but you'll need to figure out where to apply it and what actions to take based on the insights. This guide covers the key steps to consider for a smooth implementation.

## Assess key device intelligence touchpoints

To make the most of Fingerprint, it's important to know where it will be most useful on your platform. Are you focusing on stopping fraud or improving user experiences? Begin by finding the pages or actions on your site that need visitor identification. These are usually places where sensitive actions happen or where it's important to understand user behavior. Common areas include:

* **Entry pages**: Recognize anonymous visitors before they identify themselves, which supports personalization and gives you earlier context on who is using your site or app.
* **Login pages**: Protect against account takeover and credential stuffing by recognizing known visitors without friction while reserving step-up authentication for unfamiliar or suspicious ones.
* **Signup pages**: Catch repeat sign-ups from the same device or automated signups from bots, and block registrations from devices you have already banned.
* **Transactions and checkouts**: Catch payment fraud and card testing at high-value moments, and keep the device record as chargeback evidence.
* **Account updates**: Re-check the device when someone changes a password, email, or payout details.

Decide how you want to treat AI traffic at each of these touchpoints. Fingerprint can [detect AI agents and assistants](/docs/ai-agents) and expose their identity verification status, so you can allow verified agents while applying custom logic to unverified or spoofed traffic.

You will also need to decide when and how often to make identification requests. The general best practice is to [identify on demand](/docs/identify-visitors#timing-identification-requests), when the visitor takes the action you care about, rather than on every page load. For sensitive actions like logins, sign-ups, and payments, always identify visitors in real time, but for lower-risk activities, [caching the visitor ID](/docs/identify-visitors#caching-the-visitor-id) can help to avoid unnecessary API calls. However, frequent identification is important for maintaining accuracy, as it allows small changes in browsers and devices to be noticed over time.

Additionally, consider [common patterns](/docs/introduction#fingerprint-design-patterns) that apply to most sites and might also apply to your environment. These include comparing current and past visitor IDs to check if users are returning. You can also count visitor IDs linked to a single user to detect account sharing or unauthorized access. Another option is to check how many data points, such as account or transaction IDs, the visitor ID links to. Use these patterns to understand where visitor identification fits your platform's needs. An easy way to support these patterns is to link Fingerprint's visitor IDs to identifiers you already have. You can do that within your own data stores or by passing a [linked ID and tags](/docs/tagging-information) with every identification request.

## Establish baselines for visitor behavior

Next, you should analyze your visitor traffic to understand what normal behavior looks like for your platform. You can do this by analyzing your current general analytics data, or by adding Fingerprint to a few key pages and identifying visitors without acting on the results, so you start collecting identification data right away.

For example, is it normal for many devices to access a single account? If so, how many devices is typical? Do most users log in from the same device every time? Knowing these baselines helps you understand what's normal and know when to raise red flags.

The Fingerprint [dashboard](https://dashboard.fingerprint.com/overview) is a quick way to get oriented: the Overview page shows usage and unique visitors, while the [Smart Signals page](https://dashboard.fingerprint.com/smart-signals) shows how often each Smart Signal fires. You can also [export identification events](https://dashboard.fingerprint.com/events) to CSV or use the [Server API](/reference/server-api-search-events) to analyze them in your own tools. For deeper analysis, store identification events in your own systems, alongside the outcomes you already monitor, so you can join them together and look for real patterns.

Consider what device characteristics are more unusual for your users. For instance, if most of your users don't use [VPNs](/docs/smart-signals-reference#vpn-detection-for-browsers) or [incognito mode](/docs/smart-signals-reference#browser-incognito-detection), you may consider those behaviors as risky. Other [signals](/docs/smart-signals-reference) worth checking your traffic against include residential proxies, anti-detect browsers, rare device configurations, and, on mobile, rooted or jailbroken devices and emulators.

One way to evaluate these signals is to use [Suspect Score](/docs/suspect-score), which rolls them into a single risk value. Once you have collected identification data, you can label past identifications with your own fraud outcomes, upload that to the Fingerprint dashboard, and get scoring weights tuned to your traffic, showing which signals actually predict fraud for you.

## Define responses for flagged activity

After you understand what normal and suspicious behavior looks like on your platform, the next step is to decide how to respond. Having a range of responses based on the level of risk helps balance security with user experience.

Based on the data you get from Fingerprint, here are some options:

* **Allow the action**: For visitors with no signs of suspicious behavior, allow the action to proceed without adding extra steps, like MFA. This keeps the experience smooth for legitimate users.
* **Add extra friction**: If something seems off, you can add steps to verify the action. For example, if a user tries to make a purchase from an unfamiliar device, you could send a one-time passcode before completing the transaction.
* **Block the action**: Stop the action completely for high-risk behavior, like a malicious bot trying to change account settings. This helps prevent unauthorized access or fraud.
* **Manual review**: In some use cases, it may make sense to flag the activity for manual review. This allows your team to look into the situation before making a final decision.

## Prepare for data storage and system integrations

When implementing Fingerprint, plan how to store, manage, and integrate the IDs and device signals it provides. Fingerprint only retains visitor history for a limited time, ranging from 30 days to 90 days or longer, depending on your plan. In the dashboard, identification events are available for 3 months, and aggregate statistics are available for 12 months. Decide if this works for you or if you need to store the data longer in your own data storage.

<Note>
  **Staying compliant with data privacy laws**

  When storing identification data, make sure to consider your business needs as well as data regulations like GDPR, CCPA, and other applicable laws. Your workspace region is chosen when you create your workspace and cannot be changed later, so confirm which region you need before you set one up.

  Beyond storage, consider user consent requirements. Consent isn't always required for [legitimate interests](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/legal-grounds-processing-data_en#legitimate-interests-of-the-controller:~:text=A%20company/organisation%20may,of%20its%20IT%20systems.), such as fraud prevention, but it may be required for use cases like personalization. To [stay compliant](/docs/privacy-and-compliance), be sure to follow user consent and [data residency](/docs/regions) rules.
</Note>

Decide up front how you will measure whether Fingerprint is working, so you can tell what to adjust later. Set clear metrics, like the number of account takeovers prevented or fraudulent purchases stopped. Tie those to business impact where you can, such as the revenue recovered from fewer false positives or the support hours saved. Review these metrics often to adjust your logic and rules. For more guidance on ways to analyze Fingerprint data and outcomes, see Test 3 from [How to evaluate fingerprinting accuracy in the real world](https://fingerprint.com/blog/evaluate-fingerprinting-accuracy/).

Consider how Fingerprint data will fit into other systems. This might mean [sending device signals to your Web Application Firewalls (WAFs)](https://fingerprint.com/blog/bot-detection-powered-application-firewall/) or fraud detection models. Look for areas where Fingerprint can improve security or enhance the user experience. If your team investigates fraud by hand, the [MCP server](/docs/mcp-server) connects your identification data to AI assistants, enabling them to query event data and investigate suspicious activity in natural language.

## Map out installation and API usage

A quick way to get started is the [Fingerprint CLI](https://github.com/fingerprintjs/fingerprint-cli). Run `npx fingerprint` from your project root, and it will sign you in, detect your frontend and backend frameworks, provision your API keys, and write the integration into your code one step at a time.

To integrate manually, add the [JavaScript agent](/reference/js-agent) to your website's frontend code, either through the CDN or an [SDK for your framework](/docs/web-quickstarts-overview). For mobile apps, there are [SDKs](/docs/mobile-sdks) covering both native apps and multi-platform frameworks. From there, choose how to safely get Fingerprint results to your server: the [Server API](/reference/server-api), [Sealed Client Results](/docs/sealed-client-results), or [Webhooks](/docs/webhooks).

The Server API can be accessed directly or through one of the [backend SDKs](/docs/server-quickstarts-overview). Requests should be made from a backend server that can securely store and access secret keys.

With Sealed Client Results, you get a fully encrypted response payload from the JavaScript agent or mobile SDKs. This payload contains the same data available through the Server API, so you can skip the extra API call and decrypt it on your backend to reduce latency.

Fingerprint can also send you identification data using webhooks. If you choose this option, you'll need to create an endpoint on your server to receive and handle these webhook events. Webhooks provide a great way to store the full historical record of your event data.

You should also decide where your response logic lives. You can choose to write it directly in your application code, or you can use the [Rules Engine](/docs/rules-engine). The Rules Engine lets you define rules in the dashboard and returns a rule action for each identification event, so your fraud team can adjust them as needed without waiting for a code change. The Rules Engine decides the outcome, but your application applies it.

If your site runs on Cloudflare, [Flow](/docs/flow-deployments) goes a step further by deploying a worker that handles the identification setup described above, with little to no changes to your application code. You can pair it with a ruleset to enforce your rules at the edge, or run it on its own to collect identification data without taking any action.

### Choose an ad blocker evasion strategy

To ensure you can properly identify all visitors to your site, it's important to [prevent ad blockers from blocking identification requests](/docs/protecting-the-javascript-agent-from-adblockers). You can set up a custom subdomain pointing to Fingerprint's infrastructure to reduce request blocking. You can also use one of the available cloud proxy integrations for [Cloudflare](/docs/cloudflare-integration), [Akamai](/docs/akamai-proxy-integration), [CloudFront](/docs/cloudfront-proxy-integration-v2), and [other cloud providers](/docs/protecting-the-javascript-agent-from-adblockers#cloud-proxy-integrations). Both methods protect identification requests from getting blocked by proxying them through your own domain.

## Getting started

Ready to get started now that you've planned out your implementation? Fingerprint support is [here to help you](https://fingerprint.com/support/) take the next step. Get started with identifying [browsers](/docs/install-the-javascript-agent) and [mobile devices](/docs/mobile-identification), or explore the [demos](https://demo.fingerprint.com/) to see Fingerprint in action. You can also review the [use case tutorials](/docs/use-case-tutorials-overview) for step-by-step implementations of common fraud scenarios. Here are a few to help you hit the ground running:

* [Account takeover](/docs/account-takeover-use-case-tutorial)
* [Chargeback dispute](/docs/chargeback-dispute-use-case-tutorial)
* [Web scraping](/docs/web-scraping-use-case-tutorial)


# Playground
Source: https://docs.fingerprint.com/docs/playground





# Privacy and compliance
Source: https://docs.fingerprint.com/docs/privacy-and-compliance

Overview of Fingerprint's regulatory compliance and how we ensure secure and responsible visitor identification.

## Is Fingerprint GDPR compliant?

[FingerprintJS](https://github.com/fingerprintjs/fingerprintjs/), our open-source library, is GDPR compliant because it is stateless and doesn't store any data. It's a JavaScript function that generates a hash from only publicly available browser information. However, depending on how you use FingerprintJS data, you may need user consent, which is outside the scope of this guide.

[Fingerprint Identification](https://fingerprint.com/products/fingerprint-pro/) (our commercial product) is also GDPR compliant, but it’s important to understand the details behind it.

### Data controller vs data processor

Fingerprint Identification is a SaaS product offered as a client-server API system. Under GDPR, there are two roles: “data controllers” and “data processors.” A data controller is a website or app that decides to collect and store user data. A data processor is a third-party service that receives, stores, and processes data from the controller.

Examples of data controllers are sites like eBay, Wikipedia, and YouTube. Data processors include services like DigitalOcean, AWS, and Google Cloud.

Fingerprint Identification is a data processor, while a website using its API is a data controller. For example, Dropbox uses Fingerprint Identification to prevent account abuse and improve security. Dropbox is the data controller, and Fingerprint is the data processor.

As a data controller, Dropbox must follow GDPR rules and collect and use the data correctly according to GDPR guidelines.

As a data processor, Fingerprints must also follow GDPR and handle the data it **gets from data controllers** correctly, according to GDPR guidelines.

### What obligations does Fingerprint have as a data processor?

Fingerprint must delete personal information it receives from a data controller when requested. See [Data Deletion](/docs/regions#data-deletion) for more information.

### Do I need to have a GDPR consent management banner if using Fingerprint?

It depends on your use case and how you are using Fingerprint:

* **Attribution and personalization:** If you use Fingerprint for things like attribution or personalization, you’ll likely need to get user consent, similar to how you handle cookies.
* **Fraud prevention and security:** If you use Fingerprint for fraud prevention, this usually falls under “Legitimate interest” according to GDPR, so explicit user consent isn’t needed. You can check the [European Commission’s definition of legitimate interest](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/legal-grounds-processing-data_en#legitimate-interests-of-the-controller:~:text=A%20company/organisation%20may,of%20its%20IT%20systems.) for more details.

### If I do need user consent before identifying visitors, how do I implement it?

Instead of identifying visitors automatically on page load, you can choose to explicitly trigger the Fingerprint identification request only in specific circumstances. For example, only after the visitor grants consent by clicking "Accept" on a cookie consent banner.

The Fingerprint JavaScript agent only stores cookies and other metadata in the browser during the identification request. See [Timing identification requests](/docs/identify-visitors#timing-identification-requests) for more information.

### What about US Privacy Law (including CCPA) compliance?

When using Fingerprint, you are responsible for US Privacy Law compliance as the business, and Fingerprint acts as a Service Provider, processing Personal Information only as needed to provide the service. We do not sell or share data outside the scope of our agreement. You must inform consumers about data processing and handle consumer rights requests. Fingerprint supports compliance by helping with data deletion and protection. For more details, see our [US SPL Data Processing Addendum](https://docs.fingerprint.com/docs/dpa-usspl).

## Can you use Fingerprint to track visitors across the internet?

No, Fingerprint is primarily designed for fraud prevention in the same-site context. The visitor ID is scoped to each Fingerprint workspace, not the internet at large. If two Fingerprint customers identify the same browser or device, they will receive different visitor IDs. This intentionally makes Fingerprint unsuitable for creating a global visitor activity graph across *unrelated* sites as you might do with third-party cookies.

## Can you use Fingerprint for marketing attribution?

Yes, you can use Fingerprint for marketing attribution and personalization *in the context of your business*. It works well for identifying visitors on the same website, or multiple websites you control, even across domains.

For example, you can use Fingerprint to link a purchase to an email campaign or observe user interactions across your landing page and web application.

## Can you identify visitors across multiple domains you own?

Yes, you can generate the same visitor ID for the same browser or device on multiple domains you control. To do so, configure the JavaScript agent on each website with a public API key from the *same* Fingerprint workspace.

If you need to query the Fingerprint Server API by domain name, you can use [linked IDs](/reference/js-agent-get-function#linkedid) to associate a domain with each identification event. To ensure maximum accuracy when using [proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers), each website needs to proxy requests through its own domain or subdomain.


# Troubleshooting Unexpected Usage Spikes
Source: https://docs.fingerprint.com/docs/troubleshooting-unexpected-usage-spikes

If you're seeing a sudden spike in Fingerprint usage, it usually comes down to two main causes: implementation issues or malicious traffic. This guide will help you quickly diagnose and resolve the issue.

## Quick Checklist

* **Check for recent code changes** - Spikes often correlate with a recent deployment. Review any updates that may have changed when or where the Fingerprint agent is called.
* **Check for caching** - Without caching, repeat visits or user actions can trigger multiple identification requests. Ensure visitor IDs are cached appropriately using `sessionStorage` or `localStorage`.
* **Audit for duplicate calls** - Look for React `useEffect` calls missing dependency arrays, or code that triggers `get()` multiple times per session.
  * The JavaScript agent only bills for `get()` calls. Confirm you’re calling it only when the visitor ID is needed, and not on every page load or render.
* **Review the "Insights" section** - On the [Overview](https://dashboard.fingerprint.com/overview) page of your Fingerprint dashboard, adjust the trend chart by selecting the "events per visitor" metric in the drop down. A noticeable increase could indicate your code is sending more identification requests than before.
* **Inspect bot traffic** - Use the [Bots & AI agents](https://dashboard.fingerprint.com/bot-detection) page to check for bot activity. Spikes caused by scraping or browser automation suggest abuse, not implementation error.
* **Secure your API key** - Check if your API key is used on unknown domains or apps. Set up [request filtering](/docs/request-filtering) to block unwanted domains, headers, or IPs.
* **Contact support** - If you’re still unsure, reach out to [Support](https://fingerprint.com/support/) or review our [bill forgiveness](/docs/billing#how-am-i-protected-from-overpaying) policy.

## Implementation Related Spike

These spikes are usually caused by integration issues. Clues include a spike following a recent code change or usage increasing alongside user activity. For example, if usage scales with traffic but seems higher than expected, it may indicate an implementation issue - such as more identification calls per user than intended. Common causes include missing caching, duplicate calls, or unintentional triggers.

### Missing Visitor ID Caching

* Without caching your visitor ID, each page load or user action can generate a new request, increasing your API usage.
* Choosing whether to cache depends on your use case and risk tolerance:
  * If your use case demands highly accurate identification, we recommend identifying the visitor [only when needed](/docs/identify-visitors#timing-identification-requests) and always using a fresh visitor ID *without* caching.
  * For less sensitive scenarios, caching can significantly reduce redundant calls and improve performance.
* You can store the visitor ID in `sessionStorage` (recommended) or `localStorage` to reuse the ID for up to 1 hour and reduce redundant calls.

Read: [Caching Visitor ID](/docs/identify-visitors#caching-the-visitor-id)

### Duplicate Calls from Loops

* Common in single-page applications (SPAs) where component re-renders or navigation triggers extra calls.
* In React, missing a dependency array in `useEffect` can cause `get()` to be called on every render.
* Use the [React SDK](/docs/react) to manage this more easily.

### Unintended Calls to Fingerprint

* For the JavaScript agent, `start()` requests are not billed, but `get()` requests are.
  * Only call `get()` when the visitor ID will be used by your application.
* Avoid triggering identification on every render or page view.
* Visit the [Optimizing JavaScript Agent Usage](/docs/optimize-javascript-agent#only-use-the-javascript-agent-where-you-need-it) page to learn more about common use cases and when to make the `get()` request.

## Malicious Traffic or Bot-Driven Spike

These spikes often happen suddenly and without any recent deployments. Look for unusual traffic patterns - like bursts of activity or off-hour usage. Use Smart Signals or the Server API to review recent identification events. A high number of “bad bot” detections typically points to automated abuse, not an integration issue.

### Bot Traffic

* Visit the **[Bots & AI agents](https://dashboard.fingerprint.com/bot-detection)** page to view traffic flagged as bots.
* A sudden increase in the **Scraping** or **Browser Automation** categories can indicate scraping or automated abuse.
* Use the [Bots and AI agents](/docs/dashboard-bots-ai-agents) guide to narrow the spike down to a specific bot, provider, or country.
* Use this information to adjust filters or rate-limiting rules in your app.

Some helpful resources to learn more:

* [Browser Bot detection](/docs/bot-detection/overview)
* [Bot detection: How to block bad bots in 2025](https://fingerprint.com/blog/bot-detection/)
* [How to Identify and Block Bots in Your Firewall](https://fingerprint.com/blog/bot-detection-powered-application-firewall/)
* [Mitigating bad bots at WAF level through Cloudflare](/docs/cloudflare-integration-blocking-ips-and-origins)

### Public API Key Misuse

* Public API keys are visible in client-side code and can potentially be leaked or copied.
* Check whether your API key is being used on unknown domains or in unauthorized mobile apps.
* It’s good practice to restrict your API key to only the domains, headers, or IP addresses where legitimate traffic is expected.
* Set up [**Request Filtering**](https://dashboard.fingerprint.com/traffic-rules) in the dashboard to prevent unwanted usage and protect your billing.

Protect your Public API key:

* [Request Filtering for Websites](/docs/request-filtering-for-websites)
* [Mobile App Filtering](/docs/mobile-app-filtering)
* [Search Bot Filtering](/docs/search-bots-filtering)
* [Network Filtering](/docs/network-request-filtering)

## Deep Dive: Exporting and Analyzing Identification Data

If you want to dig deeper into a spike, exporting your data to CSV allows for a more granular investigation. Here's how:

1. **Check usage trends** - Go to the [Overview](https://dashboard.fingerprint.com/overview?period=last_30_days) page and review API usage over the past 30 days.
2. **Identify the spike window** - Pinpoint the spike date, and include the day before and after.
3. **Filter identification events** - Navigate to the [Identification](https://dashboard.fingerprint.com/events) page and apply a date filter for that window.
4. **Export the data** - Use the export option to download a CSV file of events.
5. **Analyze usage patterns** - Use the CSV to review the data grouped by:
   * `identification.visitor_id`
   * `linked_id` or `tags`
   * `url`
   * `ip_info.geolocation.country_name`

This can help surface unusual usage patterns, like excessive requests from a single user or unexpected geographies.

## Next Steps and Support

* If you can’t resolve the issue on your own, please reach out to [support](https://fingerprint.com/support/).
* You may be eligible for partial [bill forgiveness](/docs/billing#how-am-i-protected-from-overpaying) in cases of unintentional spikes or confirmed malicious activity.

**Important:** Forgiveness can only be applied to your **most recent completed invoice** (i.e. the last completed billing cycle). Older invoices are not eligible, even if they experienced a spike.

***

[Billing and account limits explained](/docs/billing)


# Overview
Source: https://docs.fingerprint.com/docs/using-the-dashboard

A guide to understanding the web-based interface for managing your Fingerprint account.

The Fingerprint Dashboard is the web-based interface for managing your Fingerprint account. It provides a central view of key metrics, configuration settings, and team management.

You can access the dashboard by visiting [**dashboard.fingerprint.com**](https://dashboard.fingerprint.com/).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 41 09@2x" />
</Frame>

The dashboard is optimized for both administrators and data analysts, making it easy to configure your fingerprinting setup and monitor traffic trends.

### Using the Dashboard

* **Manage your account and your team**: The dashboard enables account owners to invite and [assign roles to team members](/docs/roles-permissions), customize granular access permissions across [multiple workspaces](/docs/workspaces-environments), and allows users to manage their [personal profile details](/docs/user-preferences), time zone, and email notifications.
* **Configure resources**: Within each workspace, you [configure essential resources](/docs/configuration), including managing various API keys, setting up [multiple environments](/docs/multiple-environments), implementing security features like [request filtering](/docs/request-filtering) and [custom subdomains](/docs/custom-subdomain-setup) to counter ad blockers, and configuring [webhooks](/docs/webhooks) to securely receive identification data on your server.
* **View analytics**: The dashboard provides [detailed analytics](/docs/analytics) via an Overview page that shows key metrics like API usage, unique visitors, and top detection lists, a Smart Signals page for monitoring specific suspicious indicators, and an Identification page where users can list, extensively filter, export identification events to CSV, and review thorough event details, including suspect scores and visitor history. Additionally you can [monitor health](/docs/health)  of your integration and SDK upgrades via Health page.
* **Analyze bot traffic**: The [Bots & AI agents](/docs/dashboard-bots-ai-agents) section breaks down your automated traffic by category, provider, and identity, and lets you investigate individual AI agent and bot events.

### Navigating the Dashboard

You can navigate the Dashboard by using the sidebar. The sidebar contains:

* **Workspace selector**: switch between different workspaces
* **Get started**: useful instructions if you’re installing Fingerprint for the first time
* **Overview**: insights and charts to stay on top of your traffic
* **Identification**: look up details about specific identification requests
* **Bots & AI agents**: analyze bot and AI agent traffic, and investigate individual automation events
* **Smart Signals**: discover Smart Signal statistics and adjust Suspect Score configuration
* **API keys**: create and manage keys for API access, cloud proxy integrations and encryption
* **Health**: monitor your setup for latency issues or outdated libraries
* **Security**: configure rules to filter out unwanted requests
* **Webhooks**: configure webhooks to receive identification events on your server asynchronously
* **Libraries & Integrations**: manage proxy integrations and libraries
* **Plan & usage**: manage your plan and view usage for the current billing period

The **Settings** page consolidates options relevant to your workspace, account, and personal preferences into one place.

* (Workspace) **General settings**: general workspace settings
* (Workspace) **Environments**: manage your multi-environment setup
* (Workspace) **Subdomains**: manage your subdomains
* (Account) **Workspaces**: manage multiple workspaces
* (Account) **Team**: manage team members
* (Account) **Billing**: manage billing information and payment methods
* (User) **My profile**: manage your user settings
* (User) **My notifications**: manage your notification preferences

In the top-right section of the page, you will find links for easy access to documentation and support.


# Create API key
Source: https://docs.fingerprint.com/reference/2024-05-20-apikeyscontroller_create

reference/management-api_2024-05-20.json POST /api-keys
Creates an API key for the workspace associated with the Management API key. Maximum number of API keys in defined by your plan limits. If you need additional API keys, contact our support team.



# Delete API key
Source: https://docs.fingerprint.com/reference/2024-05-20-apikeyscontroller_deleteapikey

reference/management-api_2024-05-20.json DELETE /api-keys/{id}
Deletes an API key with the given ID. Make sure that the key you are deleting is not used in production environment. This action is not reversible.



# List API keys
Source: https://docs.fingerprint.com/reference/2024-05-20-apikeyscontroller_findall

reference/management-api_2024-05-20.json GET /api-keys
Lists all API keys for the workspace associated with the Management API key.



# Get API key
Source: https://docs.fingerprint.com/reference/2024-05-20-apikeyscontroller_findone

reference/management-api_2024-05-20.json GET /api-keys/{id}
Fetch an API key by ID.



# Update API key
Source: https://docs.fingerprint.com/reference/2024-05-20-apikeyscontroller_update

reference/management-api_2024-05-20.json PATCH /api-keys/{id}
Updates a single API key. You can update the keys name, description, status, and rate limit. You cannot mutate the actual key itself.



# Create environment
Source: https://docs.fingerprint.com/reference/2024-05-20-environmentcontroller_create

reference/management-api_2024-05-20.json POST /environments
Creates a new environment for the workspace associated with the Management API key. Maximum number of environments in defined by your plan limits. If you need additional environments, contact our support team.



# Delete environment
Source: https://docs.fingerprint.com/reference/2024-05-20-environmentcontroller_delete

reference/management-api_2024-05-20.json DELETE /environments/{id}
Deletes an environment with the given environment ID. You can only delete environments that don't have any active API keys associated with it.



# List environments
Source: https://docs.fingerprint.com/reference/2024-05-20-environmentcontroller_findall

reference/management-api_2024-05-20.json GET /environments
Lists all environments for the workspace associated with the Management API key.



# Update environment
Source: https://docs.fingerprint.com/reference/2024-05-20-environmentcontroller_update

reference/management-api_2024-05-20.json POST /environments/{id}
Updates an environment with the given environment ID. You can update the name, description, and limit settings.



# Set filtering rules
Source: https://docs.fingerprint.com/reference/2024-05-20-filteringrulescontroller_create

reference/management-api_2024-05-20.json POST /filtering-rules
Creates or updates filtering rules for an environment in bulk. This action will overwrite any existing filtering rules on specified environment. If there is no filtering rules for an environment, this action creates them. To completely remove filtering rules, set both `allow` and `deny` lists to an empty array (`[]`).
Currently only supports origin domain filtering.

Note: It can take up to 5 minutes to start filtering incoming requests after setting a rule.



# List filtering rules
Source: https://docs.fingerprint.com/reference/2024-05-20-filteringrulescontroller_findall

reference/management-api_2024-05-20.json GET /filtering-rules
Lists all request filtering rules for the workspace associated with the Management API key.



# Mutate filtering rules
Source: https://docs.fingerprint.com/reference/2024-05-20-filteringrulescontroller_update

reference/management-api_2024-05-20.json PATCH /filtering-rules
Allows atomic mutation to filtering rules for an environment. Explicitly specify which list (`allow` or `deny`) you are mutating and which operation (`add` or `remove`) you want to execute with the given list of items.
Currently only supports origin domain filtering.

**Note**: It can take up to 5 minutes to start filtering incoming requests after setting a rule.



# Create webhook
Source: https://docs.fingerprint.com/reference/2024-05-20-webhookscontroller_create

reference/management-api_2024-05-20.json POST /webhooks
Creates a new webhook in the workspace associated with the Management API key.
Webhook needs to be verified before it will start sending identification events to your server. See webhook verification.
If webhook signatures are enabled (enterprise only), signing key will be visible in the response after creation. When fetching webhooks after creation, signing key will not be visible!
See webhooks documentation for more details.
When specifying an environment during creation, webhook should be assigned to the given environment. Setting environment to null creates a global webhook.



# List webhooks
Source: https://docs.fingerprint.com/reference/2024-05-20-webhookscontroller_findall

reference/management-api_2024-05-20.json GET /webhooks
Lists all webhooks associated to the Management API key, optionally filtered by status.



# Get webhook by ID
Source: https://docs.fingerprint.com/reference/2024-05-20-webhookscontroller_findone

reference/management-api_2024-05-20.json GET /webhooks/{id}
Fetch a specific webhook by ID.



# Delete webhook
Source: https://docs.fingerprint.com/reference/2024-05-20-webhookscontroller_remove

reference/management-api_2024-05-20.json DELETE /webhooks/{id}
Deletes the webhook with the given ID. This action is not reversible. Changes will take affect in a few minutes.



# Update webhook
Source: https://docs.fingerprint.com/reference/2024-05-20-webhookscontroller_update

reference/management-api_2024-05-20.json PATCH /webhooks/{id}
Updates the webhook with the given ID. You can update the name, description, status, URL, and set basic authentication.
Changing the URL will require this webhook to be verified again.
Changing the status will disable/enable sending of identification events to your webhook.



# Verify webhook
Source: https://docs.fingerprint.com/reference/2024-05-20-webhookscontroller_verify

reference/management-api_2024-05-20.json POST /webhooks/{id}/verification
Send a test event in order to verify your webhook endpoint, it needs to respond with HTTP 200 to be verified.
Webhook needs to be verified before it will receive identification events.



# List encryption keys
Source: https://docs.fingerprint.com/reference/encryptionkeyscontroller_findall

reference/management-api_2025-11-20.json GET /encryption-keys
Lists all encryption keys for the workspace associated with the Management API key.



# Get encryption key
Source: https://docs.fingerprint.com/reference/encryptionkeyscontroller_findone

reference/management-api_2025-11-20.json GET /encryption-keys/{id}
Fetch an encryption key by ID.



# Revert encryption key rotation
Source: https://docs.fingerprint.com/reference/encryptionkeyscontroller_revert

reference/management-api_2025-11-20.json POST /encryption-keys/{id}/revert
Reverts the last encryption key rotation.



# Rotate encryption key
Source: https://docs.fingerprint.com/reference/encryptionkeyscontroller_rotate

reference/management-api_2025-11-20.json POST /encryption-keys/{id}/rotate



# Update encryption key
Source: https://docs.fingerprint.com/reference/encryptionkeyscontroller_update

reference/management-api_2025-11-20.json PATCH /encryption-keys/{id}
Updates a single encryption key. You can update the keys name, description, and status. You cannot mutate the actual key itself.



# Delete filtering rule
Source: https://docs.fingerprint.com/reference/filteringrulesv2controller_delete

reference/management-api_2025-11-20.json DELETE /filtering-rules/{id}
Deletes a filtering rule with the given ID. Make sure the rule is not critical for your production environment. This action is not reversible.



# Test filtering rules
Source: https://docs.fingerprint.com/reference/filteringrulesv2controller_test

reference/management-api_2025-11-20.json POST /filtering-rules/test
Tests filtering rules against a specified request ID or custom event payload. You can provide an existing request ID (up to 3 months old) or a custom JSON payload. Optionally, you can provide custom rules to test instead of using existing rules.



# Go Server SDK
Source: https://docs.fingerprint.com/reference/go-server-sdk

The [Fingerprint Server Go SDK](https://github.com/fingerprintjs/go-sdk) is an easy way to interact with our Server API from your Go application. You can retrieve visitor history or individual identification events. View our [Go Server SDK quickstart](/docs/go-server-quickstart) for a step-by-step guide to get started.

## How to install

Get the package from GitHub using `go get`.

```bash Bash theme={"theme":"github-dark-dimmed"}
go get github.com/fingerprintjs/go-sdk/v8
```

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region (if it is not US/Global).

```go Go theme={"theme":"github-dark-dimmed"}
package main

import (
  "context"
  "fmt"
  "log"

  "github.com/fingerprintjs/go-sdk/v8"
)

func main() {
  client := fingerprint.New(
    fingerprint.WithAPIKey("SECRET_API_KEY"),
    // fingerprint.WithRegion(fingerprint.RegionEU),
  )

  // Search events, for example, by Visitor ID
  searchEventsOpts := fingerprint.NewSearchEventsRequest().
    VisitorID("VISITOR_ID").
    Limit(10)

  searchEventsResult, searchEventsHttpRes, searchErr :=
    client.SearchEvents(context.Background(), searchEventsOpts)
  if searchErr != nil {
    if errResp, ok := fingerprint.AsErrorResponse(searchErr); ok {
      log.Printf("Error %s: %v", errResp.Error.Code, errResp)
    }
    log.Fatal(searchErr)
  }
  fmt.Printf("Search events result: %v", searchEventsResult)
  fmt.Printf("Search events response: %v", searchEventsHttpRes)

  // Get a specific identification event
  event, eventHttpRes, eventErr :=
    client.GetEvent(context.Background(), "EVENT_ID")
  if eventErr != nil {
    if errResp, ok := fingerprint.AsErrorResponse(eventErr); ok {
      switch errResp.Error.Code {
      case fingerprint.ErrorCodeEventNotFound:
        log.Fatalf("Event not found")
      default:
        log.Printf("Error %s: %v", errResp.Error.Code, errResp)
      }
    }
    log.Fatal(eventErr)
  }
  fmt.Printf("Event: %v", event)
  fmt.Printf("Event response: %v", eventHttpRes)
}
```

## Migration guide for Go SDK v8

Version 8 migrates the SDK from Server API v3 to v4. This is a breaking change.

This section summarizes the most important changes from previous versions.

### Module rename

The module path changed from `github.com/fingerprintjs/fingerprint-pro-server-api-go-sdk/v7` to `github.com/fingerprintjs/go-sdk/v8`.

```bash Bash theme={"theme":"github-dark-dimmed"}
go get github.com/fingerprintjs/fingerprint-pro-server-api-go-sdk/v7 # [!code --]
go get github.com/fingerprintjs/go-sdk/v8 # [!code ++]
```

```go Go theme={"theme":"github-dark-dimmed"}
import "github.com/fingerprintjs/fingerprint-pro-server-api-go-sdk/v7/sdk" // [!code --]
import "github.com/fingerprintjs/go-sdk/v8" // [!code ++]
```

<Info>
  The v7 and v8
  modules can be
  used side-by-side
  if you would like
  to migrate your
  codebase to the
  new version in
  stages.
</Info>

### Client construction

In v7, you created a context to pass your API key.
In v8, you pass the API key when you create the client.

```go Go theme={"theme":"github-dark-dimmed"}
cfg := sdk.NewConfiguration() // [!code --]
client := sdk.NewAPIClient(cfg) // [!code --]
ctxWithAuth := context.WithValue(context.Background(), sdk.ContextAPIKey, sdk.APIKey{Key: "SECRET_API_KEY"}) // [!code --]
client.FingerprintApi.GetEvent(ctxWithAuth, "EVENT_ID") // [!code --]
client := fingerprint.New( // [!code ++]
  fingerprint.WithAPIKey("SECRET_API_KEY"), // [!code ++]
) // [!code ++]
client.GetEvent(context.Background(), "EVENT_ID") // [!code ++]

```

### Get an event

`GetEvent` is now a method on the client, rather than nested in the `FingerprintAPI` interface, and returns `*fingerprint.Event` instead of `EventsGetResponse`.

The event data structure is flatter. For example, the ID of the event, previously called the request ID, is now available at the top level as `EventID`, and identification fields moved from `Products.Identification.Data` to the top level.

```go Go theme={"theme":"github-dark-dimmed"}
resp, _, err := client.FingerprintApi.GetEvent(ctx, "EVENT_ID") // [!code --]
requestID := resp.Products.Identification.Data.RequestId // [!code --]
visitorID := resp.Products.Identification.Data.VisitorId // [!code --]
event, _, err := client.GetEvent(context.Background(), "EVENT_ID") // [!code ++]
eventID := event.EventID // [!code ++]
visitorID := event.Identification.VisitorID // [!code ++]
```

### Search events

`SearchEvents` uses a builder to construct the request rather than positional arguments and an options struct.

```go Go theme={"theme":"github-dark-dimmed"}
linkedID := "LINKED_ID"
resp, _, err := client.FingerprintApi.SearchEvents(ctx, 10, &sdk.FingerprintApiSearchEventsOpts{ // [!code --]
  LinkedId: &linkedID, // [!code --]
}) // [!code --]
req := fingerprint.NewSearchEventsRequest().Limit(10).LinkedID("LINKED_ID") // [!code ++]
resp, _, err := client.SearchEvents(context.Background(), req) // [!code ++]
```

### `GetVisits` replaced by `SearchEvents`

`GetVisits` has been removed. Use `SearchEvents` with `VisitorID` to query a visitor's history.

```go Go theme={"theme":"github-dark-dimmed"}
resp, _, err := client.FingerprintApi.GetVisits(ctx, "VISITOR_ID") // [!code --]
req := fingerprint.NewSearchEventsRequest().VisitorID("VISITOR_ID") // [!code ++]
resp, _, err := client.SearchEvents(context.Background(), req) // [!code ++]
```

### Sealed results

`UnsealEventsResponse` is now part of the main `fingerprint` package instead of a separate `sealed` subpackage.

```go Go theme={"theme":"github-dark-dimmed"}
events, err := sealed.UnsealEventsResponse(sealedData, []sealed.DecryptionKey{ // [!code --]
  {Key: key, Algorithm: sealed.AlgorithmAES256GCM}, // [!code --]
}) // [!code --]
events, err := fingerprint.UnsealEventsResponse(sealedData, []fingerprint.DecryptionKey{ // [!code ++]
  {Key: key, Algorithm: fingerprint.AlgorithmAES256GCM}, // [!code ++]
}) // [!code ++]
```

### Error handling

Use `fingerprint.AsErrorResponse` to inspect errors.
It returns a structured response with `Error.Code` and `Error.Message`.
SDK calls also return an `*http.Response`, which you can read to use the raw response body when handling errors.

```go Go theme={"theme":"github-dark-dimmed"}
var apiErr sdk.ApiError // [!code --]
if errors.As(err, &apiErr) { // [!code --]
  log.Printf("Error %s: %v", apiErr.Code(), apiErr.Error()) // [!code --]
} // [!code --]
if errResp, ok := fingerprint.AsErrorResponse(err); ok { // [!code ++]
  log.Printf("Error %s: %s", errResp.Error.Code, errResp.Error.Message) // [!code ++]
} // [!code ++]
```

### Handling sealed client results from a v3 JavaScript agent

Go SDK v8 will fail to deserialize the decrypted payload of a [sealed client result](/docs/sealed-client-results) sent by a v3 JavaScript agent into an `Event` because the payload is an `EventsGetResponse` (i.e., the v3 event format), not an `Event`.

To upgrade to Go SDK v8 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails.
To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the [sealed client results guide](/docs/sealed-client-results#step-3-send-sealed_result-to-your-backend).

```go Go theme={"theme":"github-dark-dimmed"}
// Partial example (imports omitted).
func getEvent(
  client *fingerprint.Client,
  sealedResult []byte,
  eventID string,
  keys []fingerprint.DecryptionKey,
) (*fingerprint.Event, error) {
  // First, decrypt the sealed results
  sealedResultPayload, err := fingerprint.Unseal(sealedResult, keys)
  if err != nil {
    return nil, err
  }

  // Next, attempt to deserialize the payload into an event
  var sealedResultEvent fingerprint.Event
  err = json.Unmarshal(sealedResultPayload, &sealedResultEvent)
  if err == nil {
    return &sealedResultEvent, nil
  }

  // Deserialization failed. Fall back to the Server API using the event ID
  // sent alongside the client sealed results.
  log.Printf("Could not deserialize unsealed payload as a v4 Event, falling back to Server API: %v", err)
  serverAPIEvent, _, err := client.GetEvent(context.Background(), eventID)
  return serverAPIEvent, err
}
```

## Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/go-sdk). The repository also contains [an example app](https://github.com/fingerprintjs/go-sdk/tree/main/example) demonstrating the usage of the library.


# Java Server SDK
Source: https://docs.fingerprint.com/reference/java-server-sdk

The [Fingerprint Server Java SDK](https://github.com/fingerprintjs/java-sdk) is an easy way to interact with our Server API from your Java application. You can retrieve and manage identification events. View our [Java Server SDK quickstart](/docs/java-server-quickstart) for a step-by-step guide to get started.

## How to install

### Using Maven

Add this dependency to your project's POM:

```xml XML theme={"theme":"github-dark-dimmed"}
<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>
```

```xml XML theme={"theme":"github-dark-dimmed"}
<dependency>
  <groupId>com.github.fingerprintjs</groupId>
  <artifactId>java-sdk</artifactId>
  <version>v8.7.0</version>
</dependency>
```

### Using Gradle

Add this dependency to your project's build file:

```groovy Groovy theme={"theme":"github-dark-dimmed"}
// build.gradle
repositories {
  maven { url 'https://jitpack.io' }
}

dependencies {
  implementation "com.github.fingerprintjs:java-sdk:v8.7.0"
}
```

```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
// build.gradle.kts
repositories {
  maven {
    url = uri("https://jitpack.io")
  }
}

dependencies {
  implementation("com.github.fingerprintjs:java-sdk:v8.7.0")
}
```

### Others

Generate the JAR file:

```bash Bash theme={"theme":"github-dark-dimmed"}
./gradlew jar
```

Then manually install `sdk/build/libs/java-sdk-8.7.0.jar`.

## Usage

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region (if it is not US/Global).

```java Java theme={"theme":"github-dark-dimmed"}
import com.fingerprint.v4.api.FingerprintApi;
import com.fingerprint.v4.model.Event;
import com.fingerprint.v4.model.EventSearch;
import com.fingerprint.v4.sdk.ApiClient;
import com.fingerprint.v4.sdk.ApiException;
import com.fingerprint.v4.sdk.Configuration;
import com.fingerprint.v4.sdk.Region;

public class FingerprintApiExample {
  public static void main(String... args) {
    ApiClient client = Configuration.getDefaultApiClient(
      "SECRET_API_KEY",
      Region.GLOBAL
      // Region.EUROPE
      // Region.ASIA
    );
    FingerprintApi api = new FingerprintApi(client);

    // Search events for a specific visitor
    try {
      EventSearch response = api.searchEvents(
        new FingerprintApi.SearchEventsOptionalParams()
          .setVisitorId("VISITOR_ID")
          .setLimit(10)
      );
      System.out.println(response.getEvents());
    } catch (ApiException e) {
      System.err.println(e.getMessage());
    }

    // Get a specific identification event
    try {
      Event event = api.getEvent("EVENT_ID");
      System.out.println(event.getIdentification().getVisitorId());
    } catch (ApiException e) {
      System.err.println(e.getMessage());
    }
  }
}
```

## Migration guide for Java SDK v8

Version 8 migrates the SDK from Server API v3 to v4. This is a breaking change.

### Package rename

The artifact ID changed from `fingerprint-pro-server-api-java-sdk` to `java-sdk`. All import paths changed from `com.fingerprint.*` to `com.fingerprint.v4.*`.

**Gradle (build.gradle):**

```groovy Groovy theme={"theme":"github-dark-dimmed"}
implementation "com.github.fingerprintjs:fingerprint-pro-server-api-java-sdk:v7.x.x" // [!code --]
implementation "com.github.fingerprintjs:java-sdk:v8.7.0" // [!code ++]
```

### Import changes

All imports change from `com.fingerprint.*` to `com.fingerprint.v4.*`:

```java Java theme={"theme":"github-dark-dimmed"}
import com.fingerprint.api.FingerprintApi; // [!code --]
import com.fingerprint.model.EventsGetResponse; // [!code --]
import com.fingerprint.sdk.ApiClient; // [!code --]
import com.fingerprint.sdk.Configuration; // [!code --]
import com.fingerprint.sdk.Region; // [!code --]
import com.fingerprint.v4.api.FingerprintApi; // [!code ++]
import com.fingerprint.v4.model.Event; // [!code ++]
import com.fingerprint.v4.sdk.ApiClient; // [!code ++]
import com.fingerprint.v4.sdk.Configuration; // [!code ++]
import com.fingerprint.v4.sdk.Region; // [!code ++]
```

### `getEvent` return type

`getEvent` now returns `Event` instead of `EventsGetResponse`. The event object has a flatter structure. Smart Signals are now top-level fields instead of nested under `products`:

```java Java theme={"theme":"github-dark-dimmed"}
EventsGetResponse response = api.getEvent("EVENT_ID"); // [!code --]
String visitorId = response.getProducts().getIdentification().getData().getVisitorId(); // [!code --]
BotdBotResult botResult = response.getProducts().getBotd().getData().getBot().getResult(); // [!code --]
Event event = api.getEvent("EVENT_ID"); // [!code ++]
String visitorId = event.getIdentification().getVisitorId(); // [!code ++]
BotResult botResult = event.getBot(); // [!code ++]
```

### `getVisits` replaced by `searchEvents`

`getVisits` and `getRelatedVisitors` have been removed. Use `searchEvents` to query visitor history:

```java Java theme={"theme":"github-dark-dimmed"}
VisitorsGetResponse response = api.getVisits("VISITOR_ID"); // [!code --]
EventSearch response = api.searchEvents( // [!code ++]
  new FingerprintApi.SearchEventsOptionalParams() // [!code ++]
    .setVisitorId("VISITOR_ID") // [!code ++]
    .setLimit(10) // [!code ++]
); // [!code ++]
```

### Handling sealed client results from a v3 JavaScript agent

Java SDK v8 will fail to deserialize the decrypted payload of a [sealed client result](/docs/sealed-client-results) sent by a v3 JavaScript agent into an `Event` because the payload is an `EventsGetResponse` (the v3 event format), not an `Event`.

To upgrade to Java SDK v8 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails.
To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the [sealed client results guide](/docs/sealed-client-results#step-3-send-sealed_result-to-your-backend).

Both `Sealed.unsealEventResponse` and `api.getEvent` return an `Event`, so the fallback returns the same type.

```java Java theme={"theme":"github-dark-dimmed"}
// Partial example (imports and surrounding class omitted).
private static Event getEvent(
  FingerprintApi api,
  byte[] sealedResult,
  String eventId,
  Sealed.DecryptionKey[] keys
) throws ApiException {
  // Try to unseal the payload locally first.
  try {
    return Sealed.unsealEventResponse(sealedResult, keys);
  } catch (InvalidSealedDataException e) {
    // Deserialization failed. Fall back to the Server API using the event ID
    // sent alongside the sealed client results.
    System.out.println("Could not unseal result, falling back to Server API: " + e);
    return api.getEvent(eventId);
  }
}
```

## Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/java-sdk/).


# .NET Server SDK
Source: https://docs.fingerprint.com/reference/net-server-sdk

The [Fingerprint Server C#/.NET SDK](https://github.com/fingerprintjs/dotnet-sdk) is an easy way to interact with our Server API from your .NET application. You can retrieve visitor history or individual identification events. View our [.NET Server SDK quickstart](/docs/dotnet-server-quickstart) for a step-by-step guide to get started.

## How to install

Install the package from NuGet.

```bash Bash theme={"theme":"github-dark-dimmed"}
dotnet add package Fingerprint.ServerSdk
```

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region (if it is not US/Global).

```csharp C# theme={"theme":"github-dark-dimmed"}
using Fingerprint.ServerSdk.Api;
using Fingerprint.ServerSdk.Extensions;
using Fingerprint.ServerSdk.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFingerprint(options =>
{
    options.AddTokens(new BearerToken("SECRET-API-KEY"));
    // options.Region = Region.Eu;
});

var app = builder.Build();
var api = app.Services.GetRequiredService<IFingerprintApi>();

// Search events
var events = await api.SearchEventsAsync(new SearchEventsRequest().WithVisitorId("VISITOR_ID"));
Console.WriteLine(events.Ok());

// Get a specific identification event
var getEvent = await api.GetEventAsync("EVENT_ID");
Console.WriteLine(getEvent.Ok());
```

## Migration guide for .NET SDK v8

Version 8 migrates the SDK from Server API v3 to v4. This is a breaking change.

This section summarizes the most important changes from previous versions.

### Package and namespace rename

The package name changed from `FingerprintPro.ServerSdk` to `Fingerprint.ServerSdk`, and all namespaces changed from `FingerprintPro.ServerSdk.*` to `Fingerprint.ServerSdk.*`.

```html Project.csproj theme={"theme":"github-dark-dimmed"}
<!-- [!code --] -->
<PackageReference Include="FingerprintPro.ServerSdk" Version="7.11.0" />
<!-- [!code ++] -->
<PackageReference Include="Fingerprint.ServerSdk" Version="8.4.0" />
```

```csharp C# theme={"theme":"github-dark-dimmed"}
using FingerprintPro.ServerSdk.Api; // [!code --]
using FingerprintPro.ServerSdk.Client; // [!code --]
using FingerprintPro.ServerSdk.Model; // [!code --]
using Fingerprint.ServerSdk.Api; // [!code ++]
using Fingerprint.ServerSdk.Client; // [!code ++]
using Fingerprint.ServerSdk.Model; // [!code ++]
```

### Client construction

In v7, you created a `Configuration` object and passed it to a `FingerprintApi` constructor. In v8, you register a service on a `generichost` builder with `AddFingerprint` and resolve it as `IFingerprintApi`.

```csharp C# theme={"theme":"github-dark-dimmed"}
var configuration = new Configuration("SECRET_API_KEY"); // [!code --]
// configuration.Region = Region.Eu; // [!code --]
var api = new FingerprintApi(configuration); // [!code --]
var builder = WebApplication.CreateBuilder(args); // [!code ++]
builder.Services.AddFingerprint(options => // [!code ++]
{ // [!code ++]
    options.AddTokens(new BearerToken("SECRET_API_KEY")); // [!code ++]
    // options.Region = Region.Eu; // [!code ++]
}); // [!code ++]
var app = builder.Build(); // [!code ++]
var api = app.Services.GetRequiredService<IFingerprintApi>(); // [!code ++]
```

### Async methods and response objects

All API methods are now asynchronous and return a response object instead of the deserialized model directly. Use `IsOk` and `Ok()` to access the result, or the `TryOk` helper.

```csharp C# theme={"theme":"github-dark-dimmed"}
var ev = api.GetEvent("REQUEST_ID"); // [!code --]
var response = await api.GetEventAsync("EVENT_ID"); // [!code ++]
if (response.IsOk) // [!code ++]
{ // [!code ++]
    var ev = response.Ok(); // [!code ++]
} // [!code ++]
```

### `requestId` renamed to `eventId`

Server API v4 renamed the `request_id` parameter to `event_id`, so the identifier passed to `GetEventAsync` and `UpdateEventAsync` is now called `eventId`.

```csharp C# theme={"theme":"github-dark-dimmed"}
var response = await api.GetEventAsync(requestId: "REQUEST_ID"); // [!code --]
var response = await api.GetEventAsync(eventId: "EVENT_ID"); // [!code ++]
```

### Event structure

`GetEventAsync` returns an `Event` with a flatter structure. The data that was previously nested under `Products.<signal>.Data` is now available at the top level.

```csharp C# theme={"theme":"github-dark-dimmed"}
EventsGetResponse response = api.GetEvent("REQUEST_ID"); // [!code --]
var visitorId = response.Products.Identification.Data.VisitorId; // [!code --]
var botResult = response.Products.Botd.Data.Bot.Result; // [!code --]
Event ev = (await api.GetEventAsync("EVENT_ID")).Ok(); // [!code ++]
var visitorId = ev.Identification.VisitorId; // [!code ++]
var botResult = ev.Bot; // [!code ++]
```

### Search events

`SearchEventsAsync` takes a `SearchEventsRequest` builder instead of positional and named arguments.

```csharp C# theme={"theme":"github-dark-dimmed"}
var response = api.SearchEvents(10, bot: "bad", visitorId: "VISITOR_ID"); // [!code --]
var request = new SearchEventsRequest() // [!code ++]
    .WithLimit(10) // [!code ++]
    .WithBot(SearchEventsBot.Bad) // [!code ++]
    .WithVisitorId("VISITOR_ID"); // [!code ++]
var response = await api.SearchEventsAsync(request); // [!code ++]
```

### `GetVisits` and `GetRelatedVisitors` removed

`GetVisits` and `GetRelatedVisitors` have been removed. Use `SearchEventsAsync` with `WithVisitorId` to get the events for a visitor.

```csharp C# theme={"theme":"github-dark-dimmed"}
var visits = api.GetVisits("VISITOR_ID"); // [!code --]
var request = new SearchEventsRequest().WithVisitorId("VISITOR_ID"); // [!code ++]
var response = await api.SearchEventsAsync(request); // [!code ++]
```

### Handling sealed client results from a v3 JavaScript agent

.NET SDK v8 will fail to deserialize the decrypted payload of a [sealed client result](/docs/sealed-client-results) sent by a v3 JavaScript agent into an `Event` because the payload is an `EventsGetResponse` (i.e., the v3 event format), not an `Event`.

To upgrade to .NET SDK v8 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails.
To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the [sealed client results guide](/docs/sealed-client-results#step-3-send-sealed_result-to-your-backend).

Instead of `Sealed.UnsealEventResponse`, which decrypts and deserializes in one call, use `Sealed.Unseal` to decrypt the payload and then deserialize it into an `Event` separately. This lets you detect a deserialization failure and fall back to the Server API, which also returns an `Event`.

```csharp C# theme={"theme":"github-dark-dimmed"}
// Partial example (imports and surrounding class omitted).
private static async Task<Event> GetEvent(
    IFingerprintApi api,
    byte[] sealedResult,
    string eventId,
    Sealed.DecryptionKey[] keys)
{
    // First, decrypt the sealed results.
    var payload = Sealed.Unseal(sealedResult, keys);

    // Next, attempt to deserialize the payload into an event.
    try
    {
        var ev = JsonSerializer.Deserialize<Event>(payload);
        if (ev == null)
        {
            throw new JsonException("Deserialized event was null");
        }
        return ev;
    }
    catch (JsonException)
    {
        // The payload could not be deserialized as a v4 Event. Fall back to the
        // Server API using the event ID sent alongside the sealed client results.
        Console.WriteLine("Could not deserialize unsealed payload as a v4 Event, falling back to Server API");
        var response = await api.GetEventAsync(eventId);
        return response.Ok();
    }
}
```

## Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/dotnet-sdk/).


# Node Server SDK
Source: https://docs.fingerprint.com/reference/node-server-sdk

The [Fingerprint Server Node SDK](https://github.com/fingerprintjs/node-sdk) is an easy way to interact with our Server API from your Node application. You can retrieve visitor history or individual identification events. View our [Node Server SDK quickstart](/docs/node-server-quickstart) for a step-by-step guide to get started.

## How to install

Add `@fingerprint/node-sdk` as a dependency to your application via npm, yarn, or pnpm.

<CodeGroup>
  ```bash npm theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/node-sdk
  ```

  ```bash yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/node-sdk
  ```

  ```bash pnpm theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/node-sdk
  ```
</CodeGroup>

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

const client = new FingerprintServerApiClient({
  apiKey: "SECRET_API_KEY",
  region: Region.Global,
});

// Search events for a specific visitor
client.searchEvents({ visitor_id: "VISITOR_ID" }).then((events) => {
  console.log(events);
});

// Get a specific identification event
client.getEvent("EVENT_ID").then((event) => {
  console.log(event);
});
```

## Migration guide for Node SDK v7

Version 7 migrates the SDK from Server API v3 to v4. This is a breaking change.

This section summarizes the most important changes from previous versions.

### Package rename

The package changed from `@fingerprintjs/fingerprintjs-pro-server-api` to `@fingerprint/node-sdk`.

<CodeGroup>
  ```bash npm theme={"theme":"github-dark-dimmed"}
  npm install @fingerprintjs/fingerprintjs-pro-server-api # [!code --]
  npm install @fingerprint/node-sdk # [!code ++]
  ```

  ```bash yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprintjs/fingerprintjs-pro-server-api # [!code --]
  yarn add @fingerprint/node-sdk # [!code ++]
  ```

  ```bash pnpm theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprintjs/fingerprintjs-pro-server-api # [!code --]
  pnpm add @fingerprint/node-sdk # [!code ++]
  ```
</CodeGroup>

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
import { FingerprintJsServerApiClient } from "@fingerprintjs/fingerprintjs-pro-server-api"; // [!code --]
import { FingerprintServerApiClient } from "@fingerprint/node-sdk"; // [!code ++]
```

### Client construction

The client class was renamed from `FingerprintJsServerApiClient` to `FingerprintServerApiClient`, and the `authenticationMode` option was removed.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
const client = new FingerprintJsServerApiClient({ // [!code --]
const client = new FingerprintServerApiClient({ // [!code ++]
  apiKey: "SECRET_API_KEY",
  region: Region.Global,
  authenticationMode: AuthenticationMode.AuthHeader, // [!code --]
});
```

### Get an event

`requestId` is now called the event ID, and the event data structure is flatter.
Response fields are now `snake_case`, and identification and Smart Signals data moved from `products.<signal>.data` to the top level.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
const event = await client.getEvent("EVENT_ID");
console.log(event.products.identification.data.visitorId); // [!code --]
console.log(event.identification.visitor_id); // [!code ++]
```

### `getVisits` replaced by `searchEvents`

`getVisits()` and `getRelatedVisitors()` have been removed. Use `searchEvents` with `visitor_id` to get the events for a visitor.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
const history = await client.getVisits("VISITOR_ID", { limit: 10 }); // [!code --]
const history = await client.searchEvents({ visitor_id: "VISITOR_ID", limit: 10 }); // [!code ++]
```

### Update an event

The `updateEvent` parameter order changed from `(body, eventId)` to `(eventId, body)`, and the `tag` field was renamed to `tags`.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
await client.updateEvent( // [!code --]
  { // [!code --]
    tag: { key: "value" }, // [!code --]
    linkedId: "new_linked_id", // [!code --]
    suspect: false, // [!code --]
  }, // [!code --]
  "EVENT_ID" // [!code --]
); // [!code --]
await client.updateEvent("EVENT_ID", { // [!code ++]
  tags: { key: "value" }, // [!code ++]
  linked_id: "new_linked_id", // [!code ++]
  suspect: false, // [!code ++]
}); // [!code ++]
```

### Handling sealed client results from a v3 JavaScript agent

Node SDK v7 will fail to deserialize the decrypted payload of a [sealed client result](/docs/sealed-client-results) sent by a v3 JavaScript agent into an `Event` because the payload is an `EventsGetResponse` (i.e., the v3 event format), not an `Event`.

To upgrade to Node SDK v7 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails.
To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the [sealed client results guide](/docs/sealed-client-results#step-3-send-sealed_result-to-your-backend).

Both `unsealEventsResponse` and `client.getEvent` return an `Event`, so the fallback returns the same type.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
import { DecryptionKey, Event, FingerprintServerApiClient, UnsealAggregateError, unsealEventsResponse } from "@fingerprint/node-sdk";

async function getEvent(
  client: FingerprintServerApiClient,
  sealedResult: Buffer,
  eventId: string,
  keys: DecryptionKey[]
): Promise<Event> {
  try {
    // Try to unseal the payload locally first.
    return await unsealEventsResponse(sealedResult, keys);
  } catch (error) {
    if ( !(error instanceof UnsealAggregateError) ) {
      // Deserialization failed. Fall back to the Server API using
      // the event ID sent alongside the sealed client results.
      console.log("Could not unseal result, falling back to Server API:", error);
      return client.getEvent(eventId);
    }

    // Re-throw unsealing errors
    throw error;
  }
}
```

## Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/node-sdk).


# OpenAPI Schema
Source: https://docs.fingerprint.com/reference/openapi-schema

[OpenAPI Specification](https://swagger.io/docs/specification/about/) (formerly *Swagger Specification*) is an API description format for REST APIs. With the open-source Fingerprint Server API and Webhooks [OpenAPI schemas](https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi), you can integrate Fingerprint's [Server API](/reference/server-api) and [Webhooks](/reference/posteventwebhook) into your server.

A [visual Swagger UI](https://swagger.io/tools/swagger-ui/) representation of the OpenAPI schema can be found on the [Getting Started page](https://fingerprintjs.github.io/fingerprint-pro-server-api-openapi/) on GitHub.
The latest version of the schema is published on [GitHub](https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi/blob/main/schemas/fingerprint-server-api-v4.yaml).
Our OpenAPI schema conforms to [OpenAPI Specification version 3.1.1](https://spec.openapis.org/oas/v3.1.1.html).

## Webhooks Specification

The OpenAPI Specification supports Fingerprint Webhooks with its [*webhooks* feature](https://spec.openapis.org/oas/v3.1.1.html#oas-webhooks).

## Server API Specification

The Server API supports `Bearer` token authentication, using the standard `Bearer` format: `Authorization: Bearer YOUR_SECRET_API_KEY`.


# PHP Server SDK
Source: https://docs.fingerprint.com/reference/php-server-sdk

The PHP Server SDK is an easy way to interact with our Server API from your PHP application. You can retrieve visitor history or individual identification events. View our [PHP Server SDK quickstart](/docs/php-server-quickstart) for a step-by-step guide to get started.

## How to install

Add the package to your `composer.json` file as a dependency:

```bash Bash theme={"theme":"github-dark-dimmed"}
composer require fingerprint/server-sdk
```

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region (if it is not US/Global).

```php PHP theme={"theme":"github-dark-dimmed"}
<?php

require_once(__DIR__ . '/vendor/autoload.php');

use Fingerprint\ServerSdk\Api\FingerprintApi;
use Fingerprint\ServerSdk\Configuration;

$config = new Configuration(
  "SECRET_API_KEY",
  // Configuration::REGION_EUROPE
);
$client = new FingerprintApi($config);

// Search events, for example, by visitor ID
try {
  $events = $client->searchEvents(10, visitor_id: "VISITOR_ID");
  print_r($events);
} catch (Exception $e) {
  echo $e->getMessage(), PHP_EOL;
}

// Get a specific identification event
try {
  $event = $client->getEvent("EVENT_ID");
  print_r($event);
} catch (Exception $e) {
  echo $e->getMessage(), PHP_EOL;
}
```

## Migration guide for PHP SDK v7

Version 7 migrates the SDK from Server API v3 to v4. This is a breaking change.

This section summarizes the most important changes from previous versions.

PHP SDK v7 requires PHP 8.2 or higher. Support for PHP 8.1 has been dropped.

### Package and namespace rename

The Composer package changed from `fingerprint/fingerprint-pro-server-api-sdk` to `fingerprint/server-sdk`, and the namespace changed from `Fingerprint\ServerAPI` to `Fingerprint\ServerSdk`.

```json composer.json theme={"theme":"github-dark-dimmed"}
"require": {
  "fingerprint/fingerprint-pro-server-api-sdk": "^6.10.0" // [!code --]
  "fingerprint/server-sdk": "^7.0.0" // [!code ++]
}
```

Update all `use` statements to the new namespace:

```php PHP theme={"theme":"github-dark-dimmed"}
use Fingerprint\ServerAPI\Configuration; // [!code --]
use Fingerprint\ServerSdk\Configuration; // [!code ++]
```

### Client construction

The API key is now required in the `Configuration` constructor. `Configuration::getDefaultConfiguration()` and `setDefaultConfiguration()` have been removed. The `FingerprintApi` constructor also takes the configuration as its first argument, with the optional HTTP client second.

```php PHP theme={"theme":"github-dark-dimmed"}
$config = Configuration::getDefaultConfiguration("SECRET_API_KEY", Configuration::REGION_EUROPE); // [!code --]
$client = new FingerprintApi($httpClient, $config); // [!code --]
$config = new Configuration("SECRET_API_KEY", Configuration::REGION_EUROPE); // [!code ++]
$client = new FingerprintApi($config, $httpClient); // [!code ++]
// OR if you are using the default HTTP client // [!code ++]
$client = new FingerprintApi($config); // [!code ++]
```

### Get an event

The `getEvent` parameter `$request_id` is now `$event_id`, and the method returns an `Event` instead of a `list($event, $response)` tuple. The event data structure is flatter: fields are accessed directly instead of through the `products` wrapper.

```php PHP theme={"theme":"github-dark-dimmed"}
list($event, $response) = $client->getEvent(request_id: "REQUEST_ID"); // [!code --]
$visitorId = $event->getProducts()->getIdentification()->getData()->getVisitorId(); // [!code --]
$event = $client->getEvent(event_id: "EVENT_ID"); // [!code ++]
$visitorId = $event->getIdentification()->getVisitorId(); // [!code ++]
```

If you need the raw HTTP response, use the `WithHttpInfo` variant. Every operation now exposes `{operation}()`, `{operation}WithHttpInfo()`, `{operation}Async()`, and `{operation}AsyncWithHttpInfo()` methods.

```php PHP theme={"theme":"github-dark-dimmed"}
list($event, $response) = $client->getEvent("REQUEST_ID"); // [!code --]
list($event, $response) = $client->getEventWithHttpInfo("EVENT_ID"); // [!code ++]
```

### Search events

`searchEvents` now returns an `EventSearch` object instead of an array.

```php PHP theme={"theme":"github-dark-dimmed"}
list($events, $response) = $client->searchEvents(10, visitor_id: "VISITOR_ID"); // [!code --]
$events = $client->searchEvents(limit: 10, visitor_id: "VISITOR_ID"); // [!code ++]
```

### `getVisits` and `getRelatedVisitors` replaced by `searchEvents`

`getVisits` and `getRelatedVisitors` have been removed.
Use `searchEvents` with the `visitor_id` to find the events for a particular visitor.

```php PHP theme={"theme":"github-dark-dimmed"}
list($visits, $response) = $client->getVisits("VISITOR_ID"); // [!code --]
$events = $client->searchEvents(limit: 10, visitor_id: "VISITOR_ID"); // [!code ++]
```

### Update an event

`updateEvent` now takes the event ID first and an `EventUpdate` body second, returns `void` instead of an array, and issues a `PATCH` request instead of `PUT`.

```php PHP theme={"theme":"github-dark-dimmed"}
$body = new EventsUpdateRequest(['tag' => ['key' => 'value']]); // [!code --]
$client->updateEvent($body, request_id: "REQUEST_ID"); // [!code --]
$body = new EventUpdate(['tags' => ['key' => 'value']]); // [!code ++]
$client->updateEvent(event_id: "EVENT_ID", $body); // [!code ++]
```

### Handling sealed client results from a v3 JavaScript agent

PHP SDK v7 will fail to deserialize the decrypted payload of a [sealed client result](/docs/sealed-client-results) sent by a v3 JavaScript agent into an `Event` because the payload is an `EventsGetResponse` (i.e., the v3 event format), not an `Event`. In this case, `Sealed::unsealEventResponse` throws an `InvalidSealedDataException`.

To upgrade to PHP SDK v7 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails.
To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the [sealed client results guide](/docs/sealed-client-results#step-3-send-sealed_result-to-your-backend).

Both `Sealed::unsealEventResponse` and `$client->getEvent` return an `Event`, so the fallback returns the same type.

```php PHP theme={"theme":"github-dark-dimmed"}
// Partial example (imports omitted).

function getEvent(
  FingerprintApi $client,
  string $sealedResultBytes, // previously decoded using base64_decode
  string $eventId,
  array $keys
): Event {
  // Try to unseal the payload locally first.
  try {
    return Sealed::unsealEventResponse($sealedResultBytes, $keys);
  } catch (InvalidSealedDataException $e) {
    // Deserialization failed. Fall back to the Server API using the event ID
    // sent alongside the sealed client results.
    fwrite(STDERR, sprintf("Could not unseal result, falling back to Server API: %s\n", $e->getMessage()));
    return $client->getEvent($eventId);
  }
}
```

## Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/php-sdk).


# Python Server SDK
Source: https://docs.fingerprint.com/reference/python-server-sdk

[Fingerprint Server Python SDK](https://github.com/fingerprintjs/python-sdk) is an easy way to interact with our Server API from your Python application. You can retrieve visitor history or individual identification events. View our [Python Server SDK quickstart](/docs/python-server-quickstart) for a step-by-step guide to get started.

## How to install

Add the `fingerprint-server-sdk` package as a dependency to your application:

<CodeGroup>
  ```ini requirements.txt theme={"theme":"github-dark-dimmed"}
  fingerprint-server-sdk==9.7.1
  ```

  ```toml pyproject.toml theme={"theme":"github-dark-dimmed"}
  dependencies = [
      "fingerprint-server-sdk==9.7.1",
  ]
  ```
</CodeGroup>

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region (if it is not US/Global).

```python Python theme={"theme":"github-dark-dimmed"}
import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, ErrorResponse
from fingerprint_server_sdk.configuration import Region

configuration = fingerprint_server_sdk.Configuration(
  api_key="SECRET_API_KEY",
  # region=Region.EU
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

# Search events for a specific visitor
try:
    events = api_instance.search_events(10, visitor_id="VISITOR_ID")
    print(events)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when searching events: {e}'
    print(message)

# Get a specific identification event
try:
    event = api_instance.get_event("EVENT_ID")
    print(event)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when getting an event: {e}'
    print(message)
```

## Migration guide for Python SDK v9

Version 9 migrates the SDK from Server API v3 to v4. This is a breaking change.

This section summarizes the most important changes from previous versions.

### Package rename

The package changed from `fingerprint_pro_server_api_sdk` to `fingerprint_server_sdk`.
Update the dependency you install and all of your imports.

<CodeGroup>
  ```ini requirements.txt theme={"theme":"github-dark-dimmed"}
  fingerprint_pro_server_api_sdk==8.13.0 # [!code --]
  fingerprint-server-sdk==9.7.1 # [!code ++]
  ```

  ```toml pyproject.toml theme={"theme":"github-dark-dimmed"}
  dependencies = [
      "fingerprint_pro_server_api_sdk==8.13.0",  # [!code --]
      "fingerprint-server-sdk==9.7.1", # [!code ++]
  ]
  ```
</CodeGroup>

```python Python theme={"theme":"github-dark-dimmed"}
import fingerprint_pro_server_api_sdk # [!code --]
import fingerprint_server_sdk # [!code ++]
```

### Region parameter

The `region` parameter is now a `Region` enum instead of a string.

```python Python theme={"theme":"github-dark-dimmed"}
configuration = Configuration(api_key="SECRET_API_KEY", region="eu") # [!code --]
from fingerprint_server_sdk.configuration import Region # [!code ++]
configuration = Configuration(api_key="SECRET_API_KEY", region=Region.EU) # [!code ++]
```

### `get_event` return type

`get_event` now returns an `Event` with a flatter structure.
Access fields directly instead of through the `products` wrapper.

```python Python theme={"theme":"github-dark-dimmed"}
event = api_instance.get_event("EVENT_ID")
visitor_id = event.products.identification.data.visitor_id # [!code --]
visitor_id = event.identification.visitor_id # [!code ++]
```

### `get_visits` replaced by `search_events`

`get_visits` and `get_related_visitors` have been removed.
Use `search_events` to retrieve the events for a visitor.

```python Python theme={"theme":"github-dark-dimmed"}
response = api_instance.get_visits("VISITOR_ID", limit=10) # [!code --]
response = api_instance.search_events(limit=10, visitor_id="VISITOR_ID") # [!code ++]
```

### Error handling

The `KnownApiException` class and its `structured_error` attribute have been removed. Catch `ApiException` and parse the response body with `ErrorResponse.from_json`. Version 9 also adds specific exception subclasses such as `BadRequestException`, `TooManyRequestsException`, `ConflictException`, and `UnprocessableEntityException`.

```python Python theme={"theme":"github-dark-dimmed"}
from fingerprint_pro_server_api_sdk.rest import ApiException, KnownApiException # [!code --]
from fingerprint_server_sdk import ApiException, ErrorResponse # [!code ++]

try:
    event = api_instance.get_event("EVENT_ID")
except KnownApiException as e: # [!code --]
    structured_error = e.structured_error # [!code --]
    print("Error: %s\n" % structured_error.error) # [!code --]
except ApiException as e:
    if e.body is not None: # [!code ++]
        error_response = ErrorResponse.from_json(e.body) # [!code ++]
        if error_response is not None: # [!code ++]
            print(f"API request failed: {error_response.error.code} {error_response.error.message}") # [!code ++]
        else: # [!code ++]
            print(f"API request failed with unexpected error format: {e}") # [!code ++]
```

### Handling sealed client results from a v3 JavaScript agent

Python SDK v9 will fail to deserialize the decrypted payload of a [sealed client result](/docs/sealed-client-results) sent by a v3 JavaScript agent into an `Event` because the payload is an `EventsGetResponse` (i.e., the v3 event format), not an `Event`.

To upgrade to Python SDK v9 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails.
To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the [sealed client results guide](/docs/sealed-client-results#step-3-send-sealed_result-to-your-backend).

Both `unseal_event_response` and `get_event` return an `Event`, so the fallback returns the same type.

```python Python theme={"theme":"github-dark-dimmed"}
# Partial example (imports omitted).
def get_event(api_instance, sealed_result_bytes, event_id, keys):
    # `sealed_result_bytes` is the base64-decoded `sealed_result` from the frontend.
    # Try to unseal the payload locally first.
    try:
        return unseal_event_response(sealed_result_bytes, keys)
    except Exception as e:
        # Unsealing or deserialization failed. Fall back to the Server API
        # using the event ID sent alongside the sealed client results.
        print(f"Could not unseal result, falling back to Server API: {e}")
        return api_instance.get_event(event_id)
```

## Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/python-sdk).


# Server SDKs
Source: https://docs.fingerprint.com/reference/server-sdks

Fingerprint offers SDKs for the most popular server-side frameworks and languages. The SDKs make it easier to work with Fingerprint Server API, Webhooks, and other features by providing utility methods and types.

Fingerprint offers the following server SDKs:

* [Go Server SDK](/reference/go-server-sdk)
* [Java Server SDK](/reference/java-server-sdk)
* [Node.js Server API SDK](/reference/node-server-sdk)
* [.NET Server API SDK](/reference/net-server-sdk)
* [PHP Server API SDK](/reference/php-server-sdk)
* [Python Server API SDK](/reference/python-server-sdk)

The SDKs are based on a Server API OpenAPI schema, which is also available on GitHub:

* [Server API OpenAPI schema](https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi)


# Register a subdomain
Source: https://docs.fingerprint.com/reference/subdomainscontroller_create

reference/management-api_2025-11-20.json POST /subdomains
Register a new custom subdomain and receive its DNS records. Optionally pass `webhook_url` to get a signed POST callback on every status change instead of polling; the signing secret is returned once in this response as `webhook_secret`.

Every DNS record you need is returned in this response at once: the verification `CNAME` record and the two routing `A` records. You can add them all to your DNS provider in a single pass. The `A` records start routing traffic only after your certificate is issued, so adding them early is safe.

Optionally pass a `webhook_url` to receive a signed `POST` callback each time the subdomain's status changes, instead of polling [Get subdomain](/reference/subdomainscontroller_findone). The `webhook_secret` used to verify those callbacks is returned only in this response, so store it now. It can't be retrieved later.

Subdomains are immutable. To change a subdomain, [delete it](/reference/subdomainscontroller_delete) and register a new one.

See the [Custom subdomain setup](/docs/custom-subdomain-setup#manage-subdomains-with-the-management-api) guide for the full flow.


# Delete subdomain
Source: https://docs.fingerprint.com/reference/subdomainscontroller_delete

reference/management-api_2025-11-20.json DELETE /subdomains/{id}
Delete a subdomain by ID.

Deletes the subdomain and revokes its SSL certificate. This action is irreversible.

Deleting a subdomain whose status is `active` stops routing its traffic to Fingerprint. Any JavaScript agent still configured with this subdomain as its [`endpoints`](/reference/js-agent-start-function#endpoints) will fail to identify visitors, so update your agent configuration before you delete a subdomain that's in use.

Note: Does not support `Legacy` subdomains. Migrate old certificates via the Dashboard to manage them via API.


# List subdomains
Source: https://docs.fingerprint.com/reference/subdomainscontroller_findall

reference/management-api_2025-11-20.json GET /subdomains
Lists all custom subdomains for the workspace associated with the Management API key.

Returns a compact representation of each subdomain, without DNS records. Use [Get subdomain](/reference/subdomainscontroller_findone) to retrieve the DNS records and full details for a single subdomain.

Filter by `status` to narrow the results, and use the `cursor` and `limit` parameters to page through them. See [Pagination](/reference/management-api-pagination) for details.

Note: Does not support `Legacy` subdomains. Migrate old certificates via the Dashboard to manage them via API.


# Get subdomain
Source: https://docs.fingerprint.com/reference/subdomainscontroller_findone

reference/management-api_2025-11-20.json GET /subdomains/{id}
Fetch a subdomain by ID.

Returns the full subdomain, including its DNS records and current status. Poll this endpoint to track a subdomain's progress until its status is `active`, or configure a `webhook_url` when you [register the subdomain](/reference/subdomainscontroller_create) to receive status changes without polling.

See [Subdomain statuses](/docs/custom-subdomain-setup#subdomain-statuses) for what each status means.

Note: Does not support `Legacy` subdomains. Migrate old certificates via the Dashboard to manage them via API.


# Verify subdomain
Source: https://docs.fingerprint.com/reference/subdomainscontroller_verify

reference/management-api_2025-11-20.json POST /subdomains/{id}/verify
Trigger manual verification for a subdomain.

Triggers an on-demand DNS check instead of waiting for the next background check. Use it right after you add your DNS records to move the subdomain forward without waiting.

This endpoint is idempotent: if the check doesn't advance the subdomain, or the subdomain is already `active`, it still returns `200` with the current state. It's rate limited per subdomain, so call it sparingly rather than in a tight loop. To poll for status, use [Get subdomain](/reference/subdomainscontroller_findone) instead.


# Create a webhook
Source: https://docs.fingerprint.com/reference/webhookscontroller_create

reference/management-api_2025-11-20.json POST /webhooks
Creates a new webhook in the workspace associated with the Management API key.
Webhook needs to be verified before it will start sending identification events to your server. See webhook verification.
If webhook signatures are enabled (enterprise only), signing key will be visible in the response after creation. When fetching webhooks after creation, signing key will not be visible!
See webhooks documentation for more details.
When specifying an environment during creation, webhook should be assigned to the given environment. Setting environment to null creates a global webhook.

Webhook needs to be [verified](/reference/webhookscontroller_verify/) before it will start sending identification events to your server.

The response will include a [signing key](/docs/webhooks#webhook-signatures). When fetching webhooks after creation, signing key will not be visible!

When specifying an environment during creation, webhook will report events only from an associated environment. Setting environment to null creates a workspace-scoped webhook that reports on all events.

See [webhooks](/docs/webhooks/) documentation for more details.


# List webhooks
Source: https://docs.fingerprint.com/reference/webhookscontroller_findallv2

reference/management-api_2025-11-20.json GET /webhooks
Lists all webhooks associated to the Management API key, optionally filtered by status.



# Get webhook by ID
Source: https://docs.fingerprint.com/reference/webhookscontroller_findone

reference/management-api_2025-11-20.json GET /webhooks/{id}
Fetch a specific webhook by ID.



# Delete webhook
Source: https://docs.fingerprint.com/reference/webhookscontroller_remove

reference/management-api_2025-11-20.json DELETE /webhooks/{id}
Deletes the webhook with the given ID. This action is not reversible. Changes will take affect in a few minutes.



# Update webhook
Source: https://docs.fingerprint.com/reference/webhookscontroller_update

reference/management-api_2025-11-20.json PATCH /webhooks/{id}
Updates the webhook with the given ID. You can update the name, description, status, URL, and set basic authentication.
Changing the URL will require this webhook to be verified again.
Changing the status will disable/enable sending of identification events to your webhook.

You can update the `name`, `description`, `status`, `URL`.

Changing the URL will require this webhook to be verified again.

Changing the status will disable/enable sending of identification events to your webhook.


# Verify webhook
Source: https://docs.fingerprint.com/reference/webhookscontroller_verify

reference/management-api_2025-11-20.json POST /webhooks/{id}/verification
Send a mocked test event in order to verify your webhook endpoint, it needs to respond with HTTP 200 to be verified.
Webhook needs to be verified before it will receive identification events.



# AI agent detection
Source: https://docs.fingerprint.com/docs/ai-agents

Detect and verify AI agents visiting your web properties, and distinguish them from malicious bots.

AI agent detection lets you identify authorized AI agents visiting your website and distinguish them from malicious bots.

It uses [Web Bot Auth](/docs/bot-detection/web-bot-auth-implementation), a cryptographic signing protocol, to verify agent identity. When Fingerprint detects an agent, it returns structured metadata, including the agent's provider, name, and the identity verification status in the `bot_info` field of the Server API response.

This lets you make precise access decisions: allow authorized agents, block unverified automation, or apply different logic based on agent category and provider.

## How verification works

1. The agent signs its HTTP requests using a private key.
2. Fingerprint retrieves the agent's public key from a directory hosted at a known URL.
3. Fingerprint verifies the signature and returns an `identity` value in `bot_info`.

The `identity` value reflects the outcome of the verification:

| Value      | Meaning                                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| `signed`   | Signature verified against the agent's public key directory                                                    |
| `verified` | Signature verified, and the agent is operated exclusively by its vendor (not configurable by vendor customers) |
| `unknown`  | Agent recognized, but no verifiable identity was presented                                                     |
| `spoofed`  | Agent presented an identity that failed verification                                                           |

## API response

When Fingerprint detects a bot or agent, the [Server API](/reference/server-api-get-event) response includes the following fields:

| Field      | Type   | Description                                      |
| ---------- | ------ | ------------------------------------------------ |
| `bot`      | string | `good`, `bad`, or `not_detected`                 |
| `bot_type` | string | Additional classification, e.g. `ai_agent`       |
| `bot_info` | object | Extended metadata for recognized agents and bots |

The `bot_info` object contains:

| Field      | Description                                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | Agent category, e.g. `ai_agent`, `ai_browser`, `browser_automation` ([full list](/docs/bot-detection/bot-directory#bot_info-metadata)) |
| `provider` | The organization that operates the agent, e.g. `OpenAI` or `AWS`                                                                       |
| `name`     | Human-readable agent name, e.g. `ChatGPT Agent`                                                                                        |
| `identity` | Verification status: `signed`, `verified`, `unknown` or `spoofed`                                                                      |

`bot_info` is available in Server API v4 and only when Fingerprint recognizes the agent or bot. See the [Server API reference](/reference/server-api-get-event#response-bot-info) for the full schema.

## Supported AI agents

The following agents are currently detected and return `bot_info` metadata:

| Name              | Provider    | Category     | Identity |
| ----------------- | ----------- | ------------ | -------- |
| ChatGPT Agent     | OpenAI      | `ai_agent`   | `signed` |
| Bedrock AgentCore | AWS         | `ai_agent`   | `signed` |
| Browserbase Agent | Browserbase | `ai_agent`   | `signed` |
| Manus Agent       | Manus       | `ai_agent`   | `signed` |
| AGI Agent         | AGI Inc     | `ai_agent`   | `signed` |
| Anchor Browser    | Anchor      | `ai_browser` | `signed` |

For the full list of all detectable bots and agents, see the [Bot Directory](/docs/bot-detection/bot-directory).

## Using detection results

The `bot` field (`good`, `bad`, `not_detected`) is a legacy signal. For AI agents and other recognized bots, use `bot_info.identity` instead, as it provides more precise, actionable information.

Note that `identity` is only available for well-known bots and agents in the [Bot Directory](/docs/bot-detection/bot-directory). Some generic browser automation tools (Selenium, Playwright, headless Chrome, etc.) will not have a `bot_info` entry and should be handled using the `bot: bad` signal.

| Scenario                               | Suggested action                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `bot_info.identity: verified`          | **Allow**: agent identity is confirmed and safety verified                                 |
| `bot_info.identity: signed`            | **Allow**: agent identity is cryptographically verified                                    |
| `bot_info.identity: unknown`           | **Apply custom logic**: agent is recognized but unverified                                 |
| `bot_info.identity: spoofed`           | **Review**: verification failed, which may indicate misconfiguration or malicious spoofing |
| `bot` is `bad`, no `bot_info` (legacy) | **Review or Block**: unrecognized and potentially malicious automation                     |

## Next steps

<Columns>
  <Card title="Bot Directory" icon="globe" href="/docs/bot-detection/bot-directory">
    Full list of detectable bots and agents
  </Card>

  <Card title="Web Bot Auth implementation" icon="braces" href="/docs/bot-detection/web-bot-auth-implementation">
    Cryptographically sign your agent to verify identity
  </Card>

  <Card title="Submit your agent to Fingerprint directory" icon="shield" href="https://dashboard.fingerprint.com/submit-bot">
    Submit your agent or bot to the Fingerprint Bot Directory
  </Card>
</Columns>


# Android API call allowance
Source: https://docs.fingerprint.com/docs/android-api-call-allowance

Prevent fraud in your Android apps for free with Fingerprint device intelligence.

Free and Pro Plus plans receive 500,000 complimentary Android API calls per month. These API calls apply when using our [Android SDK](/docs/android-sdk), [React Native](/docs/fingerprintjs-pro-react-native), or [Flutter](/docs/flutter) SDKs within an Android app.

## How can I get access to the Android API call allowance?

New customers can start with our [unlimited 14-day free trial](https://dashboard.fingerprint.com/signup).\
When the trial ends, your workspace will default to the Free plan unless you upgrade to Pro Plus. Either way, the 500,000 Android allowance is automatically added to the workspace.

Existing customers with a Pro Plus workspace will automatically have the allowance added at the **start of their next billing cycle**. It will automatically be added to the first or oldest Pro Plus workspace on the account.

## What are the limitations?

* The Android API call allowance is limited to 500,000 Android API calls per billing cycle.
  * **Pro Plus plan** – continue usage past 500,000 at a rate of \$4 per additional 1,000 API calls.
  * **Free plan** – Android calls are restricted after 500,000 until the next billing cycle.
* The allowance is limited to 1 workspace per account.

## Frequently Asked Questions

### Is the Android API call allowance a permanent or limited-time offer?

Accounts created during the offer will retain this free usage cap permanently.

### How will it work if I have API calls on both Android and iOS?

Billing will be separated by platform and billed accordingly, API calls from other platforms will count towards the original plan’s usage.

For more details on how identification API requests are billed, please refer to our [documentation](/docs/billing#identification-api-request-as-a-billing-unit).

### What happens if I exceed 500K Android API calls?

As your workspace nears the 500,000 Android API call limit, you will be alerted and prompted to upgrade to our [Enterprise plan](https://fingerprint.com/pricing/).

Upon reaching the 500,000 limit within the billing cycle, Pro Plus customers can continue usage at a rate of \$4 per additional 1,000 API calls.

For Free subscriptions that reach the limit during the billing cycle, we will restrict Android API calls for the remainder of the billing cycle.

### Is support included with the Android API call allowance?

Accounts receive access to our best-in-class developer documentation anytime, along with dedicated support available 8 hours a day, 5 days a week.

### Is 500K free Android API calls a limit per app, email, domain, or company?

The API call limit applies per company. Only one workspace from each account is eligible for the offer.

### Where can I check the free API usage?

API call usage will be available on the [Plan](https://dashboard.fingerprint.com/plan/)  page, with a breakdown by platform.

### I’m on the legacy Pro plan. Do I get the 500K Android API calls?

Yes. Legacy Pro plan customers will also receive 500,000 complimentary Android API calls per month. This allowance will be automatically added at the start of your next billing cycle and applies to one workspace per account. After the 500,000 API call limit is exceeded within a billing cycle, additional Android usage will be billed at a rate of \$2 per additional 1,000 API calls.


# Android SDK Changelog
Source: https://docs.fingerprint.com/docs/android-sdk-changelog





# Changelog (JavaScript agent)
Source: https://docs.fingerprint.com/docs/changelog





# Discord Server
Source: https://docs.fingerprint.com/docs/discord





# DPA (GDPR)
Source: https://docs.fingerprint.com/docs/dpa-gdpr



# GDPR Data Processing Agreement

This Data Processing Agreement (“**DPA**”) is an addendum to the Customer Terms of Service (“**Agreement**”) between FingerprintJS Inc. (“**FingerprintJS**”) and the Customer (each a “**Party**” and together the “**Parties**”). This DPA includes and incorporates by reference the annexes and addenda referenced at the bottom of this document. All capitalised terms not defined in this DPA shall have the meanings set forth in the Agreement. Customer enters into this DPA on behalf of itself and, to the extent required under Data Protection Laws, in the name and on behalf of its Authorised Affiliates (defined below).

**The Parties agree as follows:**

## 1. Definitions

“**Additional Services**” means additional model-driven fraud prediction and detection services and access to the DRN, in each case as agreed between the Customer and FingerprintJS.

"**Administration Data**" means:

* **(a)** contact details relating to, and the content of correspondence with, the Customer’s main account holder or administrator; and
* **(b)** support enquiries submitted by the Customer’s authorised users in relation to the Service and Additional Services.

**“Affiliate”** means an entity that directly or indirectly Controls, is Controlled by or is under common Control with an entity.

**“Authorised Affiliate”** means any of Customer Affiliate(s) permitted to or otherwise receiving the benefit of the Service and Additional Services pursuant to the Agreement.

**“Control”** means either (i) an ownership, voting or similar interest representing twenty five (25%) or more of the total interests then outstanding of the entity in question; or (ii) the power to direct or cause the direction and management of an entity's policies in accordance with the acquirer's wishes, whether as a result of the ownership of shares, control of the board of directors, contract or any powers conferred by the entity's articles of association or other constitutional documents. The term **“Controlled”** shall be construed accordingly.

**“Controller”** has the meaning given to it in the GDPR.

"**Controller Clauses**" means Module One (*controller to controller*) of the Standard Contractual Clauses annexed to Commission Implementing Decision (EU) 2021/914.

“**Controller Purposes**" has the meaning given in Section 2.5.

**“Customer Personal Data”** means any Personal Data that FingerprintJS and/or its Affiliates processes in the course of providing the Service and Additional Services to Customer under the Agreement as set out in Schedule 2.

**“Data Protection Laws”** means all data protection and privacy laws and regulations applicable to the processing of Personal Data under the Agreement, including, where applicable, the GDPR and Swiss Data Protection Laws.

"**GDPR**" means Regulation (EU) 2016/679 (the "**EU GDPR**") or, where applicable the "**UK GDPR**" as defined in section 3 of the Data Protection Act 2018.

**“Personal Data”** has the meaning given to it in the GDPR.

**“Processor”** has the meaning given to it in the GDPR.

"**Processor Clauses**" means Module Two (*controller to processor*) of the Standard Contractual Clauses annexed to Commission Implementing Decision (EU) 2021/914.

**“Security Incident”** means any breach of security that leads to the accidental or unlawful destruction, loss, alteration, unauthorised disclosure of or access to Personal Data.

"**Standard Contractual Clauses**" or

“**SCCs**” means the Controller Clauses and the Processor Clauses.

**“Sub-processor”** means any Processor engaged by FingerprintJS or its Affiliates to assist in fulfilling its obligations with respect to providing the Service and Additional Services pursuant to the Agreement or this DPA. Sub-processors may include third parties or any FingerprintJS Affiliate.

"**Swiss Data Protection Laws**" means the Swiss Federal Act on Data Protection of 25 September 2020 ("**FADP**") and the Swiss Data Protection Ordinance of 31 August 2022, and any new or revised version of these laws that may enter into force for time to time; and

“**Usage Data**" means diagnostic, usage and performance information collected by FingerprintJS in relation to the Customer’s and its authorised users' use of the Service.

The terms “**data subject**”, “**processing**” (and **“process”**, **“processes”** and **“processed”**) and “**supervisory authority**” have the meanings given to them in the GDPR.

## 2. Scope and Applicability of this DPA

### 2.1

This DPA applies where and only to the extent that FingerprintJS processes Customer Personal Data in the course of providing the Service and Additional Services and such Customer Personal Data is subject to Data Protection Laws. The Parties agree to comply with the terms and conditions in this DPA in connection with such Customer Personal Data.

### 2.2 Role of the Parties

Save as set out in Section 2.5, the Parties acknowledge and agree that, as between FingerprintJS and Customer, Customer is the Controller of Customer Personal Data and FingerprintJS shall process Customer Personal Data only as a Processor on behalf of Customer.

### 2.3 Customer Obligations

Customer agrees that: (i) it shall comply with its obligations as a Controller under Data Protection Laws in respect of its processing of Customer Personal Data; (ii) it shall ensure that any processing instructions it issues to FingerprintJS with respect to Customer Personal Data shall comply with applicable Data Protection Laws.

### 2.4 Processing of Personal Data

Save as set out in Section 2.5, and notwithstanding clause 8.1 of the Processor Clauses, FingerprintJS shall process Customer Personal Data only for the following purposes: (i) processing to perform the Service and Additional Services in accordance with the Agreement; and (ii) processing to perform any steps necessary for the performance of the Agreement, in each case unless processing is required by applicable law in the UK, Switzerland, the European Union or a Member State of the European Union, in each case to which FingerprintJS is subject, in which case FingerprintJS shall, to the extent permitted by such applicable law, inform the Customer of that legal requirement before processing that Customer Personal Data. The Parties agree that, for the purposes of clause 8.1(a) of the Processor Clauses, the Agreement and this DPA shall be the Customer's instructions for the processing of Customer Personal Data. To the extent that any of the Customer's instructions require processing of Customer Personal Data in a manner that falls outside the scope of the Service and Additional Services, FingerprintJS may:

* **(a)** make the performance of any such instructions subject to the payment by the Customer of any costs and expenses incurred by FingerprintJS or such additional charges as FingerprintJS may reasonably determine; or
* **(b)** terminate the Agreement and the Service and Additional Services.

### 2.5 Controller Purposes

The Parties acknowledge and agree that:

* **(a)** FingerprintJS collects and processes Administration Data and Usage Data as a Controller for legitimate business purposes, including administering its business relationship with Customer, product development and sales and marketing;
* **(b)** FingerprintJS collects Fraud Identification Data as a Controller for the purposes of maintaining and making available the DRN.

(the “**Controller Purposes**”). Where it acts as a Controller, FingerprintJS shall process such data in compliance with Data Protection Laws..

## 3. Standard Contractual Clauses

### 3.1

The Standard Contractual Clauses shall, as further set out at Schedule 5, apply to transfers of Customer Personal Data from Customer to FingerprintJS, and form part of this DPA, to the extent that:

* **(a)** the GDPR or Swiss Data Protection Law applies to Customer's processing of such Customer Personal Data when making the transfer; or
* **(b)** the transfer is an "onward transfer" (as defined in the applicable module of the SCCs).

### 3.2

The Parties agree that:

* **(a)** execution of the Agreement or this DPA shall have the same effect as signing the SCCs; and
* **(b)** in the event of a conflict between the terms of the Agreement, this DPA and the SCCs, the terms of the SCCs shall prevail.

## 4. Sub-processing

### 4.1 Authorised Sub-processors

The Parties agree that, for the purposes of clause 9 of the Standard Contractual Clauses, Customer gives FingerprintJS general authorisation to engage Sub-processors to process Customer Personal Data on Customer's behalf. The Sub-processors currently engaged by FingerprintJS and authorised by Customer are listed in Schedule 4.

### 4.2 Sub-processor Obligations

FingerprintJS shall: (i) enter into a written agreement with the Sub-processor imposing the same data protection obligations on the Sub-processor as set out in this DPA; and (ii) remain responsible for its compliance with the obligations of this DPA and for any acts or omissions of the Sub-processor that cause FingerprintJS to breach any of its obligations under this DPA.

### 4.3 Changes to Sub-processors

FingerprintJS shall provide Customer with fourteen (14) calendar days' notice (for which email shall suffice) of any proposed changes to the Sub-processors, including any information reasonably necessary to enable the Customer to assess the Sub-processor and exercise its right to object.

### 4.4 Objection to Sub-processors

If the Customer objects to FingerprintJS's use of a new Sub-processor (including when exercising its right to object under clause 9(a) of the Standard Contractual Clauses) it shall: (i) notify FingerprintJS of its objection promptly in writing within five (5) calendar days of receipt of FingerprintJS' notice in accordance with Section 4.3; and (ii) provide documentary evidence that reasonably shows that the Sub-processor does not or cannot comply with the requirements in this DPA (including the Standard Contractual Clauses). In such an event, the Parties shall discuss such concerns in good faith with a view to achieving commercially reasonable resolution. If this is not possible, either Party may terminate the applicable Service and Additional Services that cannot be provided by FingerprintJS without the use of the objected-to new Sub-processor by giving to the other Party thirty (30) calendar days' written notice. During such notice period, FingerprintJS may suspend the affected portion of the Service and Additional Services.

## 5. Customer warranties and undertakings

### 5.1

The Customer represents and warrants that:

* **(a)** it has provided all applicable notices to data subjects and, to the extent required, obtained consent from data subjects in each case as required for the lawful processing of Customer Personal Data in accordance with the Agreement and this DPA; and
* **(b)** without prejudice to the generality of clause 8 of the Standard Contractual Clauses (as applicable), taking into account the state of the art, the costs of implementation and the nature, scope, context and purposes of processing as well as the risk of varying likelihood and severity for the rights and freedoms of natural persons, the security measures set out in Schedule 3 are:
  * **(i)** appropriate to ensure the security of the Customer Personal Data, including protection against a Security Incident; and
  * **(ii)** otherwise consistent with the Customer's obligations under Article 32 of the GDPR.

### 5.2

Other than as set out in Section 2.5, the Customer shall be solely responsible for the legality of Customer Personal Data provided to FingerprintJS by Customer or an Authorised Affiliate or collected by FingerprintJS.

## 6. Security and Audits

### 6.1 Security Measures

FingerprintJS shall implement and maintain appropriate technical and organisational security measures to protect Customer Personal Data from Security Incidents and to preserve the security and confidentiality of the Customer Personal Data, in accordance with FingerprintJS' security standards described in Schedule 3 (“Security Measures”).

### 6.2 Confidentiality of Processing

FingerprintJS shall ensure that any person who is authorised by FingerprintJS to process Customer Personal Data (including its staff, agents and subcontractors) shall be under an appropriate obligation of confidentiality (whether a contractual or statutory duty).

### 6.3 Security Incident Response

FingerprintJS will notify Customer in writing without undue delay after becoming aware of any Security Incident, and reasonably cooperate with regards to any obligation of Customer under Data Protection Laws to make any notifications in respect of a Security Incident, such as to individuals, supervisory authorities or other regulatory authorities. FingerprintJS' notification of, or response to, a Security Incident under this Section 6.3 will not be construed as an acknowledgement by FingerprintJS of any fault or liability with respect to the Security Incident.

### 6.4 Updates to Security Measures

Customer acknowledges that the Security Measures are subject to technical progress and development and that FingerprintJS may, by written notice to the Customer, update or modify the Security Measures from time to time following any review by FingerprintJS of the Security Measures (including in accordance with clause 8.6 of the Standard Contractual Clauses), provided that such updates and modifications do not result in the degradation of the overall level of protection afforded to the Customer Personal Data by FingerprintJS under this DPA.

### 6.5 Audits

With respect to any audits conducted under clauses 8.9(c) and (d) of the Standard Contractual Clauses, the Parties agree that:

* **(a)** all such audits shall be conducted:
* **(i)** only once per year, or more frequently if any audit indicates that FingerprintJS is in non-compliance with this DPA;
* **(ii)** on reasonable written notice to FingerprintJS;
* **(iii)** only during FingerprintJS' normal business hours; and
* **(iv)** in a manner that does not disrupt FingerprintJS' business;
* **(v)** by reference to an appropriate and accepted control standard or framework; and
* **(b)** the Customer (or, where applicable, a third party independent auditor appointed by the Customer) shall:
* **(i)** enter into a confidentiality agreement with FingerprintJS prior to conducting the audit in such form as FingerprintJS may request; and
* **(ii)** ensure that its personnel comply with FingerprintJS' and any Sub-processor's policies and procedures when attending FingerprintJS' or Sub-processor's premises, as notified to the Customer by FingerprintJS or Sub-processor.

### 6.6 Reports

FingerprintJS shall provide written responses (on a confidential basis) to all reasonable requests for information made by Customer, including responses to information security and audit questionnaires, that Customer (acting reasonably) considers necessary to confirm FingerprintJS's compliance with this DPA, provided that Customer shall not exercise this right more than once per year.

## 7. Return or Deletion of Data

### 7.1

Upon deactivation of the Service and Additional Services, FingerprintJS shall, subject to Section 7.2: (i) if requested to do so by the Customer within seven (7) days of the date of termination of the Agreement or deactivation of the Service and Additional Services, return a complete copy of all Customer Personal Data by secure file transfer in such a format as notified by the Customer to FingerprintJS; and (ii) delete and use all reasonable efforts to procure the deletion of all other copies of Customer Personal Data processed by FingerprintJS or any Sub-processors.

### 7.2

FingerprintJS may retain Customer Personal Data:

* **(a)** to the extent that such Customer Personal Data is processed for the Controller Purposes;
* **(b)** to the extent required by applicable laws, and only for such period and such purposes as required by applicable laws; or
* **(c)** to the extent that the Customer Personal Data has been archived on back-up systems, provided that FingerprintJS shall securely isolate and protect such Customer Personal Data from any further processing, except to the extent required by applicable law, and purge such Customer Personal Data from the applicable back-up systems in accordance with its normal back-up cycle.

### 7.3

FingerprintJS shall, with respect to any Customer Personal Data retained in accordance with Section 7.2, ensure the confidentiality of all such Customer Personal Data.

## 8. Cooperation

### 8.1

To the extent that Customer is unable to independently access the relevant Customer Personal Data within the Service and Additional Services, FingerprintJS shall (at Customer's expense) taking into account the nature of the processing, provide reasonable cooperation to assist Customer by appropriate technical and organisational measures, in so far as is possible, to respond to any requests from individuals or applicable data protection authorities relating to the processing of Customer Personal Data under the Agreement. Other than in respect of Administration Data, Usage Data and Fraud Identification Data processed for the Controller Purposes, in the event that any such request is made directly to FingerprintJS, FingerprintJS shall not respond to such communication directly without Customer's prior authorisation, unless legally compelled to do so. If FingerprintJS is required to respond to such a request, FingerprintJS shall promptly notify Customer and provide it with a copy of the request unless legally prohibited from doing so.

### 8.2

To the extent FingerprintJS is required under Data Protection Law, FingerprintJS shall (at Customer's expense) provide reasonably requested information regarding FingerprintJS’s processing of Customer Personal Data under the Agreement to enable the Customer to carry out data protection impact assessments or prior consultations with data protection authorities as required by law.

### 8.3

Customer shall promptly inform FingerprintJS of any request received by the Customer from a data subject to assert their rights under the GDPR and Swiss Data Protection Laws in relation to Administration Data, Usage Data or Fraud Identification Data processed by FingerprintJS for the Controller Purposes.

## 9. Costs

### 9.1

The Customer shall pay to FingerprintJS on demand all costs and expenses incurred by FingerprintJS in connection with:

* **(a)** implementing any changes to the Service and Additional Services under Section 4.4;
* **(b)** facilitating and contributing to any audits of FingerprintJS under Section 6.5 or clauses 8.9(c) and (d) of the Standard Contractual Clauses;
* **(c)** facilitating and contributing to any audits of FingerprintJS conducted by a supervisory authority;
* **(d)** responding to queries or requests for information from the Customer relating to the processing of Customer Personal Data under clauses 8.9(a), 8.9(c) or 8.9(e) of the Standard Contractual Clauses;
* **(e)** any assistance provided by FingerprintJS to the Customer with its fulfilment of its obligations to respond to data subjects' requests for the exercise of their rights under the GDPR; and
* **(f)** any assistance provided by FingerprintJS to the Customer with any data protection impact assessments or prior consultation with any supervisory authority of the Customer.

## 10. Miscellaneous

### 10.1

Except for the changes made by this DPA, the Agreement remains unchanged and in full force and effect. Without prejudice to the generality of clause 5 of the Standard Contractual Clauses, in the event of any conflict between the Agreement, this DPA and the Standard Contractual Clauses, the following order of precedence shall apply:

* **(g)** The Standard Contractual Clauses (or, with respect to transfers of Customer Personal Data subject to the UK GDPR or Swiss Data Protection Laws, the Standard Contractual Clauses as amended by Schedule 5).
* **(h)** The main body of this DPA.
* **(i)** The Agreement.

### 10.2

This DPA is a part of and incorporated into the Agreement so references to "Agreement" in the Agreement shall include this DPA.

### 10.3

In no event shall any Party limit its liability with respect to any individual's data protection rights under this DPA or otherwise.

### 10.4

Other than the right of data subjects or not-for-profit bodies, organisations or associations under the conditions set out in Article 80(1) of the GDPR to bring claims under the Standard Contractual Clauses (as applicable), a person who is not a Party to this DPA may not enforce any of its terms.

### 10.5

Notwithstanding the provisions of the Agreement and unless otherwise indicated in Schedule 5, this DPA and the Standard Contractual Clauses shall (to the extent permitted under applicable law) be governed by and construed in accordance with the laws of England and Wales.

### 10.6

Notwithstanding the provisions of the Agreement and unless otherwise indicated in Schedule 5, the Parties submit themselves to the jurisdiction of the courts of England and Wales in respect of any disputes arising under this DPA and the Standard Contractual Clauses.

## Schedule 1 — PARTIES TO THE PROCESSING

| Party:                                               | Customer / data exporter                       | FingerprintJS / data importer                                                                                                 |
| ---------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Role**                                             | **Controller**                                 | **Controller / Processor**                                                                                                    |
| **Contact person (Name, Position, Contact Details)** | The contact details provided with the Account. | Name: Valentin Vasilyev Position: Chief Technology Officer Contact details: [dpo@fingerprint.com](mailto:dpo@fingerprint.com) |
| **Activities / services provided**                   | Receipt of the Service and Additional Services | Provision of the Service and Additional Services                                                                              |
| **Competent supervisory authority**                  | The Data Protection Commission, Ireland        |                                                                                                                               |

## Schedule 2 — Details of processing

### Part 1 — Processing subject to the Processor Clauses

<u>Data subjects</u>

The personal data transferred concern the following categories of data subjects:

* The Customer’s end users who visit the Customer’s sites and services (“**End Users**”).
* The Customer's employees and contractors that the Customer authorises to access and use the Service (“**Authorised Users**”).

<u>Purpose(s) of the data transfer and further processing</u>

The purpose of the data transfer and further processing is the provision and maintenance of FingerprintJS' Service and Additional Services.

<u>Categories of data</u>

The personal data transferred concern the following categories of data:

End Users:

* Personal data contained within Visitor Data, including information relating to an End User's device, operating system, browser, browser configuration, IP address, and approximate location, and IDs associated with successful detections of fraud on the Customer’s sites and services.

Authorised Users:

* account information, including login information;
* payment and transaction information;
* support request information; and
* technical information regarding access to the Service (including IP address, approximate location, pages viewed and log data).

<u>Sensitive data</u>

None.

<u>Frequency of the transfer</u>

The data is transferred on a continuous basis.

<u>Subject matter of the processing</u>

The provision and maintenance of FingerprintJS' Service and Additional Services .

<u>Nature of the processing</u>

Transmitting, collecting, storing and analysing data in order to provide and maintain FingerprintJS' the Service and Additional Services.

<u>Duration</u>

The Personal Data will be retained for the duration of the Agreement, subject to Section 7 of the DPA.

<u>Sub-processor (if applicable)</u>

For transfers to sub-processors, specify subject matter, nature and duration of the processing:

* as set out in Schedule 4

### Part 2 — Processing subject to the Controller Clauses

<u>Data subjects</u>

* Authorised Users.

<u>Purposes of the transfer(s) and further processing</u>

The purpose of the data transfer and further processing is the administration of FingerprintJS' Service and Additional Services and improvement of FingerprintJS' Service, including internal record-keeping, billing, product development and sales and marketing.

<u>Categories of data</u>

The Personal Data transferred concern the following categories of data:

End Users:

* Fraud Identification Data

Authorised Users:

* contact information, including name, address, phone number, email address, login details, employing / engaging organisation;
* payment and transaction information;
* contact preferences, including preference set for notifications, marketing communications;
* comments and opinions; and
* technical information regarding access to the Service (including IP address, approximate location, pages viewed and log data, display and active functionalities).

<u>Sensitive data</u>

None.

<u>Frequency of the transfer</u>

The transfer is carried out on a continuous basis for the duration of the Agreement.

<u>Subject matter of the processing</u>

The subject matter of the processing is:

* Administration of FingerprintJS’s Service and Additional Services.
* Improvement, troubleshooting and testing of FingerprintJS' Service.
* Calculation of charges and fees owed by the Customer to FingerprintJS in respect of the Service and Additional Services.
* Marketing to Customer and their users.

<u>Nature of the processing</u>

The processing of Personal Data in connection with the administration of the Service and Additional Services and improvement of FingerprintJS's Service.

<u>Duration</u>

The Personal Data will be retained for the duration of the Agreement, subject to Section 7 of the DPA.

<u>Sub-processor (if applicable)</u>

For transfers to sub-processors, specify subject matter, nature and duration of the processing:

* as set out in Schedule 4.

## Schedule 3 — Technical and Organisational Security Measures

### 1. Introduction

The data importer employs a combination of policies, procedures, guidelines and technical controls to protect the personal data it processes from accidental loss and unauthorised access, disclosure or destruction.

### 2. Governance and Policies

The data importer has organised leadership and defined policies related to information security to ensure alignment with business objectives to adequately serve clients. These policies are reviewed and approved annually by management and updates are communicated to employees and relevant external parties.

Roles and responsibilities for teams and team members are defined within the data importer’s organisational structure and reporting lines as well as written job descriptions. Management reviews the data importer's organisational structure at least annually as part of strategic planning, and any changes are made as needed based on changing reporting lines, authorities, and responsibilities.

The data importer has following security policies and related processes in place:

* **(a)** Data classification and business impact assessment
* **(b)** Selection, documentation, and implementation of security controls
* **(c)** Assessment of security controls
* **(d)** User access authorisation and provisioning
* **(e)** Removal of user access
* **(f)** Monitoring of security controls
* **(g)** Security management

### 3. Access control

The data importer has implemented role-based access controls that limit access to sensitive information to only those individuals who require access based on job function, active employment, and management approval. The data importer maintains an up-to-date and complete inventory of information technology assets and asset owners.

Administrative level access to the data importer's critical systems (network, application, source code, and related databases) is limited to appropriate individuals based on job function and current employment with the data importer.

Administrative level access to critical system components including (production servers, databases, system infrastructure components, and front-end application level) are restricted to appropriate individuals based on job function and current employment with the data importer.

Access to the Amazon Web Services ("**AWS**") environment is controlled with security groups configured to prevent access based on predefined access control lists. Monitoring tools are in place to monitor the AWS environment and administrators receive notification of issues detected by the system based on pre-defined alert thresholds.

Sensitive authentication data such as service accounts and encryption keys are stored in a key management system. Access to sensitive authentication data is limited to only appropriate individuals based on job function and active employment with the data importer.

Remote access to the data importer's network and system infrastructure requires a unique username, password, and one-time multi-factor authentication code to authenticate. Remote access to the data importer's network and system infrastructure is limited to only appropriate individuals based on job function and active employment with the data importer.

Access to the data importer's systems requires a unique username and password. Password complexity standards within AWS are enforced and include the following:

* **(a)** Minimum password length is 16 characters
* **(b)** Require at least one uppercase letter from Latin alphabet (A–Z)
* **(c)** Require at least one lowercase letter from Latin alphabet (a–z)
* **(d)** Require at least one number
* **(e)** Require at least one non alphanumeric character ! @ # \$ % ^ & \* ( ) \_ + - = \[ ] \{ } | '.
* **(f)** Passwords expires in 90 days
* **(g)** Allow users to change their own password

### 4. Segmentation of personal data

The data importer has logically segmented its network so that unrelated portions of the information system are isolated from each other. All public internet facing systems are segregated from the production network through network segmentation, firewalling, logical access restrictions, and the use of a load balancers which restricts access to production infrastructure. The data importer's information security program prohibits the use of shared user accounts unless approved by management.

### 5. Encryption and Transmission

All data classified as potentially sensitive is encrypted at the database level while at rest. All media containing sensitive data, including electronic, hardcopy, and photocopy, is destroyed when it is no longer needed for business or legal reasons as defined in the data importers' terms of service.

All data in transit is encrypted including the following:

* **(a)** Information transmitted over the public internet (HTTPS)
* **(b)** Data transferred within system components (TLS)
* **(c)** Data transferred between organisations (SFTP)

Access to modify data transmission protocols is limited to appropriate individuals based on job function, current employment status, and inquiry with the data importer's management team.

All authentication and data transmission to the production applications, the operating systems hosting the applications, and associated production databases take place over secure transmission channels (i.e. VPN, SSH, SFTP, TLS). All production databases are encrypted using AES-256 bit encryption.

### 6. Data Backup, Recovery and Availability

The data importer performs incremental backups of its critical information systems on a daily basis, and full backups are performed on at least a weekly basis. The data importer’s management is alerted in the case of a backup failure, and backup failures are tracked to remediation.

Established entity standards exist for infrastructure and software hardening and configurations for key system components and infrastructure. The data importer has established a business continuity plan and disaster recovery plan, both of which are reviewed, tested, and updated on an annual basis.

Customer data is backed up for 90 days in the primary data store, unless otherwise stated in the Customer’s contract. After 90 days, unless otherwise stated in Customer’s contract, it becomes the customer’s responsibility to manage, back up, or otherwise store their data per their use case.

All primary data stores are retained for at least 90 days unless otherwise specified in the customer’s contract.

To ensure data availability and avoid issues with data older than 90 days, customers are advised to configure webhooks in their dashboard account. All data received via webhooks should be backed up securely on their end.

The Data importer is fully responsible for the availability of product and services.

### 7. Incident Management and System Monitoring

The data importer's management team has implemented an incident response plan that outlines the requirements for responding to anomalies that are indicative of malicious acts, natural disasters, and errors affecting the entity's ability to meet its objectives.

Security events are documented, reviewed, and tracked to final remediation by data importer's management team. A root cause analysis is conducted to determine the cause and mitigate the risk of such an incident occurring in the future.

The data importer has security monitoring tools in place to monitor the data importer's production environment and provide an ongoing solution to monitor security threats and unusual system activities. The data importer's management team receives alerts from the tools, based on predefined thresholds, and confirmed security issues are tracked to remediation.

The data importer engages a third-party to perform external penetration tests of the system on an annual basis. Management assesses and prioritises the results of the penetration test and tracks issues of medium criticality or above to final remediation.

### 8. Asset and Software Management

The data importer has implemented a change management policy that outlines the requirements for authorisation, design, development, configuration, documentation, testing, approval, and implementation of changes to infrastructure, data, and software. All system changes are tested, reviewed, and approved prior to implementation to the production environment. Access to make changes to source code is limited to only appropriate individuals based on job function and active employment with the data importer.

Version control software is in place to manage current versions of source code. Audit logs of all commits to source code libraries are maintained.

Source code scans are performed on in-scope application source code to detect potential vulnerabilities prior to the release of source code into the production environment. Any high-risk vulnerabilities are tracked to remediation prior to the promotion of each change into the production environment.

### 9. Physical Security

The data importer has a cloud-based infrastructure in AWS and relies on this subservice organisation to operate physical access controls to the data centres hosting the data importer's infrastructure. Additionally, the data importer does not own any facilities containing information assets which would require physical security controls to be implemented.

### 10. Endpoint Security

The data importer has enforced the following mobile device hardening standards for laptops and mobile phones:

* **(a)** Evidence of device encryption
* **(b)** Enterprise antivirus enabled
* **(c)** Antivirus daily updates
* **(d)** Requirement of user name and password
* **(e)** Patches or regular OS updates

All laptops with access to the data importer's network are configured to enforce hard drive encryption.

The data importer's security policy prohibits the use of removable media storage without prior approval from management.

Anti-virus/anti-malware software is installed on workstations and laptops supporting the system. Antivirus software is configured to receive an updated virus signature at least daily. Network operations receives a report of devices that have not been updated in more than 24 hours and follows up on those devices.

### 11. Service providers

The data importer has written contracts in place with service providers which require them to implement appropriate security measures to protect the personal data to which they have access and to limit the use of personal data in accordance with the data importer's instructions.

### 12. Customer Communications

The data importer has reporting mechanisms in place for reporting security issues and compliance concerns from internal and external system users. Each report is reviewed by appropriate management personnel, based on the nature of the suspected security issues, in accordance with the data importer's Incident Response Policy.

Security incidents and unauthorised disclosures of internal or external user data are communicated to data subjects, relevant legal and regulatory authorities, and others as required by law, contract, or at the advice of legal counsel, per the incident response plan.

Customer responsibilities, which include responsibility for reporting operational failures, incidents, problems, concerns, and complaints, and the process for doing so, are described within customer agreements. The data importer communicates relevant security and privacy commitments, made available on its public-facing website or by written request.

When major changes to security or privacy commitments are made, FingerprintJS communicates these changes to impacted stakeholders via email.

System descriptions are made available to authorised external users that delineate the boundaries of the system and describe relevant system components as well as the purpose and design of the system.

### 13. Staff training and awareness

The data importer maintains security policies and procedures which communicate objectives and responsibilities for internal control, necessary to support the function of internal control. Policies and procedures are made available to employees in the data importer's policy document repository.

The data importer has established standards and guidelines for management's, employees', and contractors' ethical behaviour, as outlined in the data importer's employee handbook. The handbook includes a termination policy for personnel who violate the data importer's policies and procedures, which may include disciplinary action up to and including involuntary termination.

All employees and contractors are required to sign an employment agreement, that requires personnel to adhere to the data importer's code of conduct, security, and confidentiality policies and procedures as part of their initial terms and conditions of employment.

The data importer has implemented a formal disciplinary process to address instances of noncompliance with the data importer's standards of conduct related to security which includes disciplinary measures up to and including termination.

Roles and responsibilities are defined by written job descriptions and communicated to the data importer's employees upon hire, as well as to their managers and supervisors.

Management monitors personnel compliance with the code of conduct through a complaint submission system which serves as a mechanism for reporting deviations from the code of conduct. Any deviations to the code of conduct are addressed immediately in accordance with the employee handbook.

## Schedule 4 — List of Sub-processors

| Name                               | Address                                              | Processing Activities                                                                           |
| ---------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Amazon Web Services, Inc (AWS)** | 410 Terry Avenue North, Seattle, WA 98109-5210       | Our primary provider for data processing infrastructure.                                        |
| **Rollbar, Inc.**                  | 510 Federal Street Suite 401 San Francisco, CA 94107 | Used for error tracking and reporting; may access IP addresses in specific debugging scenarios. |
| **AC PM, LLC (d/b/a Postmark)**    | 1 N Dearborn Street, Suite 500, Chicago, IL 60602    | Our transactional email provider, which has access to account email addresses.                  |
| **WorkOS, Inc.**                   | 548 Market St, PMB 86125, San Francisco, CA 94104    | Provides SAML SSO functionality and also has access to account email addresses.                 |

## Schedule 5 — Standard Contractual Clauses

### 1. EU SCCS

With respect to any transfers referred to in Section 3.1, the Standard Contractual Clauses shall be completed as follows:

#### 1.1

The Controller Clauses will apply with respect to FingerprintJS's processing of Administration Data, Usage Data and Fraud Identification Data for Controller Purposes; otherwise, the Processor Clauses will apply to FingerprintJS’s processing of Customer Personal Data.

#### 1.2

Clause 7 of the Standard Contractual Clauses (*Docking Clause*) does not apply.

#### 1.3

Option 2 of Clause 9(a) (*General written authori**s**ation*) shall apply, and the time period to be specified is determined in Section 4.3 of the DPA.

#### 1.4

The option in Clause 11(a) of the Standard Contractual Clauses *(Independent dispute resolution body*) does not apply.

#### 1.5

With regard to Clause 17 of the Standard Contractual Clauses (*Governing law*), the Parties agree that option 1 will apply and the governing law will be Irish law.

#### 1.6

In Clause 18 of the Standard Contractual Clauses (*Choice of forum and jurisdiction*), the Parties submit themselves to the jurisdiction of the courts of Ireland.

#### 1.7

For the Purpose of Annex I of the Standard Contractual Clauses: (i) Schedule 1 contains the specifications regarding the parties and the competent supervisory authority; and (ii) in respect of the Processor Clauses: Part 1 of Schedule 2, and in respect of the Controller Clauses: Part 2 of Schedule 2, contains the specifications regarding the description of transfer.

#### 1.8

For the Purpose of Annex II of the Standard Contractual Clauses, Schedule 3 of the DPA contains the technical and organisational measures.

### 2. UK Addendum

#### 2.1

This paragraph 2 (*UK Addendum*) shall apply to any transfer of Customer Personal Data from the Customer (as data exporter) to FingerprintJS (as data importer), to the extent that:

* **(a)** the UK Data Protection Laws apply to the Customer when making that transfer; or
* **(b)** the transfer is an "onward transfer" as defined in the Approved Addendum.

#### 2.2

As used in this paragraph 2:

"**Approved Addendum**" means the template addendum, version B.1.0 issued by the UK Information Commissioner under S119A(1) Data Protection Act 2018 and laid before the UK Parliament on 2 February 2022, as it may be revised according to Section 18 of the Approved Addendum.

"**UK Data Protection Laws**" means all laws relating to data protection, the processing of Personal Data, privacy and/or electronic communications in force from time to time in the UK, including the UK GDPR and the Data Protection Act 2018.

#### 2.3

The Approved Addendum will form part of this DPA with respect to any transfers referred to in paragraph 2.1, and execution of the Agreement or this DPA shall have the same effect as signing the Approved Addendum.

#### 2.4

The Approved Addendum shall be deemed completed as follows:

* **(a)** the "Addendum EU SCCs" shall refer to the SCCs as they are incorporated into this Agreement in accordance with Section 3.1 and this Schedule 5;
* **(b)** Table 1 of the Approved Addendum shall be completed with the details in Schedule 1;
* **(c)** the "Appendix Information" shall refer to the information set out in Schedule 1, Schedule 2 (as relevant, with respect to the Controller Clauses and Processor Clauses), Schedule 3 and Schedule 4;
* **(d)** for the purposes of Table 4 of the Approved Addendum, FingerprintJS (as data importer) may end this DPA, to the extent the Approved Addendum applies, in accordance with Section ‎19 of the Approved Addendum; and
* **(e)** Section 16 of the Approved Addendum is not used.

### 3. Swiss addendum

#### 3.1

This Swiss Addendum will apply to any processing of Customer Personal Data that is subject to Swiss Data Protection Laws or to both Swiss Data Protection Laws and the GDPR.

#### 3.2 Interpretation of this Addendum

* **(a)** Where this Addendum uses terms that are defined in the Standard Contractual Clauses, those terms will have the same meaning as in the Standard Contractual Clauses. In addition, the following terms have the following meanings:

"**Addendum**" means this addendum to the Clauses;

"**Clauses**" means the Standard Contractual Clauses as incorporated into this DPA in accordance with Section 3.1 and as further specified in this Schedule 5; and

"**FDPIC**" means the Federal Data Protection and Information Commissioner.

* **(b)** This Addendum shall be read and interpreted in a manner that is consistent with Swiss Data Protection Laws, and so that it fulfils the Parties' obligations under Article 16(2)(d) of the FADP.
* **(c)** This Addendum will not be interpreted in a way that conflicts with rights and obligations provided for in Swiss Data Protection Laws.
* **(d)** Any references to legislation (or specific provisions of legislation) means that legislation (or specific provision) as it may change over time. This includes where that legislation (or specific provision) has been consolidated, re-enacted and/or replaced after this Swiss Addendum has been entered into.
* **(e)** In relation to any processing of Personal Data subject to Swiss Data Protection Laws or to both Swiss Data Protection Laws and the GDPR, this Addendum amends and supplements the Clauses to the extent necessary so they operate:
  * **(i)** for transfers made by the data exporter to the data importer, to the extent that Swiss Data Protection Laws apply to the data exporter’s processing when making that transfer; and
  * **(ii)** as standard data protection clauses approved, issued or recognized by the FDPIC for the purposes of Article 16(2)(d) of the FADP.

#### 3.3 Hierarchy

In the event of a conflict or inconsistency between this Addendum and the provisions of the Clauses or other related agreements between the Parties, existing at the time this Addendum is agreed or entered into thereafter, the provisions which provide the most protection to data subjects will prevail.

#### 3.4

**Changes to the Clauses for transfers exclusively subject to Swiss Data Protection Laws**

To the extent that the data exporter's processing of Personal Data is exclusively subject to Swiss Data Protection Laws, or the transfer of Personal Data from a data exporter to a data importer under the Clauses is an "onward transfer" (as defined in the Clauses, as amended by the remainder of this paragraph 3.4) the following amendments are made to the Clauses:

* **(a)** References to the "Clauses" or the "SCCs" mean this Swiss Addendum as it amends the SCCs.
* **(b)** Clause 6 Description of the transfer(s) is replaced with:

"*The details of the transfer(s), and in particular the categories of Personal Data that are transferred and the purpose(s) for which they are transferred, are those specified in* *Schedule 1* *of this DPA where Swiss Data Protection Laws apply to the data exporter’s* *processing when making that transfer*."

* **(c)** References to "Regulation (EU) 2016/679" or "that Regulation" or ""GDPR" are replaced by "Swiss Data Protection Laws" and references to specific Article(s) of "Regulation (EU) 2016/679" or "GDPR" are replaced with the equivalent Article or Section of Swiss Data Protection Laws extent applicable.
* **(d)** References to Regulation (EU) 2018/1725 are removed.
* **(e)** References to the "European Union", "Union", "EU" and "EU Member State" are all replaced with "Switzerland".
* **(f)** Clause 13(a) and Part 3 of Annex 1.C. are not used; the "competent supervisory authority" is the FDPIC;
* **(g)** Clause 17 is replaced to state: "*These Clauses are governed by the laws of Switzerland*".
* **(h)** Clause 18 is replaced to state: "*Any dispute arising from these Clauses relating to Swiss Data Protection Laws will be resolved by the courts of Switzerland. A* *data* *subject may also bring legal proceedings against the data exporter and/or data importer before the courts of Switzerland in which he/she has his/her habitual residence. The Parties agree to submit themselves to the jurisdiction of such courts*."

#### 3.5

**Supplementary provisions for transfers of Personal data subject to both the GDPR and Swiss Data Protection Laws**

* **(a)** To the extent that the data exporter's processing of Personal Data is subject to both Swiss Data Protection Laws and the GDPR, or the transfer of Personal Data from a data exporter to a data importer under the Clauses is an "onward transfer" under both the Clauses and the Clauses as amended by paragraph 3.4 of this Addendum:
  * **(i)** for the purposes of Clause 13(a) and Annex I.C.:
    * **(A)** the FDPIC shall act as competent supervisory authority with respect to any transfers of Personal Data to the extent Swiss Data Protection Laws apply to the data exporter's processing when making that transfer, or such transfer is an "onward transfer" as defined in the Clauses (as amended by paragraph 3.4 of this Addendum); and
    * **(B)** subject to the provisions of paragraph 2 of this Schedule 5 (UK Addendum), the supervisory authority identified in Schedule 1 shall act as competent supervisory authority with respect to any transfers of Personal Data to the extent the GDPR applies to the data exporter's processing, or such transfer is an "onward transfer" as defined in the Clauses.
* **(b)** The terms "European Union", "Union", "EU", and "EU Member State" shall not be interpreted in a way that excludes the ability of data subjects in Switzerland bringing a claim in their place of habitual residence in accordance with Clause 18(c) of the Clauses.

What’s Next

* [Start your free subscription now](https://dashboard.fingerprintjs.com/signup/)


# Overview
Source: https://docs.fingerprint.com/docs/drn-overview



Fingerprint identifies millions of Android devices globally every month.

For each identified Android device, we generate and store a unique visitor ID and a collection of Smart Signals. When a device is identified again, additional Smart Signal data is added to the existing dataset. Often, when companies identify an Android device using our Android SDK, that device has already been recognized by other companies.

Since Fingerprint has a global database of Android device intelligence, we're offering it through our new Device Reputation Network (DRN) API. With this API, you can query our network using the visitor ID from a device you've identified. Unlike our [event-based Server API](/reference/server-api-get-event) , the DRN provides globally aggregated Smart Signals.

The DRN API is free to use, but is rate limited to prevent abuse. If you want to request a higher rate limit, contact us at `drn@fingerprint.com`.

<Tip>
  **DRN API requests do not count toward your monthly plan and are not billed.**
</Tip>

## Before you use the DRN

To get started, you’ll need to use our [Android SDK](/docs/native-android-integration#fingerprint-identification-sdk-for-android).

Please note, the iOS SDK and JavaScript agent SDK are not supported at this time.

After creating a Fingerprint account, integrate the Android SDK into your app to start identifying devices. For detailed instructions, refer to our Android integration guide. Once a device is identified, you can retrieve the visitor ID directly on the device, or if you're using our Zero Trust Mode and don't trust the devices, you can obtain it through a server-side API call.

With the Android device's visitor ID, you're ready to make an API call to the DRN.

## Making your first DRN API call

Ensure you have your secret API key and visitor ID, then make the following request:

#### `GET https://drn-api.fpjs.io/drn/{visitor_id}?signals={signals}`

Replace `{visitor_id}` with the visitor ID and provide signals you want. We support one or more signals in the `signals` query parameter. Use a comma separated list for the signal list.

In version `2024-09-01`, the DRN supports three global signals: **`regional_activity`**, **`suspect_score`**, and **`timestamps`**. More details about each signal are in the sections below.

If you want to request all three signals and your visitor ID is **`NSBNxrgR3h9hVkhR5mkc`**, the request will look like this:

```shell cURL theme={"theme":"github-dark-dimmed"}
curl --request GET \
  --url 'https://drn-api.fpjs.io/drn/NSBNxrgR3h9hVkhR5mkc?signals=regional_activity,suspect_score,timestamps' \
  --header 'Authorization: Bearer {secret-api-key}' \
  --header 'X-API-Version: 2024-09-01'
```

Make sure you provide your secret API key in the `Authorization` HTTP header. You can read all the details in our [DRN API reference](/reference/drn-api-overview).

## Global DRN signals

As of version `2024-09-01`, DRN supports three global signals:  **`regional_activity`,`suspect_score`, and`timestamps`** .

Additionally, DRN supports **chargeback and payment disputes reporting**. Using this feature, you can get a detailed information if an Android device is linked to chargebacks reported by other Fingerprint customers.

### regional\_activity

Represents a list of countries where the identified device was active in the last 30 days together with the level of activity in each country. Level of activity is a number between 0 and 1 and represents the percentage of activity in the country. For example if a device was active in a specific country 60% of the time, the level of activity will be `0.6`. [API reference](/reference/drn-api-get-by-visitor-id) . Note that the level of activity is scoped to a detector type.

We support two detector types: `ip` and `origin`. The `ip` detector detects a country code by the IP address at the moment of making an API call using the Android SDK. If a device is using a VPN, the `ip` detector will return the VPN exit node country.

The `origin` detector detects a real location of the device, utilizing our `originCountry` [feature](/docs/smart-signals-reference#vpn_origin_country)  of the mobile SDK VPN detection, regardless of the IP address location or attempts to hide the location using VPN. The `origin` detector does not require geolocation permissions from the user.

**Examples of different`activityPercentage` scenarios:**

| Real location country | Using VPN? | VPN IP country |
| :-------------------- | :--------- | :------------- |
| USA                   | no         | n/a            |

```json theme={"theme":"github-dark-dimmed"}
{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0},
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}
```

| Real location country | Using VPN? | VPN IP country        |
| :-------------------- | :--------- | :-------------------- |
| USA                   | yes        | USA, 100% of the time |

```json theme={"theme":"github-dark-dimmed"}
{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0},
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}
```

| Real location country | Using VPN? | VPN IP country        |
| :-------------------- | :--------- | :-------------------- |
| **Russia**            | yes        | USA, 100% of the time |

```json theme={"theme":"github-dark-dimmed"}
{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 1.0}
      ]
    },
    {
      "code": "RU",
      "detectors": [
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}
```

| Real location country | Using VPN? | VPN IP country          |
| :-------------------- | :--------- | :---------------------- |
| **Russia**            | yes        | USA, 60% of the time    |
| **Russia**            | yes        | Canada, 40% of the time |

```json theme={"theme":"github-dark-dimmed"}
{
  "countries": [
    {
      "code": "US",
      "detectors": [
        {"type": "ip", "activityPercentage": 0.6}
      ]
    },
    {
      "code": "CA",
      "detectors": [
        {"type": "ip", "activityPercentage": 0.4}
      ]
    },
    {
      "code": "RU",
      "detectors": [
        {"type": "origin", "activityPercentage": 1.0}
      ]
    }]
}
```

Regional activity gives a clear understanding where a device was physically located during the last 30 days and also where it wanted to **appear to be located**. Analyzing the detector types and the origin country helps prevent geo-related fraud.

**Output format**:

[API reference available in this document](/reference/drn-api-get-by-visitor-id).

```json theme={"theme":"github-dark-dimmed"}
"regionalActivity": [
  // RFC 3339 format, goes 30 days back from the time request received on the server in UTC
  "startDate": "2023-12-16T23:12:59Z",
  // The time the request was received on the server in UTC
  "endDate": "2024-01-16T23:12:59Z",
  // One country object per country of activity. 
  // One or two detectors are possible in each country.
  "countries": [
    {
      // Country codes are capitalized as defined in the ISO 3166-1 alpha 2 standard
      "code": "US" | "GB" | ...,
      "detectors": [
        {
          // Two detector types: "ip" and "origin"
          // "ip"-when the country is detected by IP address
          // "origin"-when the country is detected by "originCountry" feature of our VPN detection.
          // "origin" represents the country of real location
          "type": "ip" | "origin",
          // A number that's always > 0 and <= 1.
          "activityPercentage": Number
        }]
    }]
}
```

**Output example**:

```javascript theme={"theme":"github-dark-dimmed"}
// Device is physically based in Mexico and is also active in the US 20% of the time via VPN.
// Its response could look like this, 
// assuming the originCountry is available 
// (if the device is using the supported version of Android SDK).
// Note that one API call response can have both "origin" and "ip" at the same time, 
// because even when the originCountry is available, we should also use the IP country 
// (to capture the fact of the VPN usage).
"regionalActivity": {
  // Use RFC 3339 format, goes 30 days back from the time request received on the server.
  // UTC time zone
  "startDate": "2023-12-16T23:12:59Z",
    // The time the request was received on the server in UTC timezone
    "endDate": "2024-01-16T23:12:59Z",
    "countries": [
        // it's clear device is based in MX physically
        {
          "code": "MX",
          "detectors": [
            { "type": "origin", "activityPercentage": 1 },
            { "type": "ip", "activityPercentage": 0.8 }
          ]
        },
        // but 20% of the time makes VPN calls out of the US IP address
        { "code": "US", "detectors": [{ "type": "ip", "activityPercentage": 0.2 }] }
      ]
}
```

### suspect\_score

Suspect Score is a single value representing how many suspicious Smart Signals were in a particular request. You can read more in this [Smart Signals Guide](/docs/suspect-score) . The suspect score is  calculated for each Fingerprint API request that your application makes with Android SDK.

The DRN version of the `suspect_score`  is powerful, as it represents the minimum and maximum suspect scores we captured from the identified device in the last 30 days **globally** across the entire Fingerprint device network.

The maximum value contains a zero-excluded percentile, that makes it easy to see how suspicious that device was compared to **other suspicious devices**. For example if the percentile of the maximum suspect score is 0.95, it means that device was more suspicious than 95% of **other suspicious devices** in the same 30-day time period.

**Output format** :

You can find the reference in this [API reference document](/reference/drn-api-get-by-visitor-id).

**Output example**:

```javascript theme={"theme":"github-dark-dimmed"}
"suspectScore": {
  // Time in RFC 3339 format, goes 30 days back from the time request received on the server in UTC
  "startDate": "2023-12-16T23:12:59Z",
  // The time the request was received on the server in UTC
  "endDate": "2024-01-16T23:12:59Z",
  // Minimum suspect score we captured globally for the identified Android device
  "minimum": {
    // Almost always will be zero, cannot be negative.
    // In rare cases will be > 0, 
    // when this device consistently generated a suspect score value greater than zero.
    // In this case, this device used a proxy all the time.
    "value": 3,
      // The signals object lists all the Smart Signals that contributed to the suspect score
      "signals": {
      "proxy": 3
    }
  },
  // Maximum suspect score we captured globally for the identified Android device
  "maximum": {
    // Most of the time will be 0, but sometimes will be > 0 for suspicious devices.
    // When you see a particularly high maximum value for a device, you need to review this device's activity
    "value": 20,
      // Zero-excluded percentile
      // E.g. a .75 value means the max suspect score is higher than 75% of
      // non-zero max suspect scores.
      // You can use this number to understand how high this max suspect score is
      // compared to other suspicious devices with non-zero maximum scores.
      // Can take four possible values: 0.25, 0.5, 0.75, and 0.95.
    "percentile": 0.75
      // The list of signals that contributed to the maximum captured suspect_score value.
      // Only the signal names with non-zero contribution will be used, together with their respective values.
      // Signal names and values are at the time of capturing the suspect score.
      // For a full reference for all possible values, see: /reference/server-api-get-event
    "signals": {
        // Nested Smart Signals can be used, compatible with the Server API response.
        "ipBlockList": 12,
          "vpn": {
          "publicVPN": 5
        },
        "proxy": 3
      }
  }
}
```

### timestamps

Represents timestamps when we first and last saw this device on the Fingerprint device network. Knowing when a device was first seen can be useful as the devices that appeared recently (a few minutes ago) are suspicious. Output format is described in the [API reference.](/reference/drn-api-get-by-visitor-id)

**Output example**:

```javascript theme={"theme":"github-dark-dimmed"}
"timestamps": {
  "firstSeenAt": "2023-12-29T23:12:00Z" // RFC3339 formatted UTC time with minute precision
  "lastSeenAt": "2023-12-29T23:12:00Z" // RFC3339 formatted UTC time with minute precision
}
```

### Payment dispute reporting

You can query the DRN for payment dispute information, associated with each Android device. This information is submitted by other companies, using the DRN.

Report  format:

```json json theme={"theme":"github-dark-dimmed"}
{
  "data": {
    "reports": [
      {
        "type": "card_dispute",
        "startDate": "2023-12-16T23:12:59Z",
        "endDate": "2024-12-16T23:12:59Z",
        "count": 20,
        "activityPercentile": .25 | .5 | .75 | .95,
        "amounts": [
          { "currency": "INR", "avgAmount": 270.15 },
          { "currency": "AED", "avgAmount": 650.19 },
          {"currency": "USD", "avgAmount": 45.6 },
        ]
      }
    ]
  }
}
```

To access the DRN payment dispute report API, please submit your inquiry to [drn@fingerprint.com](mailto:drn@fingerprint.com)

## Smart Signal aggregation notes

When you use the DRN API, you will always use the device's visitor ID value to query the network. Sometimes a device is only identified by Fingerprint through your workspace, and sometimes a device is identified by Fingerprint through multiple workspaces that belong to multiple companies.

### Multiple companies

When multiple companies use Fingerprint API to identify a device, DRN will aggregate the data from multiple companies' data sets. For example, if Company A identified a device on 2023-01-01, and Company B identified the same device on 2024-01-01, the information from both Smart Signals will be available, but the aggregations will go only 30 days back.

### Single company

If only one company identifies a device, the data will be aggregated only from that single company data set.


# Identification using pseudonymized IP Address
Source: https://docs.fingerprint.com/docs/identification-using-pseudonymized-ip-address



The originating event's IP address is an important signal that Fingerprint Identification relies upon to accurately identify browsers and mobile devices. Normally, Fingerprint Identification stores the IP address as plain text and uses it in its identification algorithms.

Several regulatory frameworks (e.g. [GDPR](https://gdpr-info.eu/), US Privacy Laws, including [CCPA](https://oag.ca.gov/privacy/ccpa)) have classified IP addresses as Personally Identifiable Information (PII). When you use Fingerprint Identification for purposes with a [legitimate interest](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/legal-grounds-processing-data_en#legitimate-interests-of-the-controller:~:text=A%20company/organisation%20may,of%20its%20IT%20systems.), these frameworks allow you to store these IP addresses (PII) as plain text.

On the other hand, if you use Fingerprint Identification for purposes that do not fall under *legitimate interest*, then these frameworks recommend using [pseudonymized](https://en.wikipedia.org/wiki/Pseudonymization) IP addresses as an alternative to comply with regulations.

Accordingly, we have introduced a new form of Identification that uses pseudonymized IP addresses. In this approach, the original IP address is combined with other metadata and then cryptographically transformed into an unrecognizable, binary value after which it is used by our identification algorithms. It is impossible to retrieve the original IP address from this unrecognizable binary value.

Identification using pseudonymized IP addresses is a worthwhile alternative to experience the core capabilities of the Fingerprint Device Intelligence platform without compromising on identification accuracy and regulatory compliance.

## Identification using regular IP address vs. pseudonymized IP address

Several features in Fingerprint’s Device Intelligence platform that rely on the IP address being available in plain text will not be available when using a pseudonymized IP address. For example, IP Geolocation and several Smart Signals (e.g. `vpn`, `ipInfo`) will not be available. The table below outlines the differences between the two approaches:

| Feature                                                                                                                                                       | Identification using regular IP address | Identification using pseudonymized IP address                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How is the IP address stored?                                                                                                                                 | It is stored as plain text.             | It is combined with other metadata, transformed into an unrecognizable binary value, and then stored.                                                                                                                                                                                                                                                                                                                                                                          |
| Can the original IP address be retrieved?                                                                                                                     | Yes, in identifiable clear text.        | **No**. It is impossible to retrieve the original IP address from the binary value.                                                                                                                                                                                                                                                                                                                                                                                            |
| How does the IP address appear in responses to JavaScript agent / SDK requests, [Server API ](/reference/server-api)requests, and [Webhooks](/docs/webhooks)? | Original, unmodified IP address.        | **0.0.0.0**                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Is [IP Geolocation](/docs/smart-signals-reference#ip-geolocation) available in responses?                                                                     | Yes                                     | **No**                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Are all [Smart Signals](/docs/smart-signals-reference) available?                                                                                             | Yes                                     | **No**. [Browser Bot Detection](/docs/smart-signals-reference#browser-bot-detection), [IP Geolocation](/docs/smart-signals-reference#ip-geolocation), [IP Blocklist Matching](/docs/smart-signals-reference#ip-blocklist-matching), [Proxy Detection](/docs/smart-signals-reference#proxy-detection), [Velocity Signals](/docs/smart-signals-reference#velocity-signals), and [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-browsers) will not be available. |

## Enabling pseudonymized IP addresses for your workspace

When pseudonymized IP addresses are enabled for your workspace:

* You can continue to use the same workspace.
* Your users will continue to be identified using the same visitor ID as before.
* Identification accuracy, when compared to standard identification, can be slightly lower.

If you would like to try this feature for your workspace, please [contact our support team](https://fingerprint.com/support/).


# Identifying in-app browsers for iOS
Source: https://docs.fingerprint.com/docs/identifying-in-app-browsers-for-ios



An in-app browser is a browser that is “embedded” within a mobile app. It allows your iOS app to display web content without requiring your app to open a separate browser.

For iOS, in-app browsers are typically implemented using one of the following:

1. [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview)
2. [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller)
3. [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)

This article will help you understand how

* Fingerprint identifies each of these in-app browsers
* Fingerprint Identification can be influenced by the different options available to configure these in-app browsers

# In-app browsers at a glance

1. **WKWebView**
   1. You can configure it with either a
      1. [Default data store](https://developer.apple.com/documentation/webkit/wkwebsitedatastore/1532937-default) that allows you to save website data to a disk. (OR)
      2. [Non-persistent data store](https://developer.apple.com/documentation/webkit/wkwebsitedatastore/1532934-nonpersistent) that allows you to save the website data to memory. Typically, private browsing sessions are implemented using this type of data store.
   2. It does not share website data and sessions with Safari.
2. **SFSafariViewController**
   1. Unlike WKWebView, there aren’t any options for configuring the data store.
   2. It does not share website data and sessions with Safari.
3. **ASWebAuthenticationSession**
   1. You can request to share cookies and other browsing data from this session with the user’s default browser. See [`prefersEphemeralWebBrowserSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession/3237231-prefersephemeralwebbrowsersessio) to learn more.

# Fingerprint Identification across in-app and web browsers

The three listed in-app browsers do not share cookies and website data. Fingerprint can still generate the same visitor ID using alternate identification methods that do not rely on cookies and website data (aka *probabilistic identification*) for a few combinations where cookies and website data are unavailable.

In this section, we will enumerate several scenarios to help you understand the cases where Fingerprint Identification will produce the same visitor ID and those where it will not.

## Scenario 1: In-app browsers vs. web browsers

If you would like to identify your users across your app and your website, here are a few things to remember:

* The visitor ID generated for a WKWebView, irrespective of how its data store is configured, is **different** from the visitor ID generated for your web browser.
* SFSafariViewController does not share cookies and website data with the Safari browser. Even then, Fingerprint in most cases will be able to generate the same visitor ID for these two browsers.
* An ephemeral ASWebAuthenticationSession or a WKWebview session configured with a non-persistent data store is always treated as a private browsing session. Such in-app browser sessions can only be *probabilistically* identified.

### Cheat sheet

* The header column represents the various in-app browsers.
* The header row represents a few of the web browsers. Let’s assume Safari is the user’s default web browser.
* ✅ indicates that the visitor ID remains the same between the specified in-app browser and the web browser.
* ❌ indicates that the visitor ID is different between the specified in-app browser and the web browser.

<img alt="" />

## Scenario 2: Your app launches several types of in-app browsers

In general,

* If your app uses the **same type of in-app browser** (e.g. `ASWebAuthenticationSession`) in two different places, then irrespective of how they are configured, Fingerprint will be able to generate the same visitor ID for both these browsers.
* The visitor ID generated for a `WKWebView` will always be different from the visitor ID generated for the other in-app browsers.

The cheat sheet below will serve as a good reference for how the different configurations that you use to create these in-app browsers can influence Fingerprint Identification.

### Cheat sheet

* The header column represents cases where the specified in-app browser is a first-time browser.
* The header row represents cases where the specified in-app browser is a returning browser.
* ✅ indicates that the returning in-app browser was given the same visitor ID as the first-time browser.
* ❌ indicates that the returning in-app browser was given a visitor ID different from that of the first-time browser.

<img alt="" />

## Scenario 3:  Your SDK launches several types of in-app browsers

If you implement several types of these in-app browsers in your SDK, the cheat sheet below will help you understand the different combinations of in-app browsers that will yield the same visitor ID across different apps.

### Cheat sheet

* The header column represents cases where the specified in-app browser is launched from App A.
* The header row represents cases where the specified in-app browser is launched from App B.
* ✅ indicates that the visitor ID remains the same between the specified in-app browsers across apps A and B.
* ❌ indicates that the visitor ID is different between the specified in-app browsers across apps A and B.

<img alt="" />


# iOS devices
Source: https://docs.fingerprint.com/docs/ios

Fingerprint's device intelligence platform for iOS devices.

Fingerprint's device intelligence platform is also available for iOS devices. Our device intelligence platform for iOS helps you to accurately identify the devices that interact with your mobile app and provides high-quality Smart Signals that will help you identify risky transactions before they happen.

To make integrations with mobile apps easier, we offer SDKs for apps built natively as well as for apps built using multi-platform frameworks (e.g. React Native).

A Fingerprint account is required to be able to use the Fingerprint Identification SDK in your mobile apps. If you do not have an account yet, please [sign up](https://dashboard.fingerprintjs.com/signup) for one.

<Check>
  **Download our** [**demo app**](https://apps.apple.com/us/app/fingerprint-pro/id1644105278) from App Store to see Fingerprint in action!
</Check>

## Device Identifier

When Fingerprint Identification SDK is integrated into your mobile app, for every device that interacts with your app, you will be able to receive a unique device identifier (i.e. `visitorId`). The visitor ID is derived solely from Apple's [identifierForVendor](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) (IDFV) property. The SDK does not use any fingerprinting techniques to identify a device.

However, despite the visitor ID being derived from IDFV, there are a few important differences between them:

* The visitor ID will remain the same even when the app is removed and re-installed whereas the IDFV will not.
* In addition to being scoped by the vendor, the visitor ID is also scoped by the [Fingerprint Workspace](/docs/glossary#fingerprint-workspace). It means the only time the visitor ID remains the same between two apps is when the apps are from the same vendor **and** when they belong to the same Fingerprint workspace.

<Info>
  **Did you know?**

  The device identifier generated by the iOS SDK (embedded within your mobile app) will be **different** from the visitor ID generated by the Javascript agent (embedded within your website).
</Info>

The identification accuracy, when compared with browsers, is better for iOS devices because the IDFV property has higher longevity than the signals used for identifying browsers.

For your reference, we have listed various scenarios where a visitor ID will remain the same before and after and where a new visitor ID will be created.

| Scenario                                                                                                                                                                                | Will I receive the same visitor ID before and after?                                                                                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The app or device is restarted                                                                                                                                                          | **Yes.** You will receive the same visitor ID even after the app or device is restarted.                                                                                                                                       |
| The app is uninstalled and re-installed again                                                                                                                                           | **Yes.** You will receive the same visitor ID even after the app is removed and installed again                                                                                                                                |
| The [provisioning profile](https://developer.apple.com/documentation/technotes/tn3125-inside-code-signing-provisioning-profiles) and/or the signing certificate of the app are changed. | **Yes.** You will receive the same visitor ID as long as the [AppID](https://developer.apple.com/library/archive/documentation/General/Conceptual/DevPedia-CocoaCore/AppID.html) remains the same before and after the change. |
| The device is jailbroken                                                                                                                                                                | **Yes.** You will receive the same visitor ID as before even after the device is jailbroken.                                                                                                                                   |
| [Lockdown mode](https://support.apple.com/en-us/HT212650) is enabled on the device                                                                                                      | **Yes.** You will receive the same visitor ID as before even after lockdown mode is enabled on the device.                                                                                                                     |
| [Reset device settings to their default values](https://support.apple.com/guide/iphone/return-iphone-settings-to-their-defaults-iphea1c2fe48/ios)                                       | **Yes.** You will receive the same visitor ID as before even after one or more of the device settings are reset to their default.                                                                                              |
| [The device is factory reset](https://support.apple.com/en-us/HT201274)(i.e. all content and settings are erased).                                                                      | **No**. After the device is factory reset, a new visitor ID will be generated.                                                                                                                                                 |

## iOS Smart Signals

Smart Signals are actionable device intelligence signals that help you to make informed decisions about the device and thus prevent fraud. These signals could be used as input to your machine learning models behind your fraud detection or risk mitigation engines. For example, when you know that a request is originating from a *jailbroken* device, you will be able to take additional precautionary security steps (e.g., multi-factor authentication).

When your mobile app requests a visitor ID, the SDK, along with the IDFV, will collect several other attributes from the device. The Smart Signals are deduced by combining these attributes with additional algorithms.

For iOS, the following Smart Signals are available:

* [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection)
* [Frida Detection](/docs/smart-signals-reference#frida-detection)
* [Geolocation Spoofing Detection](/docs/smart-signals-reference#geolocation-spoofing-detection)
* [IP Geolocation Detection](/docs/smart-signals-reference#ip-geolocation)
* [IP Blocklist Detection](/docs/smart-signals-reference#ip-blocklist-matching)
* [Jailbroken Device Detection](/docs/smart-signals-reference#jailbroken-device-detection)
* [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection)
* [Tampered Request Detection](/docs/smart-signals-reference#tampered-request-detection-for-mobile-apps)
* [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices)
* [iOS Simulator Detection](/docs/smart-signals-reference#ios-simulator-detection)
* [Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection-for-mobile-devices)
* [Smart Signals common for browsers and mobile devices](/docs/smart-signals-reference#smart-signals-common-for-browsers-and-mobile-devices)

These Smart Signals are available as part of our [Pro Plus and Enterprise plans](https://fingerprint.com/pricing/). If you are interested in one or more of these signals, please [contact our support team](https://fingerprint.com/support/) to enable them. Signing up for an Enterprise plan does not automatically enable these signals.

## Fingerprint Identification SDK for iOS

<Info>
  ### Current Version: 2.17.2

  For release notes and older versions, please visit the [Changelog for iOS SDK](/docs/changelog-ios-sdk) page.
</Info>

### Supported Versions

The minimum version that the iOS SDK for Fingerprint Identification supports is [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes), [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes). Per [Apple](https://developer.apple.com/support/app-store/) and [Statista](https://www.statista.com/statistics/565270/apple-devices-ios-version-share-worldwide/), this will allow your app to be compatible with a wide variety of active iOS devices.

As of May 2023, our SDK will allow your app to be compatible with more than 94% of the devices in the world.

### Getting Started Guides

Our Getting Started guides are aimed at helping you to integrate our SDK with your apps easily.

* For native iOS apps, see [Getting Started Guides > iOS](/docs/ios-sdk) and our [iOS quickstart](/docs/ios-quickstart).
* For apps built using Flutter, see our [Flutter SDK on GitHub](https://github.com/fingerprintjs/fingerprintjs-pro-flutter) and our [Flutter quickstart](/docs/flutter-quickstart).
* For apps built using React Native, see our [React Native SDK on GitHub](https://github.com/fingerprintjs/react) and our [React Native quickstart](/docs/react-native-quickstart).

## Privacy Manifest File Requirements for App Store

During WWDC 2023, Apple [introduced a new requirement](https://developer.apple.com/news/?id=av1nevon) where app and SDK developers must create privacy manifest files to declare the data that their app/SDK collects and the reasons for collecting this data. Accordingly, starting from v2.3.2, the Fingerprint Identification SDK for iOS will include a privacy manifest file. To learn more, please see [Understanding privacy manifest files](/docs/mobile-devices-understanding-privacy-manifest-files).

## FingerprintJS-iOS: Open-source identification library for iOS

We also provide a lightweight, open-source library called [fingerprintjs-ios](https://github.com/fingerprintjs/fingerprintjs-ios) which is available to use for free by everyone. Our commercial SDK, Fingerprint Identification for iOS, is based on our well-maintained, free, open-source library.

For your better understanding, here is a complete set of differences between our open-source library (`fingerprintjs-ios`) and our commercial SDK (`fingerprint-ios`).

|                                                                                       | FingerprintJS-iOS(fingerprintjs-ios)                                                                                                                                   | Fingerprint Identification for iOS(fingerprint-ios)                                                                                                                    |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Core Features                                                                         |                                                                                                                                                                        |                                                                                                                                                                        |
| **Attributes collected from the device**                                              | Basic (*e.g. OS, Model*)                                                                                                                                               | Advanced. Lot more attributes, in addition to those collected by the open-source library.                                                                              |
| **ID Type**                                                                           | A visitor ID that is solely derived from Apple's [identifierForVendor](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) property. | A visitor ID that is solely derived from Apple's [identifierForVendor](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor) property. |
| **ID Origin**                                                                         | The visitor ID is generated only from within the device. External servers are not involved.                                                                            | The visitor ID is generated from within the device and also processed in our servers.                                                                                  |
| **Is visitor ID the same across multiple apps on a single device?**                   | **No.** Unless the apps are from the same vendor.                                                                                                                      | **No.** Unless the apps are from the same vendor and belong to the same Fingerprint workspace.                                                                         |
| **ID Collisions**                                                                     | Common                                                                                                                                                                 | Very rare                                                                                                                                                              |
| Support for multi-platform frameworks                                                 |                                                                                                                                                                        |                                                                                                                                                                        |
| **Flutter**                                                                           | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| **React Native**                                                                      | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| Advanced Features                                                                     |                                                                                                                                                                        |                                                                                                                                                                        |
| **Server API and Webhooks**\*(Build flexible workflows)\*                             | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| **Mobile Smart Signals**\*(VPN Detection, Factory Reset, Geolocation Spoofing, etc)\* | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| **Geolocation**\*(Based on IP address)\*                                              | -                                                                                                                                                                      | **✓**                                                                                                                                                                  |
| Operations                                                                            |                                                                                                                                                                        |                                                                                                                                                                        |
| **Data security**                                                                     | Depends on your infrastructure                                                                                                                                         | Encrypted at rest                                                                                                                                                      |
| **Storage**                                                                           | Depends on your infrastructure                                                                                                                                         | Unlimited up to 1 year                                                                                                                                                 |
| **Regions**                                                                           | Depends on your infrastructure                                                                                                                                         | Global, EU and Asia data centers                                                                                                                                       |
| **Compliance**                                                                        | Depends on your infrastructure                                                                                                                                         | Compliant\*\*\* with GDPR, US Privacy Laws including CCPA, SOC 2 Type II, and ISO 27001                                                                                |
| **SLA**                                                                               | SLA is not provided                                                                                                                                                    | 99.9% Uptime                                                                                                                                                           |
| **General Support**                                                                   | GitHub Issues/Questions. Response times varies.                                                                                                                        | Dedicated support team that responds to chat, email, and calls within 1 business day                                                                                   |
| **Support for submitting an app to App Store**                                        | Not available.                                                                                                                                                         | Dedicated support will be provided to the extent resulting from using the Fingerprint Identification SDK.                                                              |
| How to get started?                                                                   | [Get it on GitHub](https://github.com/fingerprintjs/fingerprintjs-ios)                                                                                                 | [Sign up for a free 14-day trial](https://dashboard.fingerprintjs.com/signup/)                                                                                         |

\*\*In comparison to fingerprints, VisitorIDs are more accurate and stable identifiers because they are deduplicated, are processed further on the server, and utilize fuzzy matching. On the other hand, fingerprint hashes become unstable across time intervals greater than 2 weeks because they rely on an exact match of all browser attributes.

\*\*\*The company, Fingerprint, in its role as data processor is compliant with GDPR, US Privacy Laws (including CCPA) and SOC 2 Type II. It is also ISO 27001 certified. As a data controller, it is still your responsibility to be compliant with GDPR and US Privacy Laws (including CCPA) and use the identification result for legitimate purposes


# iOS SDK Changelog
Source: https://docs.fingerprint.com/docs/ios-sdk-changelog





# Management API
Source: https://docs.fingerprint.com/docs/management-api





# Fingerprint MCP server
Source: https://docs.fingerprint.com/docs/mcp-server

Connect AI assistants and agents to Fingerprint device intelligence

The Fingerprint MCP server connects AI assistants and agents to Fingerprint's device intelligence platform. Once connected, your AI tools can query identification events, detect anomalies, investigate fraud patterns, and manage your Fingerprint workspace through natural language.

The server is available in two forms:

* **Managed service**: Hosted by Fingerprint. No setup or maintenance required.
* **Open source**: Self-host anywhere for full control over deployment and configuration.

This guide covers the managed service. For self-hosting instructions, see the [GitHub repository](https://github.com/fingerprintjs/fingerprint-mcp-server).

## Prerequisites

To use the Fingerprint MCP server, you need an active Fingerprint account and permission to create API keys in your workspace. No additional setup is required before connecting. API keys and workspace access are configured automatically during the OAuth connection flow.

## Connection Details

### Server URL

```
https://mcp.fpjs.io/mcp
```

In Claude, you can connect from the connectors directory without entering this URL. It is still required for Claude Code, Cursor, VS Code, and other MCP clients.

## Authentication

The Fingerprint MCP server uses OAuth. When you connect your AI client, you will be redirected to the Fingerprint dashboard to authorize access and select the workspace to connect to. If you have only one workspace, the selection step is skipped automatically.

If your AI client does not support OAuth, you can authenticate by passing your API key directly in the client's configuration. Go to the [Fingerprint dashboard](https://dashboard.fingerprint.com/mcp) for configuration options.

## Installation

<Accordion title="Claude (Claude.ai / Claude Desktop)">
  Fingerprint is listed in the Anthropic connectors directory, so you do not need to enter the server URL. See the [Claude Connector documentation](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities) for general setup instructions.

  <Steps>
    <Step title="Open Connectors">
      Go to **Settings** > **Connectors** and click **Browse**.
    </Step>

    <Step title="Find Fingerprint">
      Search for `Fingerprint`, then click **Connect**.
    </Step>

    <Step title="Authorize">
      Complete the OAuth authorization in your browser when prompted, then select the workspace to connect.
    </Step>
  </Steps>

  **Adding Fingerprint as a custom connector**

  If the directory listing is not available to you, add the server manually instead.

  <Steps>
    <Step title="Open Connectors">
      Go to **Settings** > **Connectors** and add a custom connector.
    </Step>

    <Step title="Add the server">
      Set **Name** to `Fingerprint` and **URL** to `https://mcp.fpjs.io/mcp`, then click **Add**.
    </Step>

    <Step title="Connect">
      Find Fingerprint in the **Not connected** list and click **Connect**.
    </Step>

    <Step title="Authorize">
      Complete the OAuth authorization in your browser when prompted.
    </Step>
  </Steps>

  <Warning>
    Name the connector `Fingerprint`. Names containing dots, apostrophes, or accented characters can prevent Claude from finding the server's tools, while the connector still shows as connected.
  </Warning>
</Accordion>

<Accordion title="Claude Code">
  See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp#installing-mcp-servers) for general setup instructions.

  <Steps>
    <Step title="Add the server">
      Run the following command to add the Fingerprint MCP server:

      ```bash theme={"theme":"github-dark-dimmed"}
      claude mcp add --transport http fingerprint https://mcp.fpjs.io/mcp
      ```
    </Step>

    <Step title="Open the MCP menu">
      Start Claude Code and open the MCP menu:

      ```bash theme={"theme":"github-dark-dimmed"}
      claude
      /mcp
      ```
    </Step>

    <Step title="Authorize">
      Select Fingerprint and complete the OAuth authorization in your browser when prompted.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Cursor">
  See the [Cursor MCP documentation](https://cursor.com/docs/mcp#installing-mcp-servers) for general setup instructions.

  <Steps>
    <Step title="Open Cursor Settings">
      Go to **Cursor** > **Settings…** > **Cursor Settings**.
    </Step>

    <Step title="Add a custom MCP server">
      Navigate to **Tools & MCP** and click **Add Custom MCP**. Add this configuration to your `mcp.json`:

      ```json theme={"theme":"github-dark-dimmed"}
      {
        "mcpServers": {
          "Fingerprint": {
            "url": "https://mcp.fpjs.io/mcp"
          }
        }
      }
      ```
    </Step>

    <Step title="Connect">
      Return to **Tools & MCP** and click **Connect** to authenticate with Fingerprint in your browser.
    </Step>
  </Steps>
</Accordion>

<Accordion title="VS Code (GitHub Copilot)">
  See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for general setup instructions.

  **Quick setup:** Open the Command Palette (`Ctrl+Shift+P` / `⇧⌘P`), run **MCP: Add Server**, and follow the guided flow for remote servers.

  **Manual setup:**

  <Steps>
    <Step title="Open your MCP config">
      Create or open `.vscode/mcp.json` in your project (to share with your team), or open the Command Palette and run **MCP: Open User Configuration** to configure across all workspaces.
    </Step>

    <Step title="Configure the server">
      Add the following to your `mcp.json`:

      ```json theme={"theme":"github-dark-dimmed"}
      {
        "servers": {
          "Fingerprint": {
            "type": "http",
            "url": "https://mcp.fpjs.io/mcp"
          }
        }
      }
      ```
    </Step>

    <Step title="Connect">
      Save the file. Click **Start** above the Fingerprint server entry, then complete the OAuth authorization in your browser.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Other MCP Clients">
  Any MCP-compatible client can connect to the Fingerprint MCP server.

  <Steps>
    <Step title="Add the server">
      Follow your client's documentation for adding an MCP server.
    </Step>

    <Step title="Configure the URL">
      Set the server URL to `https://mcp.fpjs.io/mcp`.
    </Step>

    <Step title="Authorize">
      Authenticate with OAuth in your browser when prompted.
    </Step>
  </Steps>
</Accordion>

## Available Tools

Tools are divided into two groups: event tools for querying identification data, and management tools for administering your Fingerprint workspace.

* **Event tools** let you retrieve and search identification events, including Smart Signal data like bot detection, VPN, proxy, incognito mode, and more.
* **Management tools** let you create, update, and delete workspace environments and API keys.

For a full list of tools, see the tool reference in the [GitHub repository](https://github.com/fingerprintjs/fingerprint-mcp-server).

## Example Queries and Prompts

Once connected, you can ask your AI assistant questions in plain language. Some examples:

* Fetch the last 50 events for visitor ID `Abck1234CUFmcnjLwIs4A9` and summarize their activity.
* Find all events linked to order ID `3936532456` and tell me if anything looks suspicious.
* Show me recent events where a bot was detected, filtered to the last 6 hours.
* List all environments in my workspace and create a new one called "staging".

The server also includes an `onboarding` prompt, a guided walkthrough for integrating Fingerprint into a new project that covers JavaScript agent installation and verification steps. Trigger it by asking your AI assistant to walk you through Fingerprint setup.

## Security Considerations

### **Prompt injection**

Fields like `linkedId` and `tags` are customer-controlled values attached to identification events. If a malicious actor controls what gets stored in these fields, they could attempt to embed instructions that manipulate your AI assistant. Most AI clients show you each tool call before it executes, so keep manual approval enabled and review them before confirming.

### **Sensitive operations**

Management tools can create, edit, and delete API keys and environments. Avoid connecting the server in shared or untrusted AI environments. Before approving any destructive changes, particularly in production, take time to carefully review what the agent is proposing.

## Troubleshooting

### Authentication failures

* Ensure you completed the OAuth flow and selected the correct Fingerprint workspace.
* Try disconnecting and reconnecting the MCP server in your client settings.
* If workspace authorization fails, your account may have reached the maximum number of allowed API keys (typically 5). Remove an unused key from the [Fingerprint Dashboard](https://dashboard.fingerprint.com/api-keys) and try again.

### Tools not appearing

* Restart your MCP client after adding the server configuration.
* In Claude, start a new conversation. Claude caches the tool list for the lifetime of a conversation, so a conversation started before a tool was added will not show that tool. Disconnecting and reconnecting the connector does not refresh a conversation that is already open.
* If you added Fingerprint as a custom connector and no tools appear at all, check the connector name. Names containing dots, apostrophes, or accented characters can prevent Claude from finding the server's tools. Rename it to `Fingerprint`, or connect from the connectors directory instead.

### Rate limit errors

* Reduce the number of concurrent or rapid sequential tool calls.
* Use specific filters (`visitor_id`, `linked_id`, time ranges) to reduce the number of API requests needed to answer a question.


# Request filtering for mobile apps
Source: https://docs.fingerprint.com/docs/mobile-app-filtering



To prevent malicious actors from misusing your public API key, you can [filter out unwanted identification requests](/docs/request-filtering). These requests are not billed and will receive an error instead of the identification result.

This page covers filtering requests made from mobile apps. You can filter requests by mobile app **package name** (Android) or **bundle ID** (iOS). To block requests from web browsers, see [Request filtering for websites](/docs/request-filtering-for-websites).

<Note>
  **Availability**

  Filtering requests from mobile app requires [Android SDK v2.4.0+](https://github.com/fingerprintjs/fingerprintjs-pro-android/releases/tag/v2.4.0) and [iOS SDK v2.4.0+](https://github.com/fingerprintjs/fingerprintjs-pro-ios/releases/tag/2.4.0)
</Note>

## Configuration

You can create mobile request filtering rules from the Fingerprint dashboard by specifying the *package names* (Android) or *bundle IDs* (iOS) of the blocked or allowed applications.

1. Navigate to the  **Dashboard** > **[Security](https://dashboard.fingerprint.com/traffic-rules)** > **Mobile Apps**.
2. Click **Configure**.
3. Choose the **Default behavior**:
   1. `Allow all except the ones listed below`: Fingerprint will **block the specified apps** from making identification requests. Requests from all other apps will be allowed.
   2. `Forbid all except the ones listed below`: Fingerprint will **allow only the specified apps** to make identification requests. Requests from all other apps will be blocked.
4. Fill in the **Exceptions** with the package names (Android) or bundle IDs (iOS) of the mobile app you want to allow or block. Wild cards are accepted.
5. Click **Save**.

<img alt="" />

<img alt="" />

## Error handling

Filtered-out requests are not billed and will receive a `PackageNotAuthorized`error instead of the identification result.

For more information on handling errors, see [Handling errors in Android SDK](/docs/android-sdk#handling-errors) and [Handling errors in the iOS SDK](/docs/ios-sdk#handling-errors).


# Understanding privacy manifest files
Source: https://docs.fingerprint.com/docs/mobile-devices-understanding-privacy-manifest-files



In [WWDC 2023](https://developer.apple.com/videos/play/wwdc2023/10060/), Apple announced that starting [Spring 2024](https://developer.apple.com/news/?id=3d8a9yyh), it will require its developers to declare the reasons for using certain APIs (aka Required Reason APIs) that could be misused to collect data about users' devices within privacy manifest files.

[Privacy manifest files](https://developer.apple.com/documentation/bundleresources/privacy-manifest-files) allow developers to describe their privacy practices:

* [Data](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests) that their app or SDK collects and its purpose.
* [Required Reason APIs](https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api) that their app or SDK uses and the reason for using them.

<Check>
  Important note: the [privacy manifest
  file](/docs/mobile-devices-understanding-privacy-manifest-files#privacy-manifest-file-for-fingerprint-identification-sdk)
  and the [privacy nutrition
  labels](/docs/mobile-devices-understanding-privacy-manifest-files#app-store-nutrition-labels-guidance-for-your-app)
  are two separate things - the privacy manifest is a 'plist' file bundled with the app/SDK, while
  the Nutrition Labels are what developers fill out in App Store Connect before submission. The
  privacy manifest report generated by Xcode can help populate the labels more accurately, but
  developers still need to manually apply the correct labels in the submission interface.
</Check>

In this article, we will walk you through the privacy manifest file for Fingerprint [iOS SDK](/docs/ios) and share guidance on App Store Nutrition Labels to help you complete them in App Store Connect before submission.

## Privacy Manifest File for Fingerprint Identification SDK

Starting with v2.3.2, the Fingerprint Identification SDK for iOS includes a privacy manifest file. Apple requires that every privacy manifest file contains the following keys.

### NSPrivacyTracking

Fingerprint Identification SDK does not use the collected data for tracking, and hence, the NSPrivacyTracking key is set to `false`.

```xml XML wrap theme={"theme":"github-dark-dimmed"}
{/*  Privacy manifest file for Fingerprint Identification SDK for iOS  */}
<key>NSPrivacyTracking</key>
<false/>
```

### NSPrivacyTrackingDomains

Fingerprint Identification SDK for iOS does not connect with any Internet domains that engage in tracking users. The NSPrivacyTrackingDomains key is set to an empty array of domains.

```xml XML wrap theme={"theme":"github-dark-dimmed"}
{/*  Privacy manifest file for Fingerprint Identification SDK for iOS  */}
<key>NSPrivacyTrackingDomains</key>
<array/>
```

### NSPrivacyCollectedDataTypes

Apple has identified [a list of data types](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests#4250555) that, when collected, may help to identify/track the device. These are the data types our iOS SDK collects from the device:

* `NSPrivacyCollectedDataTypeDeviceID` - device ID; such as the device’s advertising identifier, or other device-level ID.
* `NSPrivacyCollectedDataTypePreciseLocation` - precise location; information that describes the location of a user or device with the same or greater resolution as a latitude and longitude with three or more decimal places (started collecting since [iOS SDK 2.10.0](/docs/changelog-ios-sdk#v2-10-0)).
* `NSPrivacyCollectedDataTypeCoarseLocation` - coarse location; information that describes the location of a user or device with lower resolution than a latitude and longitude with three or more decimal places, such as Approximate Location Services (started collecting since [iOS SDK v2.10.0](/docs/changelog-ios-sdk#v2-10-0)).

Apple also requires [describing data use](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests#4250556) in privacy manifests as part of this dictionary item. This data is represented in the `NSPrivacyCollectedDataTypes` key in our privacy manifest file:

```xml XML wrap theme={"theme":"github-dark-dimmed"}
{/*  Privacy manifest file for Fingerprint Identification SDK for iOS  */}
<key>NSPrivacyCollectedDataTypes</key>
<array>
  <dict>
    {/*  The value provided by Apple for 'Device ID' data type  */}
    <key>NSPrivacyCollectedDataType</key>
    <string>NSPrivacyCollectedDataTypeDeviceID</string>

    {/*  Fingerprint Identification SDK does not link the 'Device ID' with user's identity  */}
    <key>NSPrivacyCollectedDataTypeLinked</key>
    <false/>

    {/*  Fingerprint Identification SDK does not use 'Device ID' for tracking  */}
    <key>NSPrivacyCollectedDataTypeTracking</key>
    <false/>

    {/*  Fingerprint Identification SDK uses 'Device ID' for App Functionality
         (prevent fraud and implement security measures)  */}
    <key>NSPrivacyCollectedDataTypePurposes</key>
    <array>
      <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
    </array>

  <dict>
    {/*  The value provided by Apple for 'Precise Location' data type  */}
    <key>NSPrivacyCollectedDataType</key>
    <string>NSPrivacyCollectedDataTypePreciseLocation</string>

    {/*  Fingerprint Identification SDK does not link the 'Precise Location' with user's identity  */}
    <key>NSPrivacyCollectedDataTypeLinked</key>
    <false/>

    {/*  Fingerprint Identification SDK does not use 'Precise Location' for tracking  */}
    <key>NSPrivacyCollectedDataTypeTracking</key>
    <false/>

    {/*  Fingerprint Identification SDK uses 'Precise Location' for App Functionality
         (prevent fraud and implement security measures)  */}
    <key>NSPrivacyCollectedDataTypePurposes</key>
    <array>
      <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
    </array>
  </dict>

  <dict>
    {/*  The value provided by Apple for 'Coarse Location' data type  */}
    <key>NSPrivacyCollectedDataType</key>
    <string>NSPrivacyCollectedDataTypeCoarseLocation</string>

    {/*  Fingerprint Identification SDK does not link the 'Coarse Location' with user's identity  */}
    <key>NSPrivacyCollectedDataTypeLinked</key>
    <false/>

    {/*  Fingerprint Identification SDK does not use 'Coarse Location' for tracking  */}
    <key>NSPrivacyCollectedDataTypeTracking</key>
    <false/>

    {/*  Fingerprint Identification SDK uses 'Coarse Location' for App Functionality
         (prevent fraud and implement security measures)  */}
    <key>NSPrivacyCollectedDataTypePurposes</key>
    <array>
      <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
    </array>
  </dict>
</array>

```

### NSPrivacyAccessedAPITypes

Fingerprint Identification SDK for iOS uses the following Required Reason APIs which have to be included in the privacy manifest file:

1. [File timestamp APIs](https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api#4278394)
2. [System boot time APIs](https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api#4278394)

```xml XML wrap theme={"theme":"github-dark-dimmed"}
{/*  Privacy manifest file for Fingerprint Identification SDK for iOS  */}
<key>NSPrivacyAccessedAPITypes</key>
<array>
  <dict>
    {/*  The value provided by Apple for 'System boot time APIs'  */}
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategorySystemBootTime</string>

    {/*  Fingerprint Identification SDK uses 'System boot time APIs' to measure the amount of
          time that has elapsed between events that occurred within the SDK  */}
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
      <string>35F9.1</string>
    </array>
  </dict>
  <dict>
    {/*  The value provided by Apple for 'File timestamp APIs'  */}
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>

    {/*  Fingerprint Identification SDK uses 'File timestamp APIs' to manage persistent cache
         data  */}
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
      <string>C617.1</string>
    </array>
  </dict>
</array>
```

## Privacy Manifest File for your App

Below, you will find answers to some of the most frequently asked questions with respect to creating privacy manifest files for your iOS apps:

**My app uses Fingerprint Identification SDK, but the app itself does not collect any** [**sensitive data**](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests#4250555)**. It also does not use any of the Required Reason APIs. Should I still provide a privacy manifest file for my app?**

* No. According to [Apple documentation](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests), your app’s privacy manifest file doesn’t need to cover data collected by third-party SDKs that your app links to.

**My app uses Fingerprint Identification SDK. The app also collects the same data as the SDK for the same purpose specified in the SDK's privacy manifest file. Should I still provide a privacy manifest file for my app?**

* Yes. Apple will aggregate the privacy manifest files provided for your app and all the third-party SDKs your app links to. See [Create your app's privacy report](https://developer.apple.com/documentation/bundleresources/describing-data-use-in-privacy-manifests#4239187) for more information.

**My app uses Fingerprint Identification SDK. What kind of assistance can Fingerprint provide towards submitting my app for review?**

* This page is a good starting point for creating the privacy manifest file for your app. For a complete privacy manifest example, you can also refer to the [privacy manifest file of our demo app](https://github.com/fingerprintjs/fingerprint-device-intelligence-ios-demo/blob/main/FingerprintDemo/PrivacyInfo.xcprivacy).
* We can review the privacy manifest file for your app to ensure that the use of Fingerprint Identification SDK is represented correctly.
* During the app submission process, we will help you answer any questions Apple raises about the data collected/processed by Fingerprint Identification SDK.

## App Store Nutrition Labels Guidance for Your App

If your app includes Fingerprint iOS SDK, then you can use the following as a reference to fill out the Nutrition Labels in App Store Connect:

### Data Collection and Security

| Question                                                       | Answer |
| -------------------------------------------------------------- | ------ |
| Does your app collect or share any of the required data types? | Yes    |
| Is all collected data encrypted in transit?                    | Yes    |

### Data types

| Apple Data Category | Fingerprint iOS SDK Relevance                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Device ID           | Yes - the SDK collects device-level identifiers                                                                          |
| Precise Location    | Yes - collected since [iOS SDK v2.10.0+](/docs/changelog-ios-sdk#september-2025) (requires user consent for permissions) |
| Coarse Location     | Yes - collected since [iOS SDK v2.10.0+](/docs/changelog-ios-sdk#september-2025) (requires user consent for permissions) |
| Performance Data    | Yes - collected since [iOS SDK v2.15.0+](/docs/changelog-ios-sdk#march-2026)                                             |

### Data Usage and Handling

| Question                       | Device ID                                      | Precise Location                               | Coarse Location                                |
| ------------------------------ | ---------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
| Collected, shared, or both?    | Collected                                      | Collected                                      | Collected                                      |
| Linked to the user's identity? | No                                             | No                                             | No                                             |
| Used for tracking?             | No                                             | No                                             | No                                             |
| Primary purpose?               | App Functionality (Fraud Prevention, Security) | App Functionality (Fraud Prevention, Security) | App Functionality (Fraud Prevention, Security) |

Note: Apple clarifies that even if data is collected solely for your app functionality, it still must be declared - the purpose just needs to be accurately indicated as "App Functionality" rather than advertising or analytics, see for reference [App privacy details on the App Store](https://developer.apple.com/app-store/app-privacy-details/).

### What's Different from the Privacy Manifest

|                       | Privacy Manifest                                                 | App Privacy Nutrition Labels      |
| --------------------- | ---------------------------------------------------------------- | --------------------------------- |
| **Where?**            | Bundled inside the SDK/app binary                                | Filled out in App Store Connect   |
| **Who fills it out?** | SDK vendor (Fingerprint provides it in starting iOS SDK v2.3.2+) | App developer (you)               |
| **When required?**    | At build/distribution time                                       | At app submission time            |
| **Covers SDK data?**  | Yes, automatically aggregated by Xcode                           | Yes, but must be manually applied |

Below, you will find answers to some of the most frequently asked questions with respect to filling out Nutrition Labels for your iOS apps:

**Do I need to declare Fingerprint's data in my app's Privacy Nutrition Label even if the SDK has its own privacy manifest?**

* Yes. While the Fingerprint SDK's privacy manifest will be combined with your app's manifest by Xcode into a single report, you are still responsible for applying the correct Nutrition Labels in App Store Connect. The manifest report helps you fill this out accurately, but it does not automatically populate the labels.

**Is using Fingerprint considered 'tracking' under Apple's definition?**

* No. Apple's guidelines specify that sharing data with a data broker that uses it solely for fraud detection or prevention or security purposes is not considered tracking. Since Fingerprint is used for fraud prevention and security, neither [NSPrivacyTracking](https://developer.apple.com/documentation/bundleresources/app-privacy-configuration/nsprivacytracking) nor the App Tracking Transparency (ATT) prompt are required.

**Who is responsible for keeping the labels accurate?**

* Developers are responsible for all code included in their apps, including third-party SDKs. If you are unsure about the data collection practices of the Fingerprint SDK, this page and Fingerprint's support team are the right resources.


# Fingerprint for mobile devices
Source: https://docs.fingerprint.com/docs/mobile-identification



Fingerprint's device intelligence platform can accurately identify every mobile device that interacts with your app. It can also provide actionable [Smart Signals](/docs/smart-signals-reference#smart-signals-for-mobile-devices) that will help you identify risky mobile transactions before they happen.

You can integrate Fingerprint's device intelligence platform with your mobile app by using any of the following SDKs:

* [Android SDK](/docs/android-sdk)
* [iOS SDK](/docs/ios-sdk)
* [Flutter SDK](/docs/flutter)
* [React Native SDK](/docs/fingerprintjs-pro-react-native)

This page provides an overview of the platform for mobile devices and compares it with that for browsers, where applicable.

### Identification

* For websites, the visitor ID provided by the JavaScript agent identifies the **browser** interacting with your website. Every browser (e.g. Safari, Chrome, Firefox, etc) on the device gets a unique visitor ID even if they are on the same device.
* For mobile apps, the visitor ID provided by mobile SDKs identifies the **mobile device** interacting with your mobile app.

The visitor ID that the mobile SDKs generate for a mobile app is different from that generated by the Javascript agent for a browser on the same device.

Learn more about how Fingerprint identifies mobile devices:

* For Android devices, see [Android:Device Identifier](/docs/native-android-integration#device-identifier)
* iOS devices, see [iOS:Device Identifier](/docs/ios#device-identifier)

### Identification accuracy

In general, for mobile devices, the identification accuracy is **higher than for browsers**. This is because the native mobile SDKs can access several operating system properties that remain stable over a long time. These properties are typically not available to a Javascript agent operating from within a browser.

<Note>
  Unlike the [JavaScript agent for browsers](https://docs.fingerprint.com/docs/identify-visitors#caching-the-visitor-id), the mobile SDKs do not cache identification responses on the device.

  This is intentional. Many of the mobile Smart Signals used in fraud prevention (for example, MITM detection or active call detection) are only meaningful if they reflect the device's current state at the time of the request. Caching a response on the SDK side would mean an app could act on a signal that no longer reflects that state, which reduces its value for time-sensitive risk decisions.

  If your mobile app needs to reduce the number of identification calls it makes, we recommend implementing caching at the application layer, where you control the cache duration and can decide which signals are safe to reuse for your specific use case and for how long. A common pattern is to cache the visitor ID for the duration of a user session and request a fresh identification on new sessions or before high-risk actions (e.g. login, checkout, payment).
</Note>

### Smart Signals for mobile devices

Smart Signals are actionable device intelligence signals that help you to make informed decisions about the device and thus prevent fraud. For a quick overview of the different Smart Signals available for each platform, see

* [Android Smart Signals](/docs/native-android-integration#android-smart-signals)
* [iOS Smart Signals](/docs/ios#ios-smart-signals)
* [Smart Signals common for browsers and mobile devices](/docs/smart-signals-reference#smart-signals-common-for-browsers-and-mobile-devices)

See [Smart Signals setup and usage](/docs/smart-signals-introduction#setup-and-usage) for information on how to receive these Smart Signals.

### Evading ad blockers

If your users' mobile devices have ad-blocking mobile apps, they can block requests that your app makes to the Fingerprint domains. You can evade these ad-blocking mobile apps by proxying requests through your own domain. See [Evading ad blockers with proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers) for more information.

### Privacy and data safety

When you publish your app to the App Store or Google Play, you must disclose information about the data collected and its usage. This requirement applies to your app as well as to the third-party SDKs the app uses.

For iOS apps, Apple requires you to provide a privacy manifest file to declare the data that your app/SDK collects and the reasons for collecting the same. To learn more, see [Privacy Manifest File Requirements for App Store](/docs/ios#privacy-manifest-file-requirements-for-app-store).

For Android apps, Google requires that the app's privacy and security practices be made available to all its users. To learn more, see [Data Safety Requirements for Google Play](/docs/native-android-integration#data-safety-requirements-for-google-play).

## Additional resources

* Want to see the iOS SDK in a demo app? Download the iOS Demo app from the [App Store](https://apps.apple.com/us/app/fingerprint-pro/id1644105278).
* Want to see the Android SDK in a demo app? Download the Android Demo app from [Google Play](https://play.google.com/store/apps/details?id=com.fingerprintjs.android.fpjs_pro_demo).


# Overview
Source: https://docs.fingerprint.com/docs/mobile-sdks



In this section, you will find Getting Started Guides for integrating a Fingerprint  SDK with your

* [Android apps](/docs/android-sdk)
* [iOS apps](/docs/ios-sdk)
* [React Native apps](/docs/fingerprintjs-pro-react-native)
* [Flutter apps](/docs/flutter)


# Overview
Source: https://docs.fingerprint.com/docs/native-android-integration

Fingerprint's device intelligence platform for Android devices.

Fingerprint's device intelligence platform is also available for Android devices. Our device intelligence platform for Android helps you to accurately identify the devices that interact with your mobile app and provides high-quality Smart Signals that will help you identify risky transactions before they happen.

To make integrations with mobile apps easier, we offer SDKs for apps built natively using Android as well as for apps built using multi-platform frameworks (e.g. React Native).

A Fingerprint account is required to be able to use the Fingerprint Identification SDK in your mobile apps. If you do not have an account yet, please [sign up](https://dashboard.fingerprintjs.com/signup) for one.

<Check>
  **Download our** [**demo
  app**](https://play.google.com/store/apps/details?id=com.fingerprintjs.android.fpjs_pro_demo) from
  Google Play to see Fingerprint in action!
</Check>

## Device Identifier

When the Fingerprint Identification SDK is integrated into your mobile app, it will collect several attributes from the device. With the help of these attributes and additional algorithms, Fingerprint is able to provide a unique device identifier (i.e. `visitorId`) for every device on which your app is installed.

<Info>
  **Did you know?**

  The device identifier generated by the Android SDK (embedded within your mobile app) will be different from the visitor ID generated by the Javascript agent (embedded within your website).
</Info>

When compared with browsers, the identification accuracy is better for mobile devices because we identify mobile devices using signals that have higher longevity than those used for identifying browsers. But there are scenarios where a `visitorId` does not persist.

For your reference, we have listed various scenarios where a `visitorId` will remain the same before and after and where a new `visitorId` will be created.

| Scenario                                                                                                                                                  | Will I receive the same `visitorId` before and after?                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The app or device is restarted                                                                                                                            | **Yes.** You will receive the same `visitorId` even after the app or device is restarted.                                                                |
| The app data/cache is cleared                                                                                                                             | **Yes.** You will receive the same `visitorId` even after the app's data/cache is cleared.                                                               |
| The app is uninstalled and re-installed again                                                                                                             | **Yes.** You will receive the same `visitorId` even after the app is removed and installed again.                                                        |
| The device is factory reset                                                                                                                               | **Yes, in most of the devices.** After a factory reset, except for a few Android models, the `visitorId` remains the same.                               |
| The app is installed on [one or more profiles](https://source.android.com/docs/devices/admin/multi-user), that belong to a single user on the same device | **Yes.** You will receive the same `visitorId` even when the app is installed on multiple user profiles that belong to a single user on the same device. |
| The app is installed for [one or more user accounts, all belonging to the same device](https://source.android.com/docs/devices/admin/multi-user)          | **Yes.** You will receive the same `visitorId` even when the app is installed on multiple user accounts that belong to the same device.                  |
| The app is cloned to a different app                                                                                                                      | **Yes**. The `visitorId` does not change even when the app is cloned numerous times or when the cloned app is installed on a different profile.          |

## Android Smart Signals

Smart Signals are actionable device intelligence signals that help you to make informed decisions about the device and thus prevent fraud. These signals could be used as input to your machine learning models behind your fraud detection or risk mitigation engines. For example, when you know that a request is originating from a *rooted* device or from a recently *factory reset* device, you will be able to take additional precautionary security steps (e.g. multi-factor authentication).

For Android, the following Smart Signals are available:

* [Android Emulator Detection](/docs/smart-signals-reference#android-emulator-detection)
* [Cloned App Detection](/docs/smart-signals-reference#cloned-app-detection)
* [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection)
* [Frida Detection](/docs/smart-signals-reference#frida-detection)
* [Geolocation Spoofing Detection](/docs/smart-signals-reference#geolocation-spoofing-detection)
* [IP Geolocation Detection](/docs/smart-signals-reference#ip-geolocation)
* [IP Blocklist Detection](/docs/smart-signals-reference#ip-blocklist-matching)
* [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection)
* [Rooted Device Detection](/docs/smart-signals-reference#rooted-device-detection)
* [Tampered Request Detection](/docs/smart-signals-reference#tampered-request-detection-for-mobile-apps)
* [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices)
* [Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection-for-mobile-devices)
* [Smart Signals common for browsers and mobile devices](/docs/smart-signals-reference#smart-signals-common-for-browsers-and-mobile-devices)

These Smart Signals are available as part of our [Pro Plus and Enterprise plans](https://fingerprint.com/pricing/). If you are interested in one or more of these signals, then please [contact our support team](https://fingerprint.com/support/) to enable them for you. Signing up for an Enterprise plan does not automatically enable these signals.

## Fingerprint Identification SDK for Android

<Info>
  ### Current Version: 2.17.1

  For release notes and older versions, visit our [Changelog for Android SDK](https://docs.fingerprint.com/docs/changelog-android-sdk) page.
</Info>

### Supported Versions

The minimum version that the Fingerprint Identification SDK for Android supports is [Marshmallow](https://developer.android.com/about/versions/marshmallow), [API Level 23](https://developer.android.com/tools/releases/platforms#6.0) starting [Android SDK 2.11.0+](/docs/changelog-android-sdk#v2-11-0). Per Google, this will allow your app to be compatible with a wide variety of active Android devices.

<img alt="" />

### Required Permissions

Fingerprint Identification SDK for Android requires the following **normal** permissions, without which the SDK cannot function properly. These permissions are required to identify the device and provide additional intelligence.

* [`android.permission.INTERNET`](https://developer.android.com/reference/android/Manifest.permission#INTERNET)
* `com.google.android.providers.gsf.permission.READ_GSERVICES`

Unlike the runtime permissions (*aka* dangerous permissions), these permissions do not require consent from the user. See [Permissions on Android](https://developer.android.com/guide/topics/permissions/overview) to learn more about the different types of permissions.

### Getting Started Guides

Our Getting Started guides are aimed at helping you to easily integrate our SDK with your apps.

* For native Android apps, see [Mobile SDKs > Android](/docs/android-sdk) and our [Android quickstart](/docs/android-quickstart).
* For apps built using Flutter, see our [Flutter SDK on GitHub](https://github.com/fingerprintjs/fingerprintjs-pro-flutter) and our [Flutter quickstart](/docs/flutter-quickstart).
* For apps built using React Native, see our [React Native SDK on GitHub](https://github.com/fingerprintjs/react) and our [React Native quickstart](/docs/react-native-quickstart).

## Data Safety Requirements for Google Play

For every app that is uploaded to the Google Play Store, Google requires that the app's privacy and security practices are made available to all its users. For this reason, when an app (or a new version) is uploaded to the Play Store, Google requires app developers to fill out a data safety form. See [Provide information for Google Play's Data safety section](https://support.google.com/googleplay/android-developer/answer/10787469?hl=en) for more information.

If your app includes our Android SDK, then you can use the following as a reference to fill out the data safety questionnaire:

### Section: Data collection and security

1. *Does your app collect or share any of the required user data types?* **Yes**
2. *Is all of the user data collected by your app encrypted in transit?* **Yes**

### Section: Data types

1. *Select all of the user data types collected or shared by your app*
   1. **App info and performance -> Diagnostics**
   2. **Device or other IDs.**
   3. **Location -> Precise and Approximate Location** (collected since [Android SDK v2.10.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#september-2025); requires user consent for permissions)

### Section: Data usage and handling

| Question                                                                          | App info and performance > Diagnostics                                  | Device or other IDs                                                     | Precise and Approximate Location                              |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
| *Is this data collected, shared, or both?*                                        | Collected                                                               | Collected                                                               | Collected                                                     |
| *Is this data processed ephemerally?*                                             | No, this collected data is not processed ephemerally                    | No, this collected data is not processed ephemerally                    | No, this collected data is not processed ephemerally          |
| *Is this data required for your app, or can users choose whether it's collected?* | Data collection is required (users can't turn off this data collection) | Data collection is required (users can't turn off this data collection) | Location data collection is optional (your app controls this) |
| *Why is this user data collected?*                                                | Analytics                                                               | Fraud Prevention, Security, and Compliance                              | Fraud Prevention, Security, and Compliance                    |

Note: The Data sharing section in the [Google Play Data Safety](https://support.google.com/googleplay/android-developer/answer/10787469#zippy=%2Cdata-sharing) form can be left empty. Per Google's policy, data transferred to a service provider that processes it on the developer's behalf - in compliance with the developer's instructions, contractual terms, and privacy policies - does not need to be declared as "shared." As Fingerprint acts as a data processor under GDPR (and a service provider under Google's definition), data sent to Fingerprint does not constitute "data sharing" for the purposes of this form.

### Google Play Compatibility Notes

The Fingerprint Android SDK may not be compatible with **[Google Play's Automatic Integrity Protection](https://developer.android.com/google/play/integrity/overview)**. If your app uses Google Play's integrity protection, we recommend reviewing compatibility before enabling this feature. If both are enabled, this may result in false positives or unexpected app behavior.

## FingerprintJS-Android: Open-source identification for Android

We also provide a lightweight, open-source library called [fingerprintjs-android](https://github.com/fingerprintjs/fingerprintjs-android) which is available to use for free by everyone. Our commercial SDK, Fingerprint Identification for Android, is based on our well-maintained, free, open-source library.

Compared to the open-source library, our commercial SDK collects many more attributes from the device. It also uses advanced fingerprinting and matching algorithms to create a unique device identifier.

For your better understanding, here is a complete set of differences between our open-source library (`fingerprintjs-android`) and our commercial SDK (`fingerprint-android-pro`).

|                                                                              | FingerprintJS-Android(fingerprintjs-android)                                         | Fingerprint Identification for Android(fingerprint-android-pro)                             |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Core Features                                                                |                                                                                      |                                                                                             |
| **Attributes collected from the device**                                     | Basic (*e.g. Android ID, GSF ID, model*)                                             | Advanced. Lot more attributes, in addition to those collected by the open-source library.   |
| **ID Type**                                                                  | Device ID or a *fingerprint* that is a hash of the collected attributes              | A single *visitorId* that is computed using advanced fingerprinting and matching algorithms |
| **ID Origin**                                                                | Attributes are processed only within the library. External servers are not involved. | Attributes are processed on external servers                                                |
| **ID Lifetime**                                                              | Only up to a few weeks                                                               | Lasts several months and sometimes even years                                               |
| **ID Collisions**                                                            | Common                                                                               | Very rare                                                                                   |
| Support for multi-platform frameworks                                        |                                                                                      |                                                                                             |
| **Flutter**                                                                  | -                                                                                    | **✓**                                                                                       |
| **React Native**                                                             | -                                                                                    | **✓**                                                                                       |
| Advanced Features                                                            |                                                                                      |                                                                                             |
| **Server API and Webhooks**\*(Build flexible workflows)\*                    | -                                                                                    | **✓**                                                                                       |
| **Mobile Smart Signals**\*(VPN Detection, Factory Reset, App Cloners, etc)\* | -                                                                                    | **✓**                                                                                       |
| **Geolocation**\*(Based on IP address)\*                                     | -                                                                                    | **✓**                                                                                       |
| Operations                                                                   |                                                                                      |                                                                                             |
| **Data security**                                                            | Depends on your infrastructure                                                       | Encrypted at rest                                                                           |
| **Storage**                                                                  | Depends on your infrastructure                                                       | Unlimited up to 1 year                                                                      |
| **Regions**                                                                  | Depends on your infrastructure                                                       | Global, EU and Asia data centers                                                            |
| **Compliance**                                                               | Depends on your infrastructure                                                       | Compliant\*\*\* with GDPR, US Privacy Laws (including CCPA), SOC 2 Type II, and ISO 27001   |
| **SLA**                                                                      | SLA is not provided                                                                  | 99.9% Uptime                                                                                |
| **Support**                                                                  | GitHub Issues/Questions. Response times varies.                                      | Dedicated support team that responds to chat, email, and calls within 1 business day        |
| How to get started?                                                          | [Get it on GitHub](https://github.com/fingerprintjs/fingerprintjs-android)           | [Sign up for a free 14-day trial](https://dashboard.fingerprintjs.com/signup/)              |

\*\*In comparison to fingerprints, VisitorIDs are more accurate and stable identifiers because they are deduplicated, are processed further on the server, and utilize fuzzy matching. On the other hand, fingerprint hashes become unstable across time intervals greater than 2 weeks because they rely on an exact match of all browser attributes.

\*\*\*The company, Fingerprint, in its role as data processor is compliant with GDPR, US Privacy Laws (including CCPA) and SOC 2 Type II. It is also ISO 27001 certified. As a data controller, it is still your responsibility to be compliant with GDPR and US Privacy Laws (including CCPA) and use the identification result for legitimate purposes.

***

[Understanding privacy manifest files](/docs/mobile-devices-understanding-privacy-manifest-files)


# Network request filtering
Source: https://docs.fingerprint.com/docs/network-request-filtering

Filter unwanted traffic based on a list of source IP addresses

Some unwanted traffic can be identified based on a set of IP addresses. Typical examples can be short-lived bot attacks or exclusion of testing requests.

## Configuration

To filter requests by an **IP address** (or **IP address ranges**):

1. Navigate to the **[Security](https://dashboard.fingerprint.com/traffic-rules)** > **Network** tab.

<img alt="" />

2. Under **No IP address rules**, click **Configure**.
3. To create an IP *Blocklist*, set **Default behavior** to  `Allow all besides the IP addresses listed below`. Then fill in the **Exceptions** field with your list of blocked IP addresses.

<img alt="" />

4. Click **Save**.

## IP address format

The configuration accepts both single IP addresses in the form of `192.168.1.1/32` and IP address ranges defined by their [CIDR representation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation) (e.g. `192.168.1.1/16`).


# Privacy policy
Source: https://docs.fingerprint.com/docs/privacy-policy

Effective date: November 1, 2026. | [Archived Versions](/docs/legal-archive)

## 1. Introduction

FingerprintJS Inc. (“Fingerprint”, “us”, “we”, or “our”) operates [https://fingerprintjs.com](https://fingerprintjs.com/) and API services available at [https://fpjs.io](https://fpjs.io/) (including subdomains) (hereinafter referred to as “**Service**”).

Our Privacy Policy governs your visit to [https://fingerprintjs.com](https://fingerprintjs.com/) or usage of our API services, available at [https://fpjs.io](https://fpjs.io/) (including subdomains), and explains how we collect, safeguard and disclose information that results from your use of our Service.

Where we refer to “**Personal Information**” in this Privacy Policy, this means personal data or personally identifiable information that can be used to contact or identify you.

Data protection laws sometimes differentiate between “controllers” and “processors” of Personal Information. A “controller” determines the purposes and means (the why and how) of processing Personal Information. A “processor” processes Personal Information on behalf of a controller subject to the controller’s instructions. We provide our Service to business customers that operate sites or services you may visit. Where we process Personal Information of our business customers’ end users during the provision of our Service, we generally act as a processor and our business customer (i.e. the site or service operator) acts as a controller.

If you are accessing our Service from the European Economic Area, Switzerland or the United Kingdom, please refer to the additional disclosures in Annex 1.

We use your Personal Information to provide and improve Service. Unless otherwise defined in this Privacy Policy, the terms used in this Privacy Policy have the same meanings as in our Terms and Conditions.

Our Terms and Conditions (“**Terms**”), [https://docs.fingerprint.com/docs/terms-of-service](https://docs.fingerprint.com/docs/terms-of-service), govern all use of our Service and together with the Privacy Policy constitutes your agreement with us (“**agreement**”).

## 2. Definitions

**SERVICE** means the [https://fingerprintjs.com](https://fingerprintjs.com/) website or [https://fpjs.io](https://fpjs.io/) (including subdomains) services operated by FingerprintJS Inc.

**USAGE DATA** is data collected automatically either generated by the use of Service or from Service infrastructure itself (for example, the duration of a page visit).

**COOKIES** are small files stored on your device (computer or mobile device).

**THE USER** is the individual using our Service (i.e. our customers or those acting on behalf of our customers).

**THE CUSTOMER END USER** is the end user of our customers.

## 3. Information Collection and Use

We collect several different types of information for various purposes to provide and improve our Service to you.

## 4. Types of Data Collected

### Personal Information

While using our Service, we may ask you to provide us with Personal Information . Personal Information may include, but is not limited to:

(a) Users’ name, address, phone number, email address and password

(b) Users’ payment and transaction related information where personal payment information is provided (see section titled “Payments” below)

(c) Tracking Cookies Data and Usage Data (including IP address)

We may use your Personal Information to contact you with newsletters, marketing or promotional materials and other information that may be of interest to you. You may opt out of receiving any, or all, of these communications from us by following the unsubscribe link.

### Usage Data

We may also collect information that your browser sends whenever you visit our Service or when you access Service by or through a mobile device (“**Usage Data**”).

This Usage Data may include information such as your computer's Internet Protocol address (e.g. IP address), browser type, browser version, the pages of our Service that you visit, the time and date of your visit, the time spent on those pages, unique device identifiers and other diagnostic data.

When you access Service with a mobile device, this Usage Data may include information such as the type of mobile device you use, your mobile device unique ID, the IP address of your mobile device, your mobile operating system, the type of mobile Internet browser you use, unique device identifiers and other diagnostic data.

### Tracking Cookies Data

We use cookies and similar tracking technologies to track the activity on our Service and we hold certain information.

Cookies are files with a small amount of data which may include an anonymous unique identifier. Cookies are sent to your browser from a website and stored on your device. Other tracking technologies are also used such as beacons, tags and scripts to collect and track information and to improve and analyze our Service.

Examples of Cookies we use:

**(a) Session Cookies:** We use Session Cookies to operate our Service.

**(b) Preference Cookies:** We use Preference Cookies to remember your preferences and various settings.

**(c) Security Cookies:** We use Security Cookies for security purposes.

If you would prefer not to accept cookies, most browsers will allow you to (i) change your browser settings to notify you when you receive a cookie, which lets you choose whether or not to accept it; (ii) disable existing cookies; or (iii) set your browser to automatically reject cookies. Please note that not accepting cookies may negatively impact your experience using the Service, as some features and services on our Service may not work properly. Depending on your operating system, you may not be able to delete or block all cookies and you may not be able to block non-cookie technologies and these browser settings that block cookies may have no effect on such techniques. You may also set your e-mail options to prevent the automatic downloading of images that may contain technologies that would allow us to know whether you have accessed our e-mail and performed certain functions with it.

<u>Do Not Track Signals</u>. Although we do our best to honor the privacy preferences of our users, we are unable to respond to Do Not Track signals set by your browser at this time.

We may use third-party Service Providers to monitor and analyze the use of our Service.

<u>Google Analytics</u>. Google Analytics is a web analytics service offered by Google that tracks and reports website traffic. Google uses the data collected to track and monitor the use of our Service. This data is shared with other Google services. Google may use the collected data to contextualize and personalize the ads of its own advertising network.

For more information on the privacy practices of Google, please visit the Google Privacy Terms web page: [https://policies.google.com/privacy?hl=en](https://policies.google.com/privacy?hl=en)

We also encourage you to review the Google's policy for safeguarding your data: [https://support.google.com/analytics/answer/6004245](https://support.google.com/analytics/answer/6004245).

## 5. Use of Data

FingerprintJS Inc. uses the collected data for various purposes:

(a) to provide and maintain our Service;

(b) to notify you about changes to our Service;

(c) to allow you to participate in interactive features of our Service when you choose to do so;

(d) to provide customer support;

(e) to gather analysis or valuable information so that we can improve our Service;

(f) to monitor the usage of our Service;

(g) to detect, prevent and address technical issues;

(h) to fulfill any other purpose for which you provide it;

(i) to carry out our obligations and enforce our rights arising from any contracts entered into between you and us, including for billing and collection;

(j) to provide you with notices about your account and/or subscription, including expiration and renewal notices, email-instructions, etc.;

(k) to provide you with news, special offers and general information about other goods, services and events which we offer that are similar to those that you have already purchased or enquired about unless you have opted not to receive such information;

(l) in any other way we may describe when you provide the information;

(m) for any other purpose with your consent.

## 6. Retention of Information

We will retain your Personal Information only for as long as is necessary for the purposes set out in this Privacy Policy. We will retain and use your Personal Information to the extent necessary to comply with our legal obligations (for example, if we are required to retain your data to comply with applicable laws), resolve disputes, and enforce our legal agreements and policies. Any Customer End User information that we have access to shall be retained according to our agreement with our business customer.

We will retain Usage Data for internal analysis purposes and to improve our Service. Usage Data is generally retained for a shorter period, except when this information is used to strengthen the security or to improve the functionality of our Service, or we are legally obligated to retain this information for longer time periods.

## 7. Disclosure of Information

We may disclose Personal Information that we collect, or you provide as follows:

### (a) Third-Party Vendors and Other Service Providers.

We may share your Personal Information with Service Providers who perform services on our behalf, as needed to carry out their work for us, which may include, for example, payment providers to successfully process payments. These third parties have access to your Personal Information only to perform these tasks on our behalf and are obligated not to disclose or use it for any other purpose.

### (b) Other Companies and Brands Owned Or Controlled by FingerprintJS.

We may disclose your Personal Information with other companies owned by or under common ownership as FingerprintJS, which also includes our subsidiaries (i.e., any organization we own or control) or our ultimate holding company (i.e., any organization that owns or controls us) and any subsidiaries it owns. These companies will use your personal information in the same way as we can under this Privacy Policy,

### (c) Disclosure for Law Enforcement.

Under certain circumstances, we may be required to disclose your Personal Information with third parties as required by law or subpoena or if we reasonably believe that such action is necessary to (a) comply with the law and the reasonable requests of law enforcement; (b) to enforce our Terms and Conditions or to protect the security or integrity of our Service; and/or (c) to exercise or protect the rights, property, or personal safety of FingerprintJS, our visitors, or others.

### (d) Business Transaction.

We may disclose your Personal Information with other parties in connection with a company transaction, such as a merger, sale of company assets or shares, reorganization, financing, change of control or acquisition of all or a portion of our business by another company or third party, or in the event of a bankruptcy or related or similar proceedings.

## 8. Security of Information

The security of your information is important to us but remember that no method of transmission over the Internet or method of electronic storage is 100% secure. While we strive to use commercially acceptable means to protect your Personal Information, we cannot guarantee its absolute security.

## 9. CI/CD tools

We may use third-party Service Providers to automate the development process of our Service.

### GitHub

GitHub is provided by GitHub, Inc.

GitHub is a development platform to host and review code, manage projects, and build software.

For more information on what data GitHub collects for what purpose and how the protection of the data is ensured, please visit GitHub Privacy Policy page: [https://help.github.com/en/articles/github-privacy-statement](https://help.github.com/en/articles/github-privacy-statement)

### GitLab CI/CD

GitLab CI/CD is provided by GitLab, Inc.

GitLab CI (Continuous Integration) service is a part of GitLab that build and test the software whenever developer pushes code to application.

GitLab CD (Continuous Deployment) is a software service that places the changes of every code in the production which results in every day deployment of production.

For more information on what data GitLab CI/CD collects for what purpose and how the protection of the data is ensured, please visit GitLab CI/CD Privacy Policy page: [https://about.gitlab.com/privacy/](https://about.gitlab.com/privacy/).

## 10. Payments

We may provide paid products and/or services within Service. In that case, we use third-party services for payment processing (e.g. payment processors).

We will not store or collect your payment card details. That information is provided directly to our third-party payment processors whose use of your personal information is governed by their Privacy Policy. These payment processors adhere to the standards set by PCI-DSS as managed by the PCI Security Standards Council, which is a joint effort of brands like Visa, Mastercard, American Express and Discover. PCI-DSS requirements help ensure the secure handling of payment information.

The payment processors we work with are:

Stripe:

We use Stripe for payment, analytics, and other business services. Stripe collects identifying information about the devices that connect to its services. Stripe uses this information to operate and improve the services it provides to us, including for fraud detection. You can learn more about Stripe and read its privacy policy at [https://stripe.com/privacy](https://stripe.com/privacy).

## 11. Links to Other Sites

Our Service may contain links to other sites that are not operated by us. If you click a third party link, you will be directed to that third party's site. We strongly advise you to review the Privacy Policy of every site you visit.

We have no control over and assume no responsibility for the content, privacy policies or practices of any third party sites or services.

## 12. Children's Privacy

Our Services are not intended for use by children under the age of 13 (“**Children**”).

We do not knowingly collect Personal Information from Children under 13. If you become aware that a Child has provided us with Personal Information, please contact us at the information provided below. If we become aware that have collected Personal Information from Children without parental consent, we take steps to remove that information from our servers.

## 13. Changes to This Privacy Policy

We may update our Privacy Policy from time to time. We will notify you of any changes by posting the new Privacy Policy on this page.

We will let you know via email and/or a prominent notice on our Service, prior to the change becoming effective and update “effective date” at the top of this Privacy Policy.

You are advised to review this Privacy Policy periodically for any changes. Changes to this Privacy Policy are effective when they are posted on this page.

## 14. Contact Us

If you have any questions about this Privacy Policy, please contact us:

By email: [support@fingerprint.com](mailto:support@fingerprint.com).

## Annex 1 - EEA, SWISS AND UK DISCLOSURES

This Annex 1 (the "**European Data Annex**") sets out how we collect, store, process, transfer, share and use data that identifies or is associated with you ("**personal data**") when you access our Service from the European Economic Area, Switzerland or the United Kingdom.

This European Data Annex was last updated on October 1, 2026.

### 1. Who is responsible for the use of your personal data

There are various ways in which we collect and receive personal data about you when you use the Service, and our role with respect to your personal data will vary depending on our relationship with you, how we collect this personal data and how we use it.

In certain circumstances we will act as the controller of your personal data, which means we determine and are responsible for how that personal data is used.

In other circumstances we act as a processor on behalf of another person, meaning that our use of this personal data is governed by our Terms of Service [https://docs.fingerprint.com/docs/terms-of-service](https://docs.fingerprint.com/docs/terms-of-service) and, where applicable, the data processing addendum [https://docs.fingerprint.com/docs/dpa-gdpr](https://docs.fingerprint.com/docs/dpa-gdpr) and [https://docs.fingerprint.com/docs/dpa-usspl](https://docs.fingerprint.com/docs/dpa-usspl)

The following summarizes where we believe we act as a controller and where we would consider ourselves to act as a processor:

* **When you subscribe to the Service and set up an account**, whether on your own behalf or on behalf of your employer, we will be the controller of your personal data that you provide to us, such as your name and other contact details, your payment details and transaction details (including the details of the type of service you have purchased).
* **When someone else sets up an account on the Service (the "Customer") and gives you access to the Service (and makes you an "Authorised User")**, such as your employer, we will process the personal data about you (such as your contact details) that they submit to us as a processor on their behalf.
* **When you access and use the Service**, we will be a controller in respect of any information about your usage of the Service, such as the pages you access and functionalities you use, as well as information about the type of device you use to access the Service.
* **When you submit support requests to us**, we will process any personal data contained in that support request as a processor on behalf of the relevant Customer.
* **When you submit comments and opinions to us**, and we use those comments and opinions to improve the Service or develop new products, we will be the controller of the personal data contained in those comments and opinions; and
* **With respect to Customer End User Data**, we generally act as a processor on behalf of the relevant Customer, other than in the limited circumstances set out below.

This European Data Annex applies to our use of your personal data when we act as a controller of that personal data.

### 2. Personal data we collect from you directly and how we use it

The following table sets out the categories of personal data that we collect from you directly when you subscribe to and use the Service and when you correspond with us. It also sets out the purposes for which we will process this personal data and the lawful basis we rely on to do so.

We will indicate to you where the provision of certain personal data is required in order for us to provide you certain features of the Service. If you choose not to provide such personal data, we may not be able to provide those parts of the Service to you or respond to your other requests.

| Category of personal data                                                                                                                                              | How we use it                                                                                                                                                                                                                                                  | Legal basis for the processing                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to set up and authenticate your account.                                                                                                                                                                                               | If you are the Customer, the processing is necessary for the performance of a contract with you and to take steps prior to entering into a contract with you.<br />If you subscribe to the Service on behalf of a Customer, the processing is necessary for the Customer's legitimate interests, namely setting up and administering the Customer's account.                                                               |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to deal with enquiries and complaints made by you relating to the Service.                                                                                                                                                             | The processing is necessary for our legitimate interests, namely administering the Service, and for communicating with you effectively to respond to your queries or complaints.                                                                                                                                                                                                                                           |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to communicate with you, including sending service-related communications.                                                                                                                                                             | If you are the Customer, the processing is necessary for the performance of a contract with you.<br />If you subscribe to the Service on behalf of a Customer, the processing is necessary for our legitimate interests, namely providing service related information and updates.                                                                                                                                         |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to send you unsolicited marketing communications in accordance with your preferences.                                                                                                                                                  | If you are the Customer, or sign up and create an account on behalf of the Customer, the processing is necessary for our legitimate interests, namely promoting certain features of our Service and our similar products and services to you.<br />If you have been granted access to the Service as an Authorized User, we will only use your personal data in this way to the extent you have given us consent to do so. |
| **Contact information that you provide to us when you subscribe to the Service,** such as your name and e-mail address.                                                | We use this information to identify and prevent fraud.                                                                                                                                                                                                         | The processing is necessary for our legitimate interests, namely identifying and preventing fraud.                                                                                                                                                                                                                                                                                                                         |
| **Payment and transaction information**, such as your credit or debit card and billing address.                                                                        | We use this information to process the payments you make through the Service.                                                                                                                                                                                  | If you are the Customer, the processing is necessary for the performance of a contract with you and to take steps prior to entering into a contract with you.<br />If you subscribe to the Service on behalf of a Customer, the processing is necessary for our legitimate interests, namely billing the Customer in respect of their use of the Service.                                                                  |
| **Payment and transaction information**, such as your credit or debit card and billing address.                                                                        | We use this information to determine products and services that may be of interest to you for marketing purposes                                                                                                                                               | The processing is necessary for our legitimate interests, namely to inform our marketing activities.                                                                                                                                                                                                                                                                                                                       |
| **Chat, comments and opinions.** When you contact us directly, e.g. by email or phone, we will record your comments and opinions.                                      | We use this information to address your questions, issues and concerns.                                                                                                                                                                                        | The processing is necessary for our legitimate interests, namely communicating with users and responding to queries, complaints and concerns.                                                                                                                                                                                                                                                                              |
| **Chat, comments and opinions.** When you contact us directly, e.g. by email or phone, we will record your comments and opinions.                                      | We use this information to develop new products and features available through the Service or otherwise improve the Service.                                                                                                                                   | The processing is necessary for our legitimate interests, namely developing and improving the Service.                                                                                                                                                                                                                                                                                                                     |
| **Your preferences**, such as preferences set for notifications, marketing communications, how the Service is displayed and the active functionalities on the Service. | We use this information to provide notifications, send news, alerts and marketing communications and provide the Service in accordance with your choices.                                                                                                      | The processing is necessary for our legitimate interest, namely ensuring the user receives the correct marketing and other communications, and that the Service is displayed in accordance with the user's preferences.                                                                                                                                                                                                    |
| **Your preferences**, such as preferences set for notifications, marketing communications, how the Service is displayed and the active functionalities on the Service. | We use this information to ensure that we comply with our legal obligation to send only those marketing communications to which you have consented.                                                                                                            | The processing is necessary for compliance with a legal obligation to which we are subject.                                                                                                                                                                                                                                                                                                                                |
| **All personal data set out above.**                                                                                                                                   | We may use all the personal data we collect to operate, maintain and provide to you the features and functionality of the Service, to communicate with you, to monitor and improve the Service and business, and to help us develop new products and services. | The processing is necessary for our legitimate interests, namely to administer and improve the Service.                                                                                                                                                                                                                                                                                                                    |

### 3. Personal data we collect about you automatically

#### 3.1

If you are a User, we also collect personal data about you automatically when you use the Service. The following table sets out the categories of personal data that we collect about Users in this way. It also sets out the purposes for which we will process this personal data and the lawful basis we rely on to do so.

| Category of personal data                                                                                                                                                                                                                                                                                                                                                                                                                                              | How we may use it                                                                                                                                                                                                                                                                                                                                  | Legal basis for the processing                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Approximate location information.** Other than information you choose to provide to us, we do not collect information about your precise location. Your device’s IP address may however help us determine an approximate location.                                                                                                                                                                                                                                   | Where relevant and where permitted under applicable law, we use this information to resolve issues, monitor and detect fraud or suspicious activity in relation to your or a Customer's account and to identify potential risk or unlawful behavior including fraud detection, theft prevention, emergency response purposes and legal compliance. | The processing is necessary for our legitimate interests, namely identifying and mitigating the risk of unlawful behavior to protect the Service, Fingerprint and its Customers. |
| **Approximate location information.** Other than information you choose to provide to us, we do not collect information about your precise location. Your device’s IP address may however help us determine an approximate location.                                                                                                                                                                                                                                   | We use information you provide to us about your location to inform and plan our marketing strategy.                                                                                                                                                                                                                                                | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Approximate location information.** Other than information you choose to provide to us, we do not collect information about your precise location. Your device’s IP address may however help us determine an approximate location.                                                                                                                                                                                                                                   | We use this information to tailor how the Service is displayed to you (such as the content that is provided to you through the Service and/or the language in which it is provided to you).                                                                                                                                                        | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | We use information about how you use and connect to the Service to present the Service to you on your device.                                                                                                                                                                                                                                      | The processing is necessary for our legitimate interests, namely presenting the Service to our users so they can access and use our Service.                                     |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | We use this information to tailor how the Service is displayed to you (such as the content that is provided to you through the Service and/or the language in which it is provided to you).                                                                                                                                                        | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | Where relevant and where permitted under applicable law, we use this information to resolve issues, monitor and detect fraud or suspicious activity in relation to your or a Customer's account and to identify potential risk or unlawful behavior including fraud detection, theft prevention, emergency response purposes and legal compliance. | The processing is necessary for our legitimate interests, namely identifying and mitigating the risk of unlawful behavior to protect the Service, Fingerprint and its Customers. |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | We use this information to determine products and services that may be of interest to you for marketing purposes.                                                                                                                                                                                                                                  | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Information about how you access and use the Service.** For example, how frequently you access the Service, the time you access the Service and how long you use it for, the approximate location that you access the Service from, whether you access the Service from multiple devices, and other actions you take on the Service.                                                                                                                                 | We use this information to monitor and improve the Service and business, and to inform the development of new products and services.                                                                                                                                                                                                               | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | We use information about how you use and connect to the Service to present the Service to you on your device.                                                                                                                                                                                                                                      | The processing is necessary for our legitimate interests, namely presenting the Service to our users so they can access and use our Service.                                     |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | Where relevant and where permitted under applicable law, we use this information to resolve issues, monitor and detect fraud or suspicious activity in relation to your or a Customer's account and to identify potential risk or unlawful behavior including fraud detection, theft prevention, emergency response purposes and legal compliance. | The processing is necessary for our legitimate interests, namely identifying and mitigating the risk of unlawful behavior to protect the Service, Fingerprint and its Customers. |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | We use this information to tailor how the Service is displayed to you (such as the content that is provided to you through the Service and/or the language in which it is provided to you).                                                                                                                                                        | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | We use this information to determine products and services that may be of interest to you for marketing purposes.                                                                                                                                                                                                                                  | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |
| **Log files and information about your device.** We also collect information about the computer, tablet, smartphone or other electronic device you use to connect to the Service. This information can include details about the type of device, unique device identifying numbers, operating systems, browsers and applications connected to the Service through the device, your mobile network, your IP address and your device’s telephone number (if it has one). | We use this information to monitor and improve the Service and business, and to inform the development of new products and services.                                                                                                                                                                                                               | We will only process your personal information in this way to the extent that you have given us your consent to do so.                                                           |

### 4. Customer End User Data

We mostly only process personal data relating to Customer End Users to provide our services to the relevant Customer as a processor on behalf of the relevant Customer. However, where a Customer opts in to using our Device Reputation Network product, we will process the following personal data as a controller:

| Category of personal data                                                                                                                                                                                                                                                                 | How we may use it                                                                                                                                                                                                                  | Legal basis for the processing                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fraud flags.** Where Customers identify that a device is being used fraudulently, we will retain the device identifier generated by the Service and the fact that the device has been flagged for fraud, together with the number of times it has been flagged and when it was flagged. | We make this information available to Customers who opt in to use the Device Reputation Network feature of our Service, which enables Customers to identify devices previously flagged for, and therefore at higher risk of fraud. | The processing is necessary for our legitimate interests, namely providing the Device Reputation Network fraud risk feature of our Service. |

### 5. Anonymization and aggregation of information

In connection with the purposes and data uses described above, we may anonymize and aggregate any of the information we collect (so that it does not directly identify you). We may use such anonymized information for purposes that include testing our IT systems, research, data analysis, improving the Service and developing new products and features.

### 6. Recipients of your personal data

We may share your personal data with the parties and for the purposes set out in paragraph 7 (**Disclosure of Data**), paragraph 10 (**CI/CD tools**) and paragraph 11 (**Payments**) of the main body of this Privacy Policy.

We may provide third parties with aggregate statistical information and analytics about users of the Service but we will make sure no one can be identified from this information before we disclose it.

### 7. How long we store your personal data

Paragraph 6 (**Retention of Data**) of the main body of this Privacy Policy sets out how long we will retain your personal data. We retain fraud flags in connection with the provision of the Device Reputation Network, as described in paragraph 4 above, for 2 years.

### 8. Marketing and Advertising

From time to time we may send you emails about our products, services and features available on the Service. For some marketing messages, we may use personal information we collect about you to help us determine the most relevant marketing information to share with you.

We will give you the opportunity to opt out of these promotional messages when you sign up and create an account on the Service.

You can also withdraw your consent at a later date by clicking on the unsubscribe link at the bottom of our marketing emails or by updating your preferences through the Service.

We will not send you these messages if you opt out from receiving them, or if you do not give us your consent. We will, however, still need to contact you with non-promotional, technical service-related information about the Service.

### 9. Cookies

Our Service uses cookies and similar technologies such as pixels and JavaScript tags and Local Storage Objects (together "**cookies**") to distinguish you from other users. The cookies we use are necessary for the operation of certain features of our Service. We also use them to detect errors on our Service and apply security settings.

The following table sets out information about the cookies we use on our Service:

| Cookie             | Type of cookie | When is the cookie set                                  | How long does the cookie last      | Purpose of the cookie                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | -------------- | ------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Google Tags        | Functional     | On first visiting the fingerprint.com site (our "Site") | Until you finish browsing our Site | This tag allows us to integrate analytics, such as Google Analytics, and similar products that track and monitor website traffic into our Site. This enables us to see how the Site is performing in order to identify errors or features that users find confusing.<br />This data will not, however, be shared with other Google services or used for contextualizing or personalizing the advertising displayed to you.<br />You can learn more about Google’s practices at [http://www.google.com/policies/privacy/partners](http://www.google.com/policies/privacy/partners), and view its currently available opt-out options at [https://tools.google.com/dlpage/gaoptout](https://tools.google.com/dlpage/gaoptout) |
| \_vid\_t, \_vid\_i | Functional     | On first visiting the Site                              | 1 year                             | This cookie allows us to demonstrate the functionality of our Service to visitors of the Site.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| \_vid\_lr          | Functional     | On first visiting the Site                              | 1 year                             | This cookie is used to diagnose latency and performance issues                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| \_cfduiud          | Functional     | On first visiting the dev.fingerprint.com site          | 1 month                            | This cookie is used to identify individual clients behind a shared IP address and apply settings on a per-client basis. We use it in connection with ensuring the Site is presented to you in the correct language, and to identify trusted web traffic and apply security settings on a per-client basis.                                                                                                                                                                                                                                                                                                                                                                                                                  |

Other than cookies that are necessary for the operation of our Site, you will only receive cookies when you have given us your consent to do so. In addition, if you do not wish to receive cookies, most browsers allow you to change your cookie settings.

Depending on your device and operating system, you may not be able to delete or block all cookies. Please note that if you choose to refuse all cookies you may not be able to use the full functionality of our Service.

These settings will typically be found in the "options" or "preferences" menu of your browser. In order to understand these settings, the following links may be helpful, otherwise you should use the "Help" option in your browser for more details.

* **(a)** [Cookie settings in Internet Explorer](https://support.microsoft.com/en-gb/help/278835/how-to-delete-cookie-files-in-internet-explorer) and [Edge](https://support.microsoft.com/en-us/windows/microsoft-edge-browsing-data-and-privacy-bb8174ba-9d73-dcf2-9b4a-c582b4e640dd)
* **(b)** [Cookie settings in Firefox](http://support.mozilla.org/en-US/kb/cookies)
* **(c)** [Cookie settings in Chrome](https://support.google.com/chrome/answer/95647?hl=en)
* **(d)** [Cookie settings in Opera](https://help.opera.com/en/latest/web-preferences/)
* **(e)** [Cookies settings in Safari web](https://support.apple.com/en-gb/guide/safari/manage-cookies-and-website-data-sfri11471/mac) and [iOS](https://support.apple.com/en-gb/HT201265).

If you would like to find out more about cookies and other similar technologies, please visit [www.allaboutcookies.org](http://www.allaboutcookies.org) or the Network Advertising Initiative's online sources at [www.networkadvertising.org](http://www.networkadvertising.org).

### 10. Transfer of Data

Your personal data may be transferred to – and maintained on – computers located outside of your state, province, country or other governmental jurisdiction where the data protection laws may differ from those of your jurisdiction.

If you choose to provide information to us, please note that we are located in the United States and your personal data will be transferred to, and processed in, the United States. We may also further transfer your personal data to other entities within the United States or other countries outside of the United Kingdom, Switzerland or the EEA to process it there. Where this is the case, we typically rely on either (i) an “adequacy decision” (where (as applicable) the European Commission, UK Secretary of State or Swiss Federal Council has deemed a country or international organisation to adequately safeguard personal information), (ii) standard contractual clauses adopted by (as applicable) the European Commission, UK Secretary of State or Federal Data Protection and Information Commissioner; or (iii) certification to the EU-U.S., Swiss-U.S. Data Privacy Framework and UK Extension (“DPF”) (a framework designed by the U.S. Department of Commerce and the European Commission (and respectively the Swiss Federal Council and UK Secretary of State) to ensure adequate protection for personal information transferred to a company participating in the DPF) as the appropriate safeguard in relation to such transfers.

FingerprintJS Inc. will take all the steps reasonably necessary to ensure that your data is treated securely and in accordance with this European Data Annex, including implementing adequate safeguards with respect to the security and handling of your personal data.

If you wish to enquire further about the safeguards we use, please contact us using the contact details in paragraph 15 (**Contact Us**) in the main body of this Privacy Policy.

### 11. Your Data Protection Rights

In accordance with applicable privacy law you have the following rights in respect of your personal data that we hold:

* **(a)** **Right of access**. You have the right to obtain:
* **(i)** confirmation of whether, and where, we are processing your personal data;
* **(ii)** information about the categories of personal data we are processing, the purposes for which we process your personal data and information as to how we determine applicable retention periods;
* **(iii)** information about the categories of recipients with whom we may share your personal data; and
* **(iv)** a copy of the personal data we hold about you.
* **(b)** **Right of portability**. You have the right, in certain circumstances, to receive a copy of the personal data you have provided to us in a structured, commonly used, machine-readable format that supports re-use, or to request the transfer of your personal data to another person.
* **(c)** **Right to rectification**. You have the right to obtain rectification of any inaccurate or incomplete personal data we hold about you without undue delay.
* **(d)** **Right to erasure**. You have the right, in some circumstances, to require us to erase your personal data without undue delay if the continued processing of that personal data is not justified.
* **(e)** **Right to restriction**. You have the right, in some circumstances, to require us to limit the purposes for which we process your personal data if the continued processing of the personal data in this way is not justified, such as where the accuracy of the personal data is contested by you.
* **(f)** **Right to withdraw consent**. If you have provided consent for the processing of your personal data, you have the right to withdraw your consent. If you withdraw your consent, this will not affect the lawfulness of our use of your personal data before your withdrawal.

**You have a right to object to any processing based on our legitimate interests. There may, depending on the particular circumstances, be compelling reasons for continuing to process your personal data despite your objection, and we will assess and inform you if that is the case. You can object to marketing activities for any reason.**

If you wish to exercise one of these rights, please contact us using the contact details in paragraph 15 (**Contact Us**) in the main body of this Privacy Policy.

You also have the right to lodge a complaint to your national data protection authority.

If you are in the UK, the relevant authority is the Information Commissioner's Office – please visit [https://ico.org.uk/make-a-complaint/](https://ico.org.uk/make-a-complaint/) for more information. You also have the right to submit a complaint directly to us.

If you are in the EEA, further information about how to contact your local data protection authority is available at [http://ec.europa.eu/justice/data-protection/bodies/authorities/index\_en.htm](http://ec.europa.eu/justice/data-protection/bodies/authorities/index_en.htm).

If you are in Switzerland, please visit [https://www.edoeb.admin.ch/edoeb/en/home/the-fdpic/links/data-protection---switzerland.html](https://www.edoeb.admin.ch/edoeb/en/home/the-fdpic/links/data-protection---switzerland.html) for more information.

### 12. Links to third party sites

The Service may, from time to time, contain links to and from third party websites, including those of other users, our partner networks, advertisers, partner merchants, news publications, retailers and affiliates. If you follow a link to any of these websites, please note that these websites have their own privacy policies and that we do not accept any responsibility or liability for their policies. Please check the individual policies before you submit any information to those websites.

### 13. Our Policy towards children

The Service is not directed at persons under 18 and we do not knowingly collect personal data from children under 18. If you become aware that your child has provided us with personal data, without your consent, then please contact us using the contact details in paragraph 15 (**Contact Us**) in the main body of this Privacy Policy so that we can take steps to remove such information as quickly as possible.

### 14. Changes to this policy

We may update this European Data Annex from time to time and so you should review this page periodically. When we change this European Data Annex in a material way, we will update the "last modified" date at the beginning of this European Data Annex. Changes to this European Data Annex are effective when they are posted on this page.

### 15. Notice to you

If we need to provide you with information about something, whether for legal, marketing or other business related purposes, we will select what we believe is the best way to get in contact with you. We will usually do this through email. The fact that we may send notices to you will not stop you from being able to opt out of certain types of contact as described in this European Data Annex.

What’s Next

* [Start your free subscription now](https://dashboard.fingerprintjs.com/signup/)


# Product Roadmap
Source: https://docs.fingerprint.com/docs/product-roadmap





# Request filtering
Source: https://docs.fingerprint.com/docs/request-filtering

Block unwanted identification requests to prevent malicious actors from misusing your Fingerprint public API keys.

To provide device intelligence, Fingerprint runs on the client device — inside the browser or a mobile app. Client-side code can be easily examined, therefore, the API key you use to make identification requests to Fingerprint is by definition a *public API key*.

To prevent malicious actors from misusing your public API key and inflating your [Fingerprint costs](/docs/billing), you can filter out unwanted identification requests. These requests are not billed and will receive an error instead of the identification result.

* To filter requests from web browsers by **origin** or **HTTP header**, see [Request filtering for websites](/docs/request-filtering-for-websites).
* To filter requests from mobile apps by **package names** or **bundle IDs**, see [Request filtering for mobile apps](/docs/mobile-app-filtering).
* To filter requests from common indexing and AI bots, see [Search bot request filtering](/docs/search-bots-filtering) and [AI bot request filtering](/docs/ai-bot-filtering) respectively.
* To filter requests from a range of IP addresses, see [Network request filtering](/docs/network-request-filtering).

<Warning>
  **We rolled out the beta for [Request Filtering V2](/docs/request-filtering-v2).**

  New iteration of request filtering gives you more flexibility and control when blocking unwanted identification requests. You have full control over order of execution, and you can create more complex rules by using our flexible expression language.
</Warning>

***

What’s Next

* [Start your free workspace now](https://dashboard.fingerprintjs.com/signup/)


# Request filtering for websites
Source: https://docs.fingerprint.com/docs/request-filtering-for-websites



To prevent malicious actors from misusing your public API key, you can [filter out unwanted identification requests](/docs/request-filtering). These requests are not billed and will receive an error instead of the identification result.

This page covers filtering requests made from web browsers. You can filter requests by **website origin** or **HTTP headers**. To block requests from mobile apps, see [Request filtering for mobile apps](/docs/mobile-app-filtering).

## Configuration

Inside the Dashboard, navigate to **Security** in the left-hand menu.

### Filter by website origin

You can create a *blocklist* or *allowlist* of specific origins.

* *Allowlist*: If you only need to use your public API key on a few origins, you should allow only those origins and block all others.
* *Blocklist*: If you need to use your public API key on many origins, you can choose to only block specific origins you suspect might be stealing your API key.

<img alt="Screenshot of how to configure request filtering in the FingerprintJS dashboard" />

To filter requests by origin:

1. Navigate to the **[Security](https://dashboard.fingerprint.com/traffic-rules)** > **Web**.
2. Under **Websites**, click **Configure**.
3. To create an *Allowlist*, set **Default behavior** to  `Forbid all besides origins listed below`. Then fill in the **Exceptions** field with your list of allowed origins.
4. Alternatively, to create a *Blocklist*, set **Default behavior** to  `Allow all besides origins listed below`. Then fill in the **Exceptions** field with your list of blocked origins.
5. Click **Save**.

<img alt="Screenshot of the form required to set up an origin allowlist" />

<Note>
  A website origin is defined by the scheme and the domain name of the URL used to access it.\
  You can use the wildcard character (\*) as a subdomain name.
</Note>

### Filter by HTTP header

You can filter out identification requests by HTTP headers. Requests you might want to filter out include server-side rendering applications, crawlers, search indexing bots, or website availability monitors.

To filter requests by HTTP header:

1. Navigate to the **[Security](https://dashboard.fingerprint.com/traffic-rules)** > **Web**.
2. Under **Forbidden HTTP Headers**, click **Add rule**.
3. Fill in the **Header** name.
4. Choose your **Match Rule**.
5. Fill in the **Value**. You can use regular expressions.

<img alt="Screenshot of the form required to create an HTTP header rule" />

<Note>
  **Regular expressions in header rules**

  The regular expression (regex) match rule is defined by the [RE2](https://github.com/google/re2) notation. To make sure you are using the correct notation, you can:

  1. Go to [regex101.com](https://regex101.com/).
  2. Select the **Golang Flavor** option on the left.
  3. Debug the regular expression to suit your needs.
  4. Copy the **Regular expression** and paste it into the **Value** field in the rule form as-is.
</Note>

## Limitations

* The maximum number of request filtering rules on the web is defined by [Account limits](/docs/billing#account-limits). If you need more request filtering rules, please reach out to our [support team](https://fingerprint.com/support/).
* It can take up to 5 minutes to start filtering incoming requests after creating or editing an origin or header rule.

## Rule Priority and Examples

If *any* rule matches, the request filtering processing stops, and the result is immediately applied. This has clear interaction when only **Forbidden Origins** rules are set up but might be less clear when both **Allowed Origins** and **Forbidden HTTP Headers** rules are involved. The basic precedence is as follows:

1. **Allowed/Forbidden Origins** rules are checked **first**.
2. **Forbidden HTTP Headers** rules are checked **second**.

Let us illustrate that interaction on a more specific example.

### Rules Configuration

We'll configure two different rules

* one is going to whitelist our own website (`https://example.com`) and
* the second one is going to further prohibit any headers coming from `somesocialnetwork` **Referer**.

<img alt="Allowed Origins + Forbidden HTTP Headers rules" />

### Result

Because the **Allowed Origins** rule has strict precedence, we will see the following result.

| Origin                | Headers                        | Result      |
| :-------------------- | :----------------------------- | :---------- |
| `https://example.com` | Referer: somesocialnetwork.com | **`ALLOW`** |

As you can see on the example, the request came through because the **Allow Origins** rule was applied first, and that stopped the processing despite having somesocialnetwork.com as a **Referer**.


# Roles & permissions
Source: https://docs.fingerprint.com/docs/roles-permissions



Any user of the Fingerprint Dashboard can only have access to one account. Within that account, access to multiple workspaces is determined by the account owners based on access preferences and user permissions.

To invite team members and manage their access, navigate to **Settings** > [**Team members**](https://dashboard.fingerprint.com/settings/users).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 56 11@2x" />
</Frame>

## Team Roles

Account administrators or team managers can invite other people to join the team and access the Fingerprint account.

When inviting a team member, you select their role. Standard roles include:

* **Viewer** - Read-only access on your account. Can view analytics and configuration resources on all workspaces.
* **Editor** - Edit access on your account. Can manage analytics and configuration resources on all workspaces.
* **Billing Admin** - Manages account-wide billing options, but no access to any workspace-specific resources.
* **Administrator** - Full unrestricted access.

## Granular Permissions

You have the ability to fine tune user access by customizing both account permissions, and permissions for each workspace.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 14 00 33@2x" />
</Frame>

For most permissions you can set them as **None**, **View**, or **Edit**.

* **None** - no access to specified features or resources
* **View** - read-only access to specified features or resources
* **Edit** - full managing access to specified features or resources

Reference of available granular permissions and their settings:

| Scope     | Permission                               | None                                 | View                                                                 | Edit                                                              |
| --------- | ---------------------------------------- | ------------------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Account   | **Billing**                              | Can't view billing information       | Can view billing information                                         | Can manage billing information, payment methods, and plan options |
| Account   | **Members**                              | Can't view team members              | Can view team members                                                | Can invite members and manage their permissions                   |
| Workspace | [**Analytics**](/docs/analytics)         | No access to analytics               | View access to analytical pages                                      | View access + ability to manage *Suspect Score*                   |
| Workspace | [**Configuration**](/docs/configuration) | No access to configuration resources | View access to configuration resources                               | Managing access to configuration resources                        |
| Workspace | **PII**                                  | Can't view PII                       | Visible IP address, country, and other data derived from geolocation | -                                                                 |


# Search bot request filtering
Source: https://docs.fingerprint.com/docs/search-bots-filtering

Allow basic search bots filtering through a single switch in the Request Filtering Dashboard section

Search bots generate legitimate internet traffic allowing search engines to index your website. But you might not want search bots to trigger Fingerprint Identification or Smart Signals processing.

Although you can [filter requests based on the `User-Agent` header](/docs/request-filtering-for-websites#filter-by-http-header), you would need to manage your list of all different search bot `User-Agent` strings. Instead, we keep and update our own list of search bot filtering rules that **can be turned on or off through a switch in the Dashboard**.

Search bots that are filtered through this setting then behave in the same way as other request filtering rules and you don't get billed for them. Keep in mind that we won't return any information except `requestId` in those cases.

<Note>
  Search bots filtering based on `User-Agent` is a basic mechanism we provide for free to filter out commonly encountered and generally well behaved search bots.
  Because of its simplicity, it might introduce both **false positive and false negative** cases. If you need **better protection against sophisticated bots**, check out our [Smart Signals that contain a paid Bot Detection product](/docs/smart-signals-reference#browser-bot-detection).
</Note>

## Configuration

Search Bots Filtering can be turned on or off in our Dashboard.

1. Navigate to **Dashboard** > **[Security](https://dashboard.fingerprint.com/traffic-rules)** and switch to the **Bots** tab.
2. Enable **Exclude Search Bots** to start filtering search bots from your billable API calls.

<img alt="Dashboard - Search Bots Filtering" />

## List of supported search bots `User-Agent` strings

The list of search bots`User-Agent` strings we support is public and we keep it updated based on the currently supported `User-Agent` strings. The following table contains all supported `User-Agent` strings with their respective information sources.

| Owner      | User-Agent (Substrings)                                                                                                                                                                                                                                                                                                    | Public doc                                                                                     |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Mail.ru    | `mail.ru`                                                                                                                                                                                                                                                                                                                  | [source](https://help.mail.ru/webmaster/indexing/robots/robot_log)                             |
| Microsoft  | `bingbot`<br />`AdIdxBot`<br />`MicrosoftPreview`                                                                                                                                                                                                                                                                          | [source](https://www.bing.com/webmasters/help/which-crawlers-does-bing-use-8c184ec0)           |
| Apple      | `applebot`                                                                                                                                                                                                                                                                                                                 | [source](https://support.apple.com/en-us/HT204683)                                             |
| Huawei     | `petalbot`                                                                                                                                                                                                                                                                                                                 | [source](https://webmaster.petalsearch.com/site/petalbot)                                      |
| Naver      | `naver.me/spd`                                                                                                                                                                                                                                                                                                             | [source](https://help.naver.com/service/5626/contents/8026)                                    |
| Yahoo      | `slurp`                                                                                                                                                                                                                                                                                                                    | [source](https://help.yahoo.com/kb/SLN22600.html)                                              |
| Baidu      | `baiduspider`                                                                                                                                                                                                                                                                                                              | [source](https://www.baidu.com/search/robots_english.html)                                     |
| Sogou      | `sogou web spider`<br />`sogou wap spider`<br />`sogou pic spider`                                                                                                                                                                                                                                                         | [source](https://help.sogou.com/spider.html)                                                   |
| Exalead    | `exabot`                                                                                                                                                                                                                                                                                                                   | [source](https://www.exalead.com/search/webmasterguide)                                        |
| Coccoc     | `coccocbot`                                                                                                                                                                                                                                                                                                                | [source](https://help.coccoc.com/en/search-engine/coccoc-robots)                               |
| Seznam     | `seznamBot`                                                                                                                                                                                                                                                                                                                | [source](https://napoveda.seznam.cz/cz/fulltext-hledani-v-internetu/seznambot)                 |
| Google     | `googlebot`<br />`AdsBot-Google`<br />`Storebot-Google`<br />`APIs-Google`<br />`AdsBot-Google-Mobile`<br />`Mediapartners-Google`<br />`Googlebot-Image`<br />`Googlebot-News`<br />`Googlebot-Video`<br />`AdsBot-Google-Mobile-Apps`<br />`FeedFetcher-Google`<br />`Google-Read-Aloud`<br />`Google-Site-Verification` | [source](https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers) |
| Yandex     | `yandex.com/bots`                                                                                                                                                                                                                                                                                                          | [source](https://yandex.com/support/webmaster/robot-workings/check-yandex-robots.html)         |
| Bytedance  | `bytespider`                                                                                                                                                                                                                                                                                                               | [source](https://zhanzhang.toutiao.com/docs/intro/26899)                                       |
| Duckduckgo | `duckduckbot`                                                                                                                                                                                                                                                                                                              | [source](https://duckduckgo.com/duckduckgo-help-pages/results/duckduckbot/)                    |
| Ahrefs     | `AhrefsBot`<br />`AhrefsSiteAudit`                                                                                                                                                                                                                                                                                         | [source](https://ahrefs.com/robot)                                                             |
| Facebook   | `facebookexternalhit`<br />`facebookcatalog`                                                                                                                                                                                                                                                                               | [source](https://developers.facebook.com/docs/sharing/webmasters/crawler/)                     |
| Pinterest  | `Pinterestbot`                                                                                                                                                                                                                                                                                                             | [source](https://help.pinterest.com/en/business/article/pinterest-crawler)                     |
| Cincraw    | `Cincraw`                                                                                                                                                                                                                                                                                                                  | [source](https://cincrawdata.net/bot/)                                                         |
| Semrush    | `http://www.semrush.com/bot.html`                                                                                                                                                                                                                                                                                          |                                                                                                |
| Seekport   | `SeekportBot`                                                                                                                                                                                                                                                                                                              | [source](https://bot.seekport.com/)                                                            |
| Amazon     | `Amazonbot/0.1`<br />`amazonproductbot`                                                                                                                                                                                                                                                                                    | [source](https://developer.amazon.com/support/amazonbot)                                       |
| DataDog    | `datadog`                                                                                                                                                                                                                                                                                                                  | [source](https://docs.datadoghq.com/synthetics/guide/identify_synthetics_bots)                 |


# Status Page
Source: https://docs.fingerprint.com/docs/status





# Terms of service
Source: https://docs.fingerprint.com/docs/terms-of-service

Effective date: Nov 1, 2026. | [Archived Versions](/docs/legal-archive)

These Terms of Service, as amended from time to time (“**Terms**”), are entered into by and between FingerprintJS, Inc., a Delaware corporation (“**FingerprintJS**”), and the customer identified during Onboarding (“**Customer**”).

“**Onboarding**” means the process by which Customer procures from FingerprintJS a subscription to use the Service through a self-service sign-up process made available on FingerprintJS’s website. These Terms and any terms agreed-to during Onboarding are collectively referred to herein as the “**Agreement**”. By accessing or using the Service (as defined below) or clicking a button or checking a box marked “Submit”, “I Agree”, “I Accept”, or something similar, or by otherwise affirmatively manifesting assent to this Agreement, Customer signifies that Customer has read, understood, and agrees to be bound by this Agreement as of Customer’s completion of Onboarding (such date, the “**Effective Date**”).

**PLEASE NOTE: THE SERVICE IS MADE AVAILABLE ON A SUBSCRIPTION BASIS. YOUR SUBSCRIPTION FOR THE SERVICE AND THIS AGREEMENT WILL BE AUTOMATICALLY RENEWED FOR SUCCESSIVE BILLING PERIODS AT OUR THEN-CURRENT PRICING UNLESS YOU OPT OUT OF THE AUTO-RENEWAL IN ACCORDANCE WITH SECTION 5.iv BELOW.**

## 1. Fingerprint Service

### 1.i Subscription

Subject to the terms and conditions of this Agreement, and in each case solely during the Subscription Term: (a) FingerprintJS hereby grants Customer a limited, revocable, non-exclusive, non-transferable (except in compliance with Section 13.i) right and license to install the Agent on the Customer Website solely as necessary to use the Service in accordance with the Documentation; ii) right and license to install or use the Mobile SDKs; and (b) Customer and its Users may remotely access the Dashboard. Such use is limited to Customer's internal use. Customer and each User must keep Credentials confidential and not share them with anyone else. Customer is responsible for (i) its Users’ compliance with this Agreement and actions taken through their Credentials and (ii) disabling access to the Service by any User who is no longer an employee of Customer.

### 1.ii Restrictions

Customer shall not use the Service for any purposes beyond the scope of the access granted in this Agreement. Customer shall not at any time, directly or indirectly (and shall not allow and third party to): (a) copy, modify, or create derivative works of the Service or any component thereof; (b) rent, lease, lend, sell, license, sublicense, assign, distribute, publish, transfer, or otherwise make available the Service or any component thereof; (c) reverse engineer, disassemble, decompile, decode, adapt, or otherwise attempt to derive or gain access to the Agent or Mobile SDKs or any other software component of the Service, in whole or in part; (d) remove any proprietary notices from the Service or any component thereof; (e) use the Service or any component thereof in any manner or for any purpose that infringes, misappropriates, or otherwise violates any intellectual property right or other right of any person, or that violates any applicable law; or (f) use the Service or any component thereof for any benchmarking purpose or for the purpose of developing or assisting in the development of a product or service that competes with the Service, that utilizes functions and features similar to those of the Service or that copies the Service or any part, feature, function, graphics or user interface of the Service; (g) use browser automation tools or any software applications that run automated tasks to create accounts, subscriptions, users or other resources in the Service; (h) bypass or ignore instructions that control access to the Service, including attempting to circumvent any rate limiting systems by using multiple API keys, directing traffic through multiple IP addresses, or otherwise obfuscating the source of traffic you send to the Service; (i) attempt to gain unauthorized access to, interfere with, damage, or disrupt any parts of the Service, the server on which the Service is stored, or any server, computer, or database connected to the Service; (j) use the Service to transmit any computer viruses, worms, defects, Trojan horses, or other items of a destructive nature to violate the security of any computer network, crack passwords or security encryption codes; or (k) access, retrieve, or index any portion of the Service for purposes of constructing or populating a searchable database.

## 2. Support Terms

During the Subscription Term, FingerprintJS will use commercially reasonable efforts to respond in a timely manner to support tickets sent by Customer to [support@fingerprint.com](mailto:support@fingerprint.com).

## 3. Data Rights

### 3.i Visitor Data and Personal Information

#### 3.i(a) License Grant

Customer grants FingerprintJS a non-exclusive, non-transferable (except in compliance with Section 13.i) right and license to: (i) use, copy, store, transmit, display, modify and create derivative works of Visitor Data as necessary to provide the Service to Customer under this Agreement and as otherwise described in the Privacy policy; (ii) aggregate the Visitor Data with other data in a de-identified form and to use such derived data for any lawful purpose both during and after the Subscription Term; and (iii) if Customer elects to use the DRN as part of the Service, use any Fraud Identification Data that the Customer submits to FingerprintJS to maintain the DRN and make the Fraud Identification Data contained within the DRN available to other customers of FingerprintJS.

#### 3.i(b) DRN

Customer acknowledges that the license in Section 3.i.a(iii) shall survive termination of the Agreement or termination of the Customer’s use of or access to the DRN as part of the Service, and FingerprintJS shall not be required to delete any Fraud Identification Data maintained by FingerprintJS as part of the DRN on termination of the Agreement or on termination of Customer’s use of or access to the DRN.

#### 3.i(c) Data Processing

If Customer is established in the European Economic Area, the United Kingdom, or Switzerland, or if any Personal Information processed by FingerprintJS in connection with the Service otherwise falls within the scope of the European Data Privacy Legislation, FingerprintJS will process any such Personal Information in accordance with FingerprintJS’ GDPR data processing addendum, which will be incorporated by reference into this Agreement and can be accessed at [https://dev.fingerprint.com/docs/dpa-gdpr](https://dev.fingerprint.com/docs/dpa-gdpr) (as modified from time to time). If Customer is subject to US Data Protection Laws or if any Personal Information processed by FingerprintJS in connection with the Service includes Personal Information within the scope of such US Data Protection Laws, FingerprintJS will process any such Personal Information in accordance with FingerprintJS’ US Data Protection Laws data processing addendum, which will be incorporated by reference into this Agreement and can be accessed [https://docs.fingerprint.com/docs/dpa-usspl](https://docs.fingerprint.com/docs/dpa-usspl) (as modified from time to time). Notwithstanding the foregoing, if the parties agree in writing to use a different data processing addendum, such data processing addendum will apply in lieu of either of the foregoing data processing addenda.

### 3.ii Usage Data

FingerprintJS may collect Usage Data and use it to operate, improve and support the Service and for other lawful business practices, such as analytics, benchmarking and reports. However, FingerprintJS will not disclose Usage Data to third parties (other than duly appointed service providers), including in benchmarks or reports, unless it has been (a) de-identified so that it does not individually identify Customer, its Users or any other person and (b) aggregated with usage data across other FingerprintJS customers.

### 3.iii Security

FingerprintJS uses reasonable technical and organizational measures designed to protect the Service and Visitor Data.

### 3.iv Location

Customer may elect to deploy the Service in the following regions: United States, European Union, and Asia. If United States is selected, Visitor Data that contains Personal Information will be stored in data centers located in the US; if European Union is selected, Visitor Data that contains Personal Information will be stored in data centers located in the EU; if Asia is selected, Visitor Data that contains Personal Information will be stored in data centers located in India. Data derived from Visitor Data that does not contain personal information may be stored in data centers located in a region different than their primary region.

## 4. Customer Obligations

Customer (a) is solely responsible for its Visitor Data (including its content) and compliance with all Applicable Laws in its use of the Service and (b) represents and warrants that it has made all necessary disclosures and obtained all necessary consents required for its submission of data and granting of rights to FingerprintJS under this Agreement without violating or infringing any third-party intellectual property or privacy rights or Customer or third-party terms of service or privacy policies.

## 5. Commercial Terms

### 5.i Types of Plans

As described on the FingerprintJS pricing page (located at [https://fingerprint.com/pricing/](https://fingerprint.com/pricing/)) (the “**Pricing Page**”), two tiers of the Service are made available by FingerprintJS: (a) a free tier (“**Free Plan**”) and (b) a paid tier (“**Paid Plan**”). Except as otherwise expressly noted, both the Free Plan and Paid Plan are subject to the terms of this Agreement.

### 5.ii Fees and Taxes

Fees are as described on the Pricing Page. All fees and expenses are non-refundable except as set out in Section 10.i (FingerprintJS Indemnity). Customer is responsible for any sales, use, GST, value-added, withholding or similar taxes or levies that apply to any amounts payable by Customer hereunder, whether domestic or foreign (“**Taxes**”), other than FingerprintJS’s income tax. Fees and expenses are exclusive of Taxes.

### 5.iii Payment; Billing

Customer must provide FingerprintJS with a current, valid accepted method of payment (as it may be updated from time to time, “**Payment Method**”) in order to purchase and use a Paid Plan. FingerprintJS uses a third party payment processor (currently Stripe, Inc. (“**Stripe**”)) to process payments using the provided Payment Method. By starting a Paid Plan and providing or designating a Payment Method, Customer agrees to be bound by Stripe’s Services Agreement available at [https://stripe.com/us/legal](https://stripe.com/us/legal) and further authorizes FingerprintJS to charge Customer any applicable fees at the then current rate, and any other charges Customer may incur in connection with Customer’s use of the Service, to Customer’s Payment Method. Customer acknowledges that the amount billed each period may vary for reasons that may include the particular number of Unique Browser Instances during such period, different plan options or services, promotional offers, and/or changing a plan, and Customer authorizes FingerprintJS to charge Customer’s Payment Method for such varying amounts, which may be billed in one or more charges. Fees for the Service may be billed at the beginning of the applicable billing cycle or at a later period, depending on the specific details of the Customer’s Paid Plan (as described on the Pricing Page).

### 5.iv Automatic Renewal

After Customer’s initial billing cycle, and again after any subsequent billing cycle, Customer’s subscription will automatically commence on the first day following the end of such period (each a “**Renewal Commencement Date**”) and continue for an additional equivalent period, at FingerprintJS’s then-current price for such subscription. Customer agrees that its Payment Method will be subject to this automatic renewal feature unless Customer cancels its subscription at least thirty (30) days prior to the Renewal Commencement Date. By subscribing, Customer authorizes FingerprintJS to charge Customer’s Payment Method for the initial billing cycle and any subsequent billing cycle. Customer reserves the right to change the timing of its billing as indicated in this Section 5.iii. FingerprintJS may authorize your Payment Method in anticipation of subscription or other charges.

### 5.v Fee Changes

FingerprintJS, in its sole discretion and at any time, may modify the fees for the Service. Any fee change will become effective at the end of the then-current billing cycle. FingerprintJS will provide Customer with reasonable prior notice of any change in fees. Customer’s continued use of Service after a fee change comes into effect constitutes Customer’s agreement to pay the modified fee amount.

### 5.vi Suspension of Service

FingerprintJS may suspend Customer’s access to the Service if (a) Customer breaches Section 1.ii (Restrictions) or Section 4 (Customer Obligations), (b) if Customer’s account is 30 days or more overdue, (c) if Customer’s actions risk harm to other customers or the security, availability or integrity of the Service, or (d) in the case of Free Plan accounts, if no API calls have been made for a continuous period of 90 days. Where practicable, FingerprintJS will use reasonable efforts to provide Customer with prior notice of the suspension. Once Customer resolves the issue requiring suspension, FingerprintJS will promptly restore Customer’s access to the Service in accordance with this Agreement. For Free Plan accounts suspended due to inactivity, FingerprintJS may terminate the account if no activity resumes within 7 days after notice of suspension is provided to Customer.

## 6. Warranty Disclaimer

### 6.i Disclaimers

THE SERVICE IS PROVIDED “AS IS”. FINGERPRINTJS AND ITS SUPPLIERS MAKE NO OTHER WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NONINFRINGEMENT. FINGERPRINTJS DOES NOT WARRANT VISITOR DATA WILL BE ACCURATE OR PRESERVED WITHOUT LOSS. FINGERPRINTJS IS NOT LIABLE FOR DELAYS, FAILURES OR PROBLEMS INHERENT IN USE OF THE INTERNET AND ELECTRONIC COMMUNICATIONS OR OTHER SYSTEMS OUTSIDE FINGERPRINTJS’S CONTROL. FEATURES OF THE SERVICE DESIGNED TO DETECT AND FILTER CATEGORIES OF DATA HAVE INHERENT LIMITATIONS. FINGERPRINTJS DOES NOT GUARANTEE THAT THE SERVICE WILL DETECT OR FILTER ALL DATA WITH COMPLETE ACCURACY. CUSTOMER IS SOLELY RESPONSIBLE FOR ITS OWN DATA HANDLING POLICIES. CUSTOMER MAY HAVE OTHER STATUTORY RIGHTS, BUT ANY STATUTORILY REQUIRED WARRANTIES WILL BE LIMITED TO THE SHORTEST LEGALLY PERMITTED PERIOD. CUSTOMER HEREBY AGREE TO WAIVE ALL LAWS THAT MAY LIMIT THE EFFICACY OF SUCH RELEASES CONTAINED HEREIN. WITHOUT LIMITING THE FOREGOING, CUSTOMER SPECIFICALLY AGREES TO WAIVE THE PROVISIONS OF CALIFORNIA CIVIL CODE SECTION 1542, WHICH PROVIDES “A GENERAL RELEASE DOES NOT EXTEND TO CLAIMS WHICH THE CREDITOR DOES NOT KNOW OR SUSPECT TO EXIST IN HIS FAVOR AT THE TIME OF EXECUTING THE RELEASE, WHICH IF KNOWN BY HIM MUST HAVE MATERIALLY AFFECTED HIS SETTLEMENT WITH THE DEBTOR.”

## 7. Term and Termination

### 7.i Term

This Agreement starts on the Effective Date and continues until terminated in accordance with this Agreement (the “**Subscription Term**”).

### 7.ii Termination

Either party may terminate this Agreement if the other party (a) fails to cure a material breach of this Agreement (including a failure to pay fees) within 30 days after written notice, (b) ceases operation without a successor or (c) seeks protection under a bankruptcy, receivership, trust deed, creditors’ arrangement, composition or comparable proceeding, or if such a proceeding is instituted against that party and not dismissed within 60 days. Notwithstanding anything to the contrary in this Agreement, FingerprintJS may, in its sole and absolute discretion (x) terminate any Free Plan at any time and for any reason without notice and (y) terminate any Paid Plan for any reason with thirty (30) days’ prior written notice.

### 7.iii Effect of Termination

Upon expiration or termination of this Agreement, (a) Customer’s right to use the Service (including its license to any Agent and the Mobile SDKs) will terminate, and (b) Customer shall immediately cease any and all use of and access to the Service. At the disclosing party’s request upon expiration or termination of this Agreement, the receiving party will delete all of the disclosing party’s Confidential Information (as defined in Section 11) in its possession or control. Customer acknowledges that following termination it shall have no further access to any Visitor Data input into the Service, and that FingerprintJS may delete any such data as may have been stored by FingerprintJS at any time. Visitor Data and other Confidential Information may be retained in the receiving party’s standard backups after deletion but will remain subject to this Agreement’s confidentiality restrictions.

### 7.iv Survival

These Sections survive expiration or termination of this Agreement: 1.ii (Restrictions), 3.i (Visitor Data) (but solely as it relates to derived data and 3.i.c. (Data Processing)), 3.ii (Usage Data), 4 (Customer Obligations), 5.ii (Fees and Taxes), 6.i (Disclaimers), 7.iii (Effect of Termination), 7.iv (Survival), 8 (Ownership), 9 (Limitations of Liability), 10 (Indemnification), 11 (Confidentiality), 13 (General Terms) and 14 (Definitions). Except where an exclusive remedy is provided, exercising a remedy under this Agreement does not limit other remedies a party may have.

## 8. Ownership

Neither party grants the other any rights or licenses not expressly set out in this Agreement. Except for FingerprintJS’s use rights in this Agreement, between the parties Customer retains all intellectual property and other rights in Visitor Data provided to FingerprintJS. Except for Customer’s limited license and use rights set forth in Section 1 of this Agreement, FingerprintJS and its licensors retain all intellectual property and other rights in the Service, the Agent and Mobile SDKs, and any related FingerprintJS technology, including any modifications or improvements to these items made by FingerprintJS. If Customer provides FingerprintJS with feedback or suggestions regarding the Service or other FingerprintJS offerings, FingerprintJS may use the feedback or suggestions without restriction.

## 9. Limitations of Liability

### 9.i Consequential Damages Waiver

NEITHER FINGERPRINTJS NOR ITS SUPPLIERS WILL HAVE ANY LIABILITY ARISING OUT OF OR RELATED TO THIS AGREEMENT FOR ANY LOSS OF USE, LOST DATA, LOST PROFITS, FAILURE OF SECURITY MECHANISMS, INTERRUPTION OF BUSINESS OR ANY INDIRECT, SPECIAL, INCIDENTAL, RELIANCE OR CONSEQUENTIAL DAMAGES OF ANY KIND, EVEN IF INFORMED OF THEIR POSSIBILITY IN ADVANCE.

### 9.ii Liability Cap

FINGERPRINTJS’S (AND ITS SUPPLIERS’) ENTIRE LIABILITY ARISING OUT OF OR RELATED TO THIS AGREEMENT WILL NOT EXCEED IN AGGREGATE THE AMOUNTS PAID OR PAYABLE BY CUSTOMER TO FINGERPRINTJS DURING THE 12 MONTHS IMMEDIATELY PRECEDING THE CLAIM (OR, IF FEWER THAN 12 MONTHS HAVE ELAPSED UNDER THE AGREEMENT, THE AVERAGE MONTHLY FEES PAID OR PAYABLE BY CUSTOMER TO FINGERPRINTJS UNDER THE AGREEMENT MULTIPLIED BY 12).

### 9.iii Nature of Claims and Failure of Essential Purpose

The waivers and limitations in this Section 9 apply regardless of the form of action, whether in contract, tort (including negligence), strict liability or otherwise and will survive and apply even if any limited remedy in this Agreement fails of its essential purpose.

## 10. Indemnification

### 10.i FingerprintJS Indemnity

FingerprintJS will defend Customer from and against any third-party claim to the extent alleging that the Service, when used as authorized by Customer, infringes a third-party’s U.S. patent, copyright or trademark, and will indemnify Customer against any damages or costs finally awarded by a court of competent jurisdiction against Customer (including reasonable attorneys’ fees) or agreed in settlement by FingerprintJS resulting from the claim. In response to an actual or potential infringement claim, if required by settlement or injunction or as FingerprintJS determines necessary to avoid material liability, FingerprintJS may at its option: (a) procure rights for Customer’s continued use of the Service, (b) replace or modify the alleged infringing portion of the Service to avoid infringement without reducing the Service’s overall functionality or (c) terminate Customer’s access to the infringing portion of the Service and refund to Customer any pre-paid, unused fees for the terminated portion of the applicable Subscription Term. FingerprintJS’s obligations in this Section 10 do not apply to the following “Customer-Controlled Matters” (i) to infringement resulting from Customer’s modification of the Agent or Mobile SDKs or use of the Service in combination with items not provided by FingerprintJS, (ii) to infringement resulting from use of a non-supported version of the Agent, Mobile SDKs or Service, (iii) to infringement resulting from unauthorized use of the Service, (iv) FingerprintJS’ compliance with any designs, requirements or specifications required or otherwise provided by Customer, or (v) if Customer settles or makes any admissions about a claim without FingerprintJS’s prior written consent. This Section 10 sets out Customer’s exclusive remedy and FingerprintJS’s entire liability regarding infringement of third-party intellectual property rights.

### 10.ii Customer Indemnity

At FingerprintJS’s request, Customer will defend FingerprintJS and its affiliates from and against any third-party claim based upon or arising from Visitor Data or FingerprintJS’s collection, storage, or processing thereof in compliance with this Agreement, or any Customer-Controlled Matter, and, regardless of whether FingerprintJS requests Customer to defend against such a claim, will indemnify FingerprintJS and its affiliates against any damages or costs awarded against FingerprintJS or its affiliates (including reasonable attorneys’ fees) or agreed in settlement by Customer resulting from the claim.

### 10.iii Indemnity Procedures

The party seeking defense and indemnification hereunder (the “**Indemnified Party**”) must provide the party from whom indemnification is sought (the “**Indemnifying Party**”): (a) prompt written notice of any claim for which indemnification is sought (provided that a failure to provide such notice will not relieve the Indemnifying Party of its obligations under this Section 10 except to the extent material prejudice results from such failure); (b) all reasonable cooperation, at the Indemnifying Party’s request and expense, in the defense and settlement of the claim; and (c) sole control of the defense and settlement of the claim (provided that (i) where Customer is the Indemnifying Party, such control only accrues to the extent FingerprintJS requests Customer’s defense of the claim and (ii) the Indemnifying Party may not agree to any settlement that places any obligation on the Indemnified Party without the Indemnified Party’s written consent, not to be unreasonably withheld, conditioned, or delayed).

## 11. Confidentiality

### 11.i Definition

“**Confidential Information**” means information disclosed under this Agreement that is designated by the disclosing party as proprietary or confidential or that should be reasonably understood to be proprietary or confidential due to its nature and the circumstances of its disclosure. FingerprintJS’s Confidential Information includes any technical or performance information about, and all nonpublic aspects of, the Service. Customer acknowledges that Fraud Identification Data maintained by FingerprintJS as part of the DRN does not constitute Customer’s Confidential Information.

### 11.ii Obligations

As receiving party, each party will (a) hold in confidence and not disclose Confidential Information to third parties except as permitted in this Agreement, and (b) only use Confidential Information to fulfill its obligations and exercise its rights in this Agreement. The receiving party may disclose Confidential Information to its employees, agents, contractors and other representatives having a legitimate need to know (including, for FingerprintJS, the subcontractors referenced in Section 13.ix), provided it remains responsible for their compliance with this Section 11 and they are bound to confidentiality obligations no less protective than this Section 11.

### 11.iii Exclusions

These confidentiality obligations do not apply to information that the receiving party can document (a) is or becomes public knowledge through no fault of the receiving party, (b) it rightfully knew or possessed prior to receipt under this Agreement, (c) it rightfully received from a third party without breach of confidentiality obligations or (d) it independently developed without using the disclosing party’s Confidential Information. The receiving party may disclose Confidential Information if required by Applicable Laws, subpoena or court order, provided (if permitted by Applicable Laws) it notifies the disclosing party in advance and cooperates in any effort to obtain confidential treatment.

### 11.iv Remedies

Unauthorized use or disclosure of Confidential Information may cause substantial harm for which damages alone are an insufficient remedy. Each party may seek appropriate equitable relief, in addition to other available remedies, for breach or threatened breach of this Section 11.

## 12. Publicity

FingerprintJS may include Customer and its trademarks in FingerprintJS’s customer lists and promotional materials but will cease this use at Customer’s written request.

## 13. General Terms

### 13.i Assignment

Neither party may assign this Agreement without the prior written consent of the other party, except that either party may assign this Agreement in connection with a merger, reorganization, acquisition or other transfer of all or substantially all its assets or voting securities. Any non-permitted assignment is void. This Agreement will bind and inure to the benefit of each party’s permitted successors and assigns.

### 13.ii Governing Law, Jurisdiction and Venue

This Agreement is governed by the laws of the State of Delaware and the United States without regard to conflicts of laws provisions and without regard to the United Nations Convention on the International Sale of Goods. The jurisdiction and venue for actions related to this Agreement will be the state and United States federal courts located in New Castle County, Delaware and both parties submit to the personal jurisdiction of those courts.

### 13.iii Notices

Except as set out in this Agreement, notices under this Agreement must be in writing to the addresses on the first page. Either party may update its address with notice to the other party. FingerprintJS may also send operational notices to Customer by email or through the Service.

### 13.iv Entire Agreement

This Agreement is the parties’ entire agreement regarding its subject matter and supersedes any prior or contemporaneous agreements regarding its subject matter. In this Agreement, headings are for convenience only and “including” and similar terms are to be construed without limitation. The terms in any Customer purchase order or business form will not amend or modify this Agreement and are expressly rejected by FingerprintJS; any of these Customer documents are for administrative purposes only and have no legal effect.

### 13.v Amendments

FingerprintJS may, in its sole discretion and from time to time, modify this Agreement by posting a revised version of this Agreement on its website. Customer is responsible for regularly reviewing this Agreement. CONTINUED USE OF THE SERVICE AFTER ANY SUCH CHANGES SHALL CONSTITUTE CUSTOMER’S AGREEMENT TO SUCH CHANGES. If Customer does not agree to the revised Agreement, then Customer may not use or continue to use the Service. Changes will become effective no sooner than seven (7) days after they are posted; provided that changes addressing new functions or changes made for legal reasons will be effective immediately.

### 13.vi Waivers and Severability

Waivers must be signed by the waiving party’s authorized representative and cannot be implied from conduct. If any provision of this Agreement is held invalid, illegal or unenforceable, it will be limited to the minimum extent necessary so the rest of this Agreement remains in effect.

### 13.vii Audit Rights

Upon FingerprintJS’s written request, Customer shall certify in a signed writing that Customer’s use of the Service is in full compliance with the terms of this Agreement.

### 13.viii Force Majeure

Neither party is liable for any delay or failure to perform any obligation under this Agreement (except for a failure to pay fees) due to events beyond its reasonable control, such as a strike, blockade, war, act of terrorism, riot, internet or utility failures, refusal of government license or natural disaster.

### 13.ix Subcontractors

FingerprintJS may use subcontractors and permit them to exercise FingerprintJS’s rights, but FingerprintJS remains responsible for their compliance with this Agreement and for its overall performance under this Agreement.

### 13.x Independent Contractors

The parties are independent contractors, not agents, partners or joint venturers.

### 13.xi Open Source

Certain aspects of the Service may contain or be provided with third-party components subject to the terms and conditions of “open source” software licenses (“**Third-Party Open Source**”). Third-Party Open Source may be identified in the Service (or a portion thereof), the Documentation, or FingerprintJS shall provide a list of the Third-Party Open Source to Customer upon Customer’s written request. To the extent required by the license that accompanies the Third-Party Open Source, the terms of such license will apply in lieu of the terms of this Agreement with respect to such Third-Party Open Source, including, without limitation, any provisions governing access to source code, modification, or reverse engineering. For clarity, Third-Party Open Source does not include any open source software created by FingerprintJS.

## 14. Definitions

“**Agent**” means the FingerprintJS JavaScript agent and any related code that the Customer installs on the Customer Website in connection with its use of the Service.

“**Applicable Laws**” means all relevant local, state, federal and international laws, regulations and conventions, including those related to data privacy and data transfer, international communications and export of technical data or Personal Information.

“**Browser**” means a particular software application designed to allow interactive access to the World Wide Web such as, by way of example and without limitation, Google Chrome, Firefox, Apple Safari, and Microsoft Edge.

“**CCPA**” means the California Consumer Privacy Act of 2018, Cal. Civ. Code § 1798.100 et seq., as amended, including its implementing regulations and the California Privacy Rights Act of 2020.

“**Credentials**” means user IDs, passwords, accounts, license keys or other Service access mechanisms provided by FingerprintJS.

“**Customer Website**” means the website of Customer on which the Agent is installed.  **“Dashboard”** means the hosted user interface made available by FingerprintJS at [https://dashboard.fingerprint.com](https://dashboard.fingerprint.com/) through which Customer can access certain information in connection with the Service.

“**Device Reputation Network**” or

“**DRN**” means the database maintained by FingerprintJS containing, in relation to each device to which Fraud Identification Data relates, aggregated Fraud Identification Data submitted by customers of FingerprintJS.

"**Documentation**" means the documentation made available to Customer by FingerprintJS for use with the Service at [https://dev.fingerprint.com/docs](https://dev.fingerprint.com/docs) (as modified from time to time).

"**European Data Privacy Legislation**" means, as applicable: (i) Regulation (EU) 2016/679; (ii) the "UK GDPR" as defined in The Data Protection, Privacy and Electronic Communications (Amendment Etc.) (EU Exit) Regulations 2019; and (iii) the Swiss Federal Act on Data Protection of 25 September 2020 and the Swiss Data Protection Ordinance of 31 August 2022, and any new or revised version of these laws that may enter into force for time to time.

“**Fraud Identification Data**” means information regarding devices associated with successful detections of fraud.

“**Mobile SDKs**” means the FingerprintJS object code or machine code libraries or software development kits in compiled, intermediate language, or source code form and any related code that the Customer adds to their mobile device applications in connection with its use of the Service.

“**Personal Information**” means information relating to identified or identifiable natural persons.

“**Privacy Policy**” means the FingerprintJS Privacy Policy, the current version of which is available at [https://dev.fingerprint.com/docs/privacy-policy](https://dev.fingerprint.com/docs/privacy-policy) (as modified from time to time).

“**Service**” means FingerprintJS’s proprietary fingerprinting-as-a-service offering, FingerprintJS. The Service includes the Dashboard, the Agent, the server-side software that analyzes Visitor Data, and, where the Customer elects to use such features of the Service using the functionalities on the Dashboard, either or both of the following: (i) additional model-driven fraud prediction and detection services; and (ii) access to the DRN.

“**Unique Browser Instance**” means a single instance of a single Browser on a single device initiated by a visitor to the Customer Website in an individual calendar month. \[1]

“**Usage Data**” means technical, log, usage and other data related to Customer’s (or its authorized users’) general use of the Service.

“**US Data Protection Laws**” means all applicable federal and state laws rules, regulations, and governmental requirements relating to data protection, the processing of Personal Information, privacy and/or data protection in force from time to time in the United States, including (without limitation) the CCPA.

“**User**” means any employee or contractor of Customer that Customer allows to use the Service on its behalf.

“**Visitor Data**” means the Customer Website session data collected in connection with the Service and any additional data provided or made available to FingerprintJS in relation to the Customer Website session, including any Fraud Identification Data provided by the Customer.

\[1] By way of example, a visitor who accesses the Customer Website via Google Chrome on a given device in a given calendar month counts as one (1) Unique Browser Instance. If the same visitor accesses the Customer Website via Firefox or a different device in the same calendar month, that counts as two (2) Unique Browser Instances (one (1) for the Google Chrome instance on the initial device and one (1) for the Firefox instance on the same device or the Google Chrome instance on a different device, respectively) in the applicable calendar month.

***

What’s Next

* [Start your free subscription now](https://dashboard.fingerprintjs.com/signup/)


# User preferences
Source: https://docs.fingerprint.com/docs/user-preferences



You can access your own profile to manage personal settings by visiting **Settings** >[**My Profile**](https://dashboard.fingerprint.com/profile/settings).

## Personal Information

* **Profile details**: Manage your personal information.
* **Time zone**: This setting determines the time zone in which you will view all statistics and analytics in the dashboard.

## Email Notifications

Manage your personal email settings, including whether you will receive:

* **Summary emails**: Subscribe to receive daily or weekly summary emails.
* **Workspace alerts**: Including billing events, alerts about outdated libraries, and other relevant notifications.


# Workspaces & environments
Source: https://docs.fingerprint.com/docs/workspaces-environments



Workspaces and environments let you organize projects and separate traffic contexts.

## Workspaces

A **Workspace** is a dedicated project space (tied to your account) where you manage and configure Fingerprint for a given application or business unit. Each workspace has its own data and settings – for example, you might have one workspace for your primary business and another for your secondary business managed by a dedicated team.

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 53 32@2x" />
</Frame>

To switch between different workspaces, use the **workspace selector (1)** on the top of the sidebar.

To manage your workspaces, go to **Settings** > [**Workspaces**](https://dashboard.fingerprint.com/settings/workspaces). Your plan is tied to your workspace. If you’re on the Enterprise plan, reach out to [Customer Support](https://fingerprint.com/support/) for additional workspaces.

## Environments

A workspace can contain multiple **Environments**, which are useful for isolating production vs. development or staging setups. For instance, you might have “Prod” and “Dev” environments under the same workspace, or different domains under separate environments. Learn more about [multiple environments](/docs/multiple-environments).

<Frame>
  <img alt="Clean Shot 2026 05 28 At 13 54 12@2x" />
</Frame>

To see environment specific data and resources, look for **environment filter options** on the pages you’re working with.

To manage your environments, go to **Settings** > [**Environments**](https://dashboard.fingerprint.com/environments). Each workspace starts with a default environment which cannot be removed, but you can add or delete others as needed.

You can optionally set a **API usage threshold** for each environment if you want to be notified about excess usage. If you're an Enterprise customer, you can also set a limit to **restrict API usage** for each environment.

## Comparison

If you manage multiple websites, applications, or business units, the best option will depend on your specific use case and how separate you need them to be. Both workspaces and environments have advantages and trade-offs, which you can compare below.

|                    | Workspaces                                                                                                         | Environments                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| **Regions**        | Each workspace can be created on a different region.                                                               | They belong to a single workspace, so they are always in the same region.                    |
| **Identification** | Identification is completely separate, so same device will get a different visitor ID on different workspaces.     | Identification is shared, so same device will get the same visitor ID on every environment.  |
| **Observability**  | Each workspace is separate so there's no high-level observability and shared statistics for multiple workspaces.   | Full support for observability and statistics for multiple environments.                     |
| **Management**     | Created and managed manually.                                                                                      | Can be created and managed programmatically via [Management API](/reference/management-api). |
| **Team access**    | Team members can be given access to specific workspaces with [granular user permissions](/docs/roles-permissions). | When they have access to workspace, team members have full access to all environments.       |


# Android SDK
Source: https://docs.fingerprint.com/docs/changelog-android-sdk

This changelog lists all additions and updates to the Fingerprint Android SDK, in chronological order.

<Update label="September 2026">
  ## v4.1.0

  ### What's new

  * Bug fixes and internal improvements.
  * Reduced SDK size.

  Android SDK v4.1.0 size info: 3.51MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**2.3.20** (`org.jetbrains.kotlin:kotlin-*:2.3.20`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="August 2026">
  ## v4.0.0

  <Warning>
    This version includes breaking changes and requires you to manually migrate. For more details on upgrading to Android SDK v4.0.0, refer to the [Migrating the Fingerprint Android SDK from v2 to v4](https://docs.fingerprint.com/reference/migrating-android-sdk-from-v2-to-v4) page.
  </Warning>

  ### What's new

  * `FingerprintJSFactory` and the `FingerprintJS` interface are renamed to `FingerprintFactory` and `Fingerprint`, dropping the legacy "JS" naming.
  * The response object is renamed from `FingerprintJSProResponse` to `FingerprintResponse`, and several nested/legacy fields (`confidenceScore`, `ipLocation`, `firstSeenAt`, and similar) have been removed in favor of a flat response shape, along with their supporting types (`ConfidenceScore`, `Timestamp`, and `IpLocation`). Check the [migration guide](https://docs.fingerprint.com/reference/migrating-android-sdk-from-v2-to-v4) to see the full list.
  * `requestId` is renamed to `eventId` across responses, errors, and exceptions.
  * The `extendedResponseFormat` configuration flag has been removed as v4 always returns the flat format.
  * Several error classes have been removed or replaced, and new error classes have been added to reflect new server-side error codes. Check the [migration guide](https://docs.fingerprint.com/reference/migrating-android-sdk-from-v2-to-v4) for more details about error classes.
  * Kotlin upgraded from v1.9.25 to v2.3.20.
  * Added in-code documentation for better DX: API documentation is published as a Javadoc JAR alongside the Maven artifacts, so it's available directly in your IDE when you add the dependency.
  * Bug fixes and stability improvements for low-end Android devices.
  * Reduced SDK size.

  Android SDK v4.0.0 size info: 3.94MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**2.3.20** (`org.jetbrains.kotlin:kotlin-*:2.3.20`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="August 2026">
  ## v2.17.1

  ### What's new

  * Started collecting additional signals to support upcoming improvements to Android identification.

  Android SDK v2.17.1 size info: 4.23MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="July 2026">
  ## v2.17.0

  ### What's new

  * Added internal improvements to enhance fraud detection capabilities. These updates lay the groundwork for upcoming backend enhancements.
  * Reduced false positives in emulator and rooted device detection.
  * Internal bug fixes and security updates.

  Android SDK v2.17.0 size info: 4.13MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="June 2026">
  ## v2.16.0

  ### What's new

  * Added internal improvements to support enhanced detection logic and upcoming backend updates.

  Android SDK v2.16.0 size info: 4.12MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="April 2026">
  ## v2.15.0

  ### What's new

  * Updated client-level logic to improve the accuracy and reliability of [rooted device detection](https://docs.fingerprint.com/docs/smart-signals-reference#rooted-device-detection).
  * Expanded the range of device-level signals collected for deeper device integrity insights.
  * Internal bug fixes and performance improvements.

  Android SDK v2.15.0 size info: 3.53MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="March 2026">
  ## v2.14.0

  ### What's new

  * Reduced Android SDK AAR size by 1.5MB (from 4.7MB to 3.2MB)
  * Fixed crashes during app initialization on low-end devices running Android 12, 13, and 15, including devices with limited available RAM.
  * Added [coroutine support](/docs/android-quickstart#4-initialize-the-sdk) for cleaner, more idiomatic integration in Kotlin-based Android projects.
  * Internal bug fixes and performance improvements.

  Android SDK v2.14.0 size info: 3.2MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="February 2026">
  ## v2.13.1

  ### What's new

  * Added internal improvements to support enhanced detection logic and upcoming backend updates.
  * Security updates and minor bug fixes.

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="December 2025">
  ## v2.12.0

  ### What's new

  * Added internal improvements to enhance fraud detection capabilities. These updates lay the groundwork for upcoming backend enhancements.
  * Improved [cloned app detection](/docs/smart-signals-reference#cloned-app-detection) on Android.

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 36 (`targetSdk = 36`)
  * **Compiled using** API Level 36 (`compileSdk = 36`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="October 2025">
  ## v2.11.0

  ### What's new

  **Recommendation**: We strongly encourage upgrading to the version **2.11.0** to benefit from improved security and stronger protection against tampering and reverse-engineering attempts.

  * Implemented additional security measures to protect Android SDK requests from manipulation, tampering, and reverse-engineering attempts.
  * Deprecated support for Android 5.x.
  * Improved [rooted device detection](/docs/smart-signals-reference#rooted-device-detection) on Android.
  * Improved [emulator detection](/docs/smart-signals-reference#android-emulator-detection) logic on Android.
  * The total SDK size increased from 800kB to 4.5MB

  ### Compatibility

  * **Requires** Android 6.0+ ([API Level 23 or higher](https://developer.android.com/about/versions/marshmallow))
  * **Tested with** API Level 35 (`targetSdk = 35`)
  * **Compiled using** API Level 35 (`compileSdk = 35`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.13.0** (`com.android.tools.build:gradle:8.13.0`)
  * Gradle: v**8.13**
  * jvmTarget : **Java 11**
</Update>

<Update label="September 2025">
  ## v2.10.0

  ### What's new

  * Introduced a new proximity detection location-based signal for mobile devices. Instead of representing a unique device, the new proximity ID corresponds to a fixed geographical zone within which the device is observed. This additional layer of context makes it possible to identify groups of devices in the same physical area or a single device that may have changed its identity but remained in the same location. See [Proximity detection for Android devices](/docs/smart-signals-reference#proximity-detection) reference for more info.
    * The Android SDK will only collect location data if the new [`allowUseOfLocationData`](/docs/android-sdk#allowuseoflocationdata) option is set to `true`.
    * It's possible to configure the location retrieval timeout by setting the new [`locationTimeoutMillis`](/docs/android-sdk#locationtimeoutmillis) option to a desired value. By default, it's set to 5 seconds. Refer to [Using Location Data for Proximity Detection](/docs/android-sdk#using-location-data-for-proximity-detection) page for configuration details.
  * Enhanced the detection logic to more accurately identify true [factory resets](/docs/smart-signals-reference#factory-reset-detection) on Android devices. This update reduces false positives and improves signal reliability for fraud prevention workflows.

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 35 (`targetSdk = 35`)
  * **Compiled using** API Level 35 (`compileSdk = 35`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.7.3** (`com.android.tools.build:gradle:8.7.3`)
  * Gradle: v**8.10.2**
  * jvmTarget : **Java 8**
</Update>

<Update label="August 2025">
  ## v2.9.0

  ### What's new

  * Introduced internal architecture updates and performance improvements to support upcoming capabilities.
  * Addressed minor data collection issues to improve SDK reliability.
  * Added new error codes
    * `InvalidProxyIntegrationSecret`
    * `InvalidProxyIntegrationHeaders`
    * `ProxyIntegrationSecretEnvironmentMismatch`

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 35 (`targetSdk = 35`)
  * **Compiled using** API Level 35 (`compileSdk = 35`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="February 2025">
  ## v2.8.0

  ### What's new

  * Introduced the ability to detect if requests from the app were subject to MitM attacks. See [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection) to learn more.
  * Added support for [Open Client Response](/docs/v3/open-client-response).
  * Minor enhancements to identification and detection of Smart Signals.

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 35 (`targetSdk = 35`)
  * **Compiled using** API Level 35 (`compileSdk = 35`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.7.3** (`com.android.tools.build:gradle:8.7.3`)
  * Gradle: v**8.10.2**
  * jvmTarget : **Java 8**
</Update>

<Update label="October 2024">
  ## v2.7.0

  ### What's new

  * Added support for [Sealed Client Results](/docs/android-sdk#reading-the-response).

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 34 (`targetSdk = 34`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**

  ## v2.6.0

  ### What's new

  * Introduced the ability to configure the timeout interval for the client session. To learn more, see [Specifying a custom timeout](/docs/android-sdk#specifying-a-custom-timeout).
  * Added internal improvements to enhance fraud detection capabilities. These updates lay the groundwork for upcoming backend enhancements.

  ### What's changed

  * Information about Installed Applications is no longer collected and used.
  * Removed dependency `com.github.fingerprintjs:fingerprint-android`

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 34 (`targetSdk = 34`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.25** (`org.jetbrains.kotlin:kotlin-*:1.9.25`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="August 2024">
  ## v2.5.0

  ### What's new

  * Introduced the ability to redirect failed requests to alternate endpoints. The list `Configuration.fallbackEndpointUrls` can be used to specify one or more alternate endpoints. For a complete example, see [Getting a visitorId](/docs/android-sdk#getting-a-visitorid).

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 34 (`targetSdk = 34`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.10** (`org.jetbrains.kotlin:kotlin-*:1.9.10`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="January 2024">
  ## v2.4.0

  ### What's new

  * Introduced a new child class, `PackageNotAuthorized` to the sealed class, `Error`. This error is returned when an unauthorized app makes identification requests using a stolen API key. See [Request filtering for mobile apps](/docs/mobile-app-filtering) for more information.
  * Enhanced our [VPN Detection Smart Signal](/docs/smart-signals-reference#vpn-detection-for-mobile-devices) with a new data point, [`originCountry`](/docs/smart-signals-reference#vpn_origin_country) that indicates the country in which the mobile device is currently located at.

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 34 (`targetSdk = 34`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.10** (`org.jetbrains.kotlin:kotlin-*:1.9.10`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="October 2023">
  ## v2.3.4

  ### What's new

  * Introduced the ability to detect if the device location has been spoofed. To learn more, see [Geolocation Spoofing Detection](/docs/smart-signals-reference#geolocation-spoofing-detection).
  * Added runtime dependency `com.google.android.gms:play-services-location`

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.10** (`org.jetbrains.kotlin:kotlin-*:1.9.10`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**

  ## v2.3.3

  ### What's new

  * Introduced the ability to detect if a device is using VPN. To learn more, see [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices).
  * Introduced the ability to detect if an app using this SDK is being instrumented by Frida. To learn more, see [Frida Detection](/docs/smart-signals-reference#frida-detection).
  * Added runtime dependency `androidx.core:core`

  ### What's changed

  * Upgraded dependency `com.github.fingerprintjs:fingerprint-android` to v**2.1.0**

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 34 (`compileSdk = 34`)

  ### Build Info

  * Kotlin: v**1.9.10** (`org.jetbrains.kotlin:kotlin-*:1.9.10`)
  * Android Gradle Plugin: v**8.1.1** (`com.android.tools.build:gradle:8.1.1`)
  * Gradle: v**8.3.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="July 2023">
  ## v2.3.2

  ### What's changed

  * Upgraded dependency `com.github.fingerprintjs:fingerprint-android` to v**2.0.2**

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 33 (`compileSdk = 33`)

  ### Build Info

  * Kotlin: v**1.8.21** (`org.jetbrains.kotlin:kotlin-*:1.8.21`)
  * Android Gradle Plugin: v**7.4.2** (`com.android.tools.build:gradle:7.4.2`)
  * Gradle: v**7.5.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="April 2023">
  ## v2.3.1

  ### What's changed

  * The following dependencies have now been declared within `com.fingerprint.android:pro`. They need not anymore be individually included in build.gradle.
    * `org.jetbrains.kotlin:kotlin-stdlib`
    * `com.github.fingerprintjs:fingerprint-android`
  * Reduced the size of the payload that is transmitted from the device to Fingerprint’s servers.

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 33 (`compileSdk = 33`)

  ### Build Info

  * Kotlin: v**1.8.0** (`org.jetbrains.kotlin:kotlin-*:1.8.0`)
  * Android Gradle Plugin: v**7.4.2** (`com.android.tools.build:gradle:7.4.2`)
  * Gradle: v**7.5.0**
  * jvmTarget : **Java 8**
</Update>

<Update label="March 2023">
  ## v2.3.0

  ### What's changed

  * Introduced the ability to detect if the requests to the app are being made from
    * An emulated device. To learn more, see [Android Emulator Detection](/docs/smart-signals-reference#android-emulator-detection).
    * A rooted device. To learn more, see [Rooted Device Detection](/docs/smart-signals-reference#rooted-device-detection).
    * A factory-reset device. To learn more, see [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection).
  * Introduced the ability to detect if a cloned version of the app is being used to make requests to your servers. To learn more, see [Cloned App Detection](/docs/smart-signals-reference#cloned-app-detection).

  ### Compatibility

  * **Requires** Android 5.0+ ([API Level 21 or higher](https://developer.android.com/about/versions/lollipop))
  * **Tested with** API Level 33 (`targetSdk = 33`)
  * **Compiled using** API Level 33 (`compileSdk = 33`)

  ### Build Info

  * Kotlin: v**1.7.0** (`org.jetbrains.kotlin:kotlin-*:1.7.0`)
  * Android Gradle Plugin: v**7.2.2** (`com.android.tools.build:gradle:7.2.2`)
  * Gradle: v**7.4.2**
  * jvmTarget : **Java 8**
</Update>


# Dashboard
Source: https://docs.fingerprint.com/docs/changelog-dashboard

This changelog lists all additions and updates to the Fingerprint Dashboard, in chronological order.

<Update label="September 2026">
  ## Breakdown charts on the Overview page

  The timeline chart on the Overview page has a new **Breakdowns** group in the chart selector. A breakdown plots the composition of your identification events over time, so you can see a trend shift as it happens instead of comparing two point-in-time distribution lists.

  Six breakdowns are available: **Browsers**, **Client types**, **Client versions**, **Countries**, **Operating systems**, and **URLs**. Each one renders as a stacked chart of the top 5 entities for the selected period, with everything else grouped into **Other**, and can be switched between absolute counts and percentage share, or between a chart and a table.

  Breakdowns are available in all workspaces.

  See [Analytics](/docs/analytics).
</Update>

<Update label="September 2026">
  ## Bots & AI agents replaces the Bot Detection page

  The Dashboard sidebar has a new **Bots & AI agents** section, with an **Overview** page for bot traffic analytics and an **Events** page for individual automation events. It replaces the Bot Detection page under Smart Signals, and existing links to that page redirect to the new Overview.

  The Overview page reports your traffic against the full bot taxonomy: metrics for total bots, AI traffic, and trusted, spoofed, and unknown identities; six timeline charts; top bot names, providers, and categories; and an identity breakdown of every category against its identity results. Switch between the **Automation Intelligence API** and **JS Agent** tabs to change the data source behind the page.

  The Overview page is available to all workspaces while the [Automation Intelligence API](/reference/automation-intelligence-api) is in Public Preview. The **JS Agent** tab requires the Bot Detection Smart Signal in your plan.

  See [Bots and AI agents](/docs/dashboard-bots-ai-agents) for the full guide.
</Update>

<Update label="September 2026">
  ## One-click subdomain setup with Domain Connect

  You can now set up a custom subdomain without editing any DNS records. The Dashboard detects whether your domain's DNS provider supports Domain Connect and shows a one-click setup card. You authorize the change with your provider, records are applied instantly, and verification and certificate issuance continue automatically.

  * Cloudflare is the first supported provider. Fingerprint is onboarding others next.
  * Records are applied as **DNS only**, which avoids Cloudflare proxying misconfiguration.
  * Domains on providers without Domain Connect support keep the manual setup flow.

  See [Custom subdomain setup](/docs/custom-subdomain-setup).
</Update>

<Update label="July 2026">
  ## Subdomain setup improvements

  Custom subdomain setup now fits into a single visit instead of several. On **Settings** > **Subdomains**:

  * All DNS records appear upfront. The page shows the `CNAME` verification record and both `A` routing records together, rather than hiding the `A` records until the certificate is issued.
  * **Copy** and **Download** controls grab every record in one action, including a pasteable zone-file format for providers that support bulk import, such as Cloudflare and Route 53. Per-record copy buttons remain.
  * Subdomain status updates live while you are on the page, with a progress indicator during verification and a success state once the subdomain is **Active**.
  * **Check DNS records** triggers an on-demand DNS check instead of waiting for the background cycle.

  See [Custom subdomain setup](/docs/custom-subdomain-setup).
</Update>

<Update label="June 2026">
  ## Health page restructure

  The Health page is now a high-level triage view that links out to entity-specific pages for detail, instead of a single detail-heavy surface. It features three widgets:

  * **Throttled requests**: the number of requests throttled in the current period, and the API keys responsible.
  * **Webhooks**: your webhook failure rate, and the webhooks with the most recent delivery failures.
  * **SDK versions**: how many updates are available across your integrations.

  Below the widgets, the charts are merged into one view with a selector for **API Latency**, **API Errors**, and **Webhook Failed Calls**.

  SDK health moved to **Libraries & Integrations**, where each active library shows recent usage and current version information. Version tracking is now origin-first: you see each domain or app, the URLs within it, and the SDK versions found there. The previous version-first view could not distinguish an origin that still needs updating from stale cached clients still sending old requests.

  See [Health](/docs/health).
</Update>

<Update label="June 2026">
  ## Top IP addresses and Top visitor IDs distributions

  The Overview page has two additional distribution lists: **IP address** and **Visitor ID**. Both rank items by the number of identification events in the selected time range, which helps you spot a small number of visitors generating a disproportionate share of your traffic.

  See [Overview page](/docs/analytics#overview-page).
</Update>

<Update label="May 2026">
  ## Suspect Score weights by confidence level

  You can now set Suspect Score weights according to how confident a detection is, instead of applying one weight per Smart Signal regardless of confidence.

  * For **VPN detection**, apply weights by method (public service, relay, timezone mismatch, and others) or by confidence (`low`, `medium`, `high`).
  * For **Residential proxy**, apply a flat weight or weights by confidence (`low`, `medium`, `high`).

  See [Configuring weights by confidence level](/docs/suspect-score#configuring-weights-by-confidence-level).
</Update>

<Update label="May 2026">
  ## Stripe Checkout and Stripe Customer Portal

  Billing flows now use Stripe's hosted Checkout page instead of an in-app card form, and payment methods are managed in the Stripe Customer Portal instead of a custom Dashboard screen.

  * Apple Pay, Google Pay, Cash App Pay, and Link, including Instant Bank Payments, are available alongside cards for a first paid workspace, an upgrade, or a reactivation.
  * Invoices are visible in both the Dashboard and the Stripe Portal.
  * Card data is collected on Stripe's domain, so Fingerprint never handles raw card details.

  Existing customers keep the previous flow. See [Payment methods](/docs/billing#payment-methods).
</Update>

<Update label="April 2026">
  ## Proximity ID in event search, details, and CSV export

  Proximity information for iOS events is now visible throughout the Identification pages.

  * The Event Details page shows the proximity ID in the device and identification section, and in the quick reference sidebar.
  * The Identification page has a proximity ID filter, and you can add proximity ID as a column from the column display dropdown.
  * Proximity data is included in the CSV export for both Server API v3 and v4.

  See [Proximity Detection](/docs/smart-signals-reference#proximity-detection).
</Update>

<Update label="April 2026">
  ## Server API v4 by default

  The Dashboard now presents Server API v4, which is the recommended and actively developed version, rather than v3.

  * Smart Signals snippets on the Event Details page use the Server API v4 format.
  * The event JSON viewer defaults to v4.
  * The CSV export dialog has a v3 and v4 selector that changes the column names in the exported file.

  See [Migrating from Server API v3 to v4](/reference/migrating-from-server-api-v3-to-v4).
</Update>

<Update label="March 2026">
  ## Workspace reactivation

  Reactivating a canceled workspace no longer requires contacting support.

  * Canceled workspaces show a reactivation banner in the sidebar with a link to choose a plan.
  * The Plans page offers **Reactivate free** and **Reactivate** options based on your eligibility.

  See [Fingerprint Platform Billing](/docs/billing).
</Update>


# iOS SDK
Source: https://docs.fingerprint.com/docs/changelog-ios-sdk

This changelog lists all additions and updates to the Fingerprint iOS SDK, in chronological order.

<Update label="August 2026">
  ## v4.0.0

  <Warning>
    This version includes breaking changes and requires you to manually migrate. For more details on upgrading to iOS SDK v4.0.0, refer to the [Migrating the Fingerprint iOS SDK from v2 to v4](https://docs.fingerprint.com/reference/migrating-ios-sdk-from-v2-to-v4) page.
  </Warning>

  ### What's new

  * The library and module were renamed from `FingerprintPro` to `Fingerprint`. Update your imports from `import FingerprintPro` to `import Fingerprint`.
  * The `FingerprintProFactory` type was renamed to `FingerprintFactory`. Update calls such as `FingerprintProFactory.getInstance(...)` to `FingerprintFactory.getInstance(...)`.
  * The SDK is now distributed from a new Swift Package Manager repository, `https://github.com/fingerprintjs/fingerprint-ios`. Because this is a new package rather than a rename, you must remove the old package and add the new one.
  * The CocoaPods pod was renamed from `FingerprintPro` to `Fingerprint-iOS`. CocoaPods is still supported for now but is deprecated.
  * The `FPJSError` error type was renamed to `FPError`.
  * The response object `FingerprintResponse` changed from a deeply nested shape to a flat one. Several legacy fields (`confidence`, `ipLocation`, `firstSeenAt`, and similar) have been removed, along with their supporting types (`IPLocation`, `IPLocationSubdivision`, `IPGeoInfo`, and `SeenAt`).
  * `requestId` is renamed to `eventId` on the response.
  * A new `suspectScore` field of type `Int?` is added to the response.
  * The `extendedResponseFormat` configuration flag has been removed as v4 always returns the flat format.
  * The `APIError.Code` enum has been revised to reflect new server-side error codes.
  * Swift upgraded from 5.9 to 6.
  * Dropped support for iOS 13.
  * Reduced latency.
  * Reduced SDK size.
  * Added DocC documentation to the iOS SDK. It is automatically bundled with the package, so it appears in Xcode's Developer Documentation once the dependency is added, and it is also published online via GitHub Pages.

  iOS SDK v4.0.0 size info: 2.8MB

  ### Requirements

  #### IDE

  * Minimum Xcode is now [16.0](https://developer.apple.com/documentation/xcode-release-notes/xcode-16-release-notes). Support for [Xcode 15](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes) has been dropped. See [App Store submission requirements](https://developer.apple.com/app-store/submitting/) for more information.
  * The iOS SDK is now built in the Swift 6 language mode. This does not require your app to adopt the Swift 6 language mode - `Fingerprint` remains compatible with projects using the Swift 5 language mode.

  #### Minimum supported versions

  * [**iOS 14**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-14-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="August 2026">
  ## v2.17.2

  ### What's new

  * Refined signal collection logic on devices located in mainland China, improving App Store review compliance in that region.
  * Optimized signal collection to reduce latency during app launch.

  iOS SDK v2.17.2 size info: 3.1MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="July 2026">
  ## v2.17.1

  ### What's new

  * Added additional signal data to improve the accuracy of Factory Reset detection on iOS 26.6 and iOS 27.

  iOS SDK v2.17.1 size info: 3.1MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)

  ## v2.17.0

  ### What's new

  * Added internal improvements to enhance fraud detection capabilities. These updates lay the groundwork for upcoming backend enhancements.
  * Internal bug fixes.

  iOS SDK v2.17.0 size info: 3.1MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="June 2026">
  ## v2.16.0

  ### What's new

  * Added internal improvements to support enhanced detection logic and upcoming backend updates.
  * Added support for the iOS device memory attribute as part of the [Raw Device Attributes](https://docs.fingerprint.com/docs/smart-signals-reference#raw-device-attributes) smart signal.

  iOS SDK v2.16.0 size info: 3.0MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="May 2026">
  ## v2.15.1

  ### What's new

  * Fixed a crash occurring when the SDK was initialized with a proxy configuration on devices with an A18 Pro chip or newer.
  * Introduced performance optimizations which resulted in reducing the iOS SDK binary size from 4 MB to 2.9 MB - a 27.5% decrease. This reduces the overall size impact on host apps when building for device.
  * Reduced latency.

  iOS SDK v2.15.1 size info: 2.9MB

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="May 2026">
  ## v2.15.0

  ### What's new

  * Improved [MitM detection](https://docs.fingerprint.com/docs/smart-signals-reference#mitm-attack-detection) reliability on iOS. Certificate chain collection now happens directly from the visitor identification request, eliminating a separate preliminary network request. This resolves false positive MitM detections for users whose network environment (VPNs, corporate proxies) blocked or intercepted the previous preliminary request.
  * Expanded the range of device-level signals collected for deeper device integrity insights.
  * Performance improvements.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="March 2026">
  ## v2.14.0

  ### What's new

  * Expanded signal collection to support upcoming factory reset detection.
  * Improved [jailbroken device detection](https://docs.fingerprint.com/docs/smart-signals-reference#jailbroken-device-detection) and [Frida detection](https://docs.fingerprint.com/docs/smart-signals-reference#frida-detection) logic.
  * Performance improvements and minor bug fixes.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="February 2026">
  ## v2.13.0

  ### What's new

  * Added internal improvements to support enhanced detection logic and upcoming backend updates.
  * Improved data handling logic in virtualized and simulator environments to strengthen privacy and security protections.
  * Improved the underlying logic for [Geolocation spoofing Smart Signal](https://docs.fingerprint.com/docs/smart-signals-reference#geolocation-spoofing-detection)
  * Minor bug fixes.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="December 2025">
  ## v2.12.0

  ### What's new

  * Added internal improvements to enhance fraud detection capabilities.
  * Introduced a new [iOS simulator detection](/docs/smart-signals-reference#ios-simulator-detection) Smart Signal.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="October 2025">
  ## v2.11.0

  ### What's new

  **Recommendation**: We strongly encourage upgrading to the version **2.11.0** to benefit from improved security and stronger protection against tampering and reverse-engineering attempts.

  * Implemented additional security measures to protect iOS SDK requests from manipulation, tampering, and reverse-engineering attempts.
  * Fixed two bugs related to `LocationPermissionHelper`:
    * Resolved an issue with the `locationPermissionHelper(_:shouldShowLocationRationale:)` delegate method being triggered more than once for the same authorization status change, which previously led to duplicate permission dialogs for clients who use `LocationPermissionHelper`.
    * Fixed an issue where calling `LocationPermissionHelper.requestTemporaryPrecisePermission` could cause an infinite loop if an error occurred, such as when the required purpose string for temporary precise location permission was missing from the Info.plist.
  * The total SDK size increased from 1MB to 3.6MB

  Note: Simulators running iOS 15 or lower are no longer supported for testing Fingerprint integrations. If you use simulators to test your Fingerprint integration, please update to iOS 16 or higher.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="September 2025">
  ## v2.10.1

  ### What's new

  * Optimized signal collection to reduce latency during app launch.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)

  ## v2.10.0

  ### What's new

  * Introduced a new proximity detection location-based signal for mobile devices. Instead of representing a unique device, the new proximity ID corresponds to a fixed geographical zone within which the device is observed. This additional layer of context makes it possible to identify groups of devices in the same physical area or a single device that may have changed its identity but remained in the same location. See [Proximity detection for iOS devices](/docs/smart-signals-reference#proximity-detection) reference for more info.
    * Added `allowUseOfLocationData` property to the `Configuration` structure in order to start receiving proximity detection signal. This flag allows the Fingerprint client to access device location data when enabled and the necessary permissions are granted. Default value is `false`. See [using location data for proximity detection](/docs/ios-sdk#using-location-data-for-proximity-detection) for integration details.
    * Added `NSPrivacyCollectedDataTypePreciseLocation` and `NSPrivacyCollectedDataTypeCoarseLocation` to `NSPrivacyCollectedDataTypes` in the iOS SDK’s [Privacy Manifest](/docs/mobile-devices-understanding-privacy-manifest-files#nsprivacycollecteddatatypes), indicating that the SDK may collect both precise and coarse user location data from host apps.
    * Added an optional `LocationPermissionHelper` utility to simplify integration of location permission handling for host apps that do not implement their own flow. This utility provides an easy way to request, observe, and respond to location permission changes using a `LocationPermissionDelegate` callback. See a detailed integration example in the [Handling Location Permissions](/docs/ios-sdk#handling-location-permissions) section.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="August 2025">
  ## v2.9.0

  ### What's new

  * Introduced internal architecture updates and performance improvements to support upcoming capabilities.
  * Added new error code:
    * `ProxyIntegrationSecretEnvironmentMismatch`
  * Addressed minor issues to improve SDK reliability.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="April 2025">
  ## v2.8.2

  ### What's new

  * Introduced the ability to detect if requests from the app were subject to MitM attacks. See [MitM Attack Detection](/docs/smart-signals-reference#mitm-attack-detection) to learn more.
  * Added support for [Open Client Response](/docs/v3/open-client-response).

  ### What's changed

  * The following changes were made to the error handling API. To ensure backward compatibility, the old symbols have been preserved and annotated with the `@available(*, deprecated, renamed: "<new-name>")` attribute.
    * Enum `APIErrorType` has been renamed to `APIError.Code`.
    * Property `APIError.error` has been renamed to `APIError.errorDetails`.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [**iOS 13**](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [**tvOS 15**](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="October 2024">
  ## v2.7.0

  ### What's new

  * Introduced the ability to configure the timeout interval for the client session. To learn more, see [Specifying a custom timeout](/docs/ios-sdk#specifying-a-custom-timeout).
  * Added support for [Sealed Client Results](/docs/ios-sdk#reading-the-response).
  * Extended compatibility for use with projects that have [enabled Swift 6 language mode](https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/featuremigration/).

  ### Bug fixes

  * Fixed a regression introduced in v2.5.0 in which the API errors were incorrectly parsed as `FPJSError.invalidResponseType`. The API errors are now correctly parsed and returned as `FPJSError.apiError`.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="August 2024">
  ## v2.6.0

  ### What’s new

  * Introduced the ability to redirect failed requests to alternate endpoints. The `Region.custom(domain:fallback:)` can be used to specify the `fallback` array of one or more alternate endpoints. For a complete example, see [Getting a visitorId](/docs/ios-sdk#getting-a-visitorid).

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="July 2024">
  ## v2.5.0

  ### What’s new

  * Enhanced our [Jailbroken Device Detection Smart Signal](/docs/smart-signals-reference#jailbroken-device-detection) with the ability to detect rootless jailbreaks.
  * [Factory Reset Smart Signal](/docs/smart-signals-reference#factory-reset-detection) is no longer reported as true for brand-new iOS devices.
  * In accordance with [Apple's third-party SDK requirements](https://developer.apple.com/support/third-party-SDK-requirements/), the XCFramework bundle is now code signed with an Apple Distribution certificate. The dependency signature verification feature, introduced in Xcode 15, allows the XCFramework's code signing identity to be verified, thus enabling SDK consumers to protect their software supply chain integrity.

  ### What's changed

  * Dropped support for Swift 5.7 and 5.8.

  ### Requirements

  #### IDE

  * [Xcode 15.0+](https://developer.apple.com/documentation/xcode-release-notes/xcode-15-release-notes), Swift 5.9. See [App Store submission requirements](https://developer.apple.com/news/?id=fxu2qp7b) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="January 2024">
  ## v2.4.0

  ### What's new

  * Introduced a new `packageNotAuthorized` value to the `APIErrorType` enum. This error is thrown when an unauthorized app makes identification requests using a stolen API key. See [Request filtering for mobile apps](/docs/mobile-app-filtering) for more information.
  * Extended several public APIs (e.g. `FingerprintResponse`, `IPLocation`, etc) with memberwise initializers so that they can be easily stubbed for unit tests.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="December 2023">
  ## v2.3.2

  ### What's new

  * Added `PrivacyInfo.xcprivacy`, the privacy manifest file. See [Understanding privacy manifest files](/docs/mobile-devices-understanding-privacy-manifest-files) for more information.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="October 2023">
  ## v2.3.1

  ### What's new

  * Introduced the ability to detect [Geolocation Spoofing](/docs/smart-signals-reference#geolocation-spoofing-detection).

  ### What's changed

  * Removed the limitation in which the Smart Signals could not be made available in the response of the very first [`/events API`](/reference/server-api-get-event) request.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)

  ## v2.3.0

  ### What's new

  * Introduced the ability to detect if a device is using a VPN. See [VPN Detection](/docs/smart-signals-reference#vpn-detection-for-mobile-devices) for more information.
  * Introduced a new Smart Signal, [Factory Reset Detection](/docs/smart-signals-reference#factory-reset-detection) that provides the timestamp of the most recent factory reset of the device.
  * Added support for Swift 5.9 and Xcode 15.

  ### What's changed

  * Dropped support for iOS 12, tvOS 12, tvOS 13, and tvOS 14.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 13](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-13-release-notes)
  * [tvOS 15](https://developer.apple.com/documentation/tvos-release-notes/tvos-15-release-notes)
</Update>

<Update label="June 2023">
  ## v2.2.0

  ### What's new

  * Introduced the ability to detect
    * If Frida is being used to instrument your app. See [Frida Detection](/docs/smart-signals-reference#frida-detection) for more information.
    * If your app is running on a jailbroken device. See [Jailbroken Device Detection](/docs/smart-signals-reference#jailbroken-device-detection) for more information.
  * Introduced a new field, `visitorFound` in `FingerprintResponse`. This field indicates if a device was already seen by your mobile app.

  ### What's changed

  * Dropped support for Swift 5.5 and Swift 5.6.

  ### Requirements

  #### IDE

  * [Xcode 14.1+](https://developer.apple.com/documentation/xcode-release-notes/xcode-14_1-release-notes), Swift 5.7. See [App Store submission requirements](https://developer.apple.com/news/?id=jd9wcyov#) for more information.

  #### Minimum supported versions

  * [iOS 12](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-12-release-notes)
  * [tvOS 12](https://developer.apple.com/documentation/tvos-release-notes/tvos-12-release-notes)
</Update>


# JavaScript agent
Source: https://docs.fingerprint.com/docs/changelog-javascript-agent

This changelog lists all additions and updates to the Fingerprint documentation, in chronological order.

<Update label="September 2026">
  ## v4.1.5

  * Add [`tags`](/reference/js-agent-get-function#tags) to replace deprecated [`tag`](/reference/js-agent-get-function#tag-deprecated)
  * Improve stability and security

  ## v3.12.15

  * Improve stability and security
</Update>

<Update label="July 2026">
  ## v4.1.4

  * Minor bug fixes, stability, and security improvements

  ## v4.1.3

  * Minor bug fixes, stability, and security improvements

  ## v4.1.2

  * Minor bug fixes, stability, and security improvements

  ## v3.12.14

  * Minor bug fixes, stability, and security improvements

  ## v3.12.13

  * Minor bug fixes, stability, and security improvements

  ## v3.12.12

  * Minor bug fixes, stability, and security improvements
</Update>

<Update label="June 2026">
  ## v4.1.1

  * Minor bug fixes, stability, and security improvements

  ## v4.1.0

  * Minor bug fixes, stability, and security improvements
  * Added new methods to [BinaryOutput](https://docs.fingerprint.com/reference/js-agent-get-function#sealed_result): `toJSON`, `toString`, and `[Symbol.toPrimitive]`. These return a base64 representation of the binary data:
    ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
    const result = await agent.get();
    console.log(result.sealed_result.toString()); // <<< will log the base64 string now, instead of `[object Object]`
    ```

  ## v3.12.11

  * Minor bug fixes, stability, and security improvements

  ## v3.12.10

  * Minor bug fixes, stability, and security improvements
</Update>

<Update label="March 2026">
  ## v4.0.3

  * Minor bug fixes, stability, and security improvements

  ## v4.0.2

  * Minor bug fixes, stability, and security improvements

  ## v3.12.9

  * Minor bug fixes, stability, and security improvements

  ## v3.12.8

  * Minor bug fixes, stability, and security improvements
</Update>

<Update label="February 2026">
  ## v4.0.1

  * Minor bug fixes, stability, and security improvements

  ## v3.12.7

  * Improve Identification accuracy
</Update>

<Update label="January 2026">
  ## v4.0.0

  * New major API version has been released. This version contains a major overhaul of the API surface, configuration options, and introduces breaking changes. See the [full migration guide](/reference/migrating-from-v3-to-v4) for all the details to start the transition to this new version.
  * The deprecation period for JavaScript agent version 3 begins once all server, client, and proxy integrations get released. The deprecation period is **12 months** from that date, following our [API deprecation policy](/reference/api-deprecation-policy).

  ## v3.12.6

  * Improve Identification and Smart Signal accuracy
</Update>

<Update label="December 2025">
  ## v3.12.5

  * Minor bug fixes, stability and security improvements
</Update>

<Update label="November 2025">
  ## v3.12.4

  * Improve Identification accuracy in Safari 26
  * Drop support for older browsers and updated our [list of supported browsers](/docs/browser-and-device-support)
</Update>

<Update label="October 2025">
  ## v3.12.3

  * Improve Smart Signals accuracy
</Update>

<Update label="September 2025">
  ## v3.12.2

  * Add a check for `SecurityError` in all affected signals

  ## v3.12.1

  * Improve Smart Signals accuracy
</Update>

<Update label="August 2025">
  ## v3.12.0

  * Move to ES2018 JavaScript language version target.
  * Decrease overall latency and bundle size

  ## v3.11.14

  * Improve identification accuracy
  * Improve performance (minor improvement)
</Update>

<Update label="July 2025">
  ## v3.11.13

  * Improve accuracy of [Developer Tools Detection](/docs/smart-signals-reference#developer-tools-detection) Smart Signal
  * Optimize latency
  * Introduce `FingerprintJS.ERROR_PROXY_INTEGRATION_SECRET_ENVIRONMENT_MISMATCH`, returned when the proxy secret belongs to a different environment than the Public API key (but same workspace)

  ## v3.11.12

  * Improve performance (signal collection latency)

  ## v3.11.11

  * Optimize agent size
  * Remove unused signals to decrease latency
</Update>

<Update label="May 2025">
  ## v3.11.10

  * Improve general performance by decreasing the total bundle size
  * Improve signal collection performance in Safari
  * Improve Smart Signals accuracy
  * ImproveIdentification accuracy in Firefox
</Update>

<Update label="April 2025">
  ## v3.11.9

  * Add specific behavior for [AI bot request filtering](/docs/ai-bot-filtering)
</Update>

<Update label="February 2025">
  ## v3.11.8

  * Signal accuracy improvements
</Update>

<Update label="January 2025">
  ## v3.11.7

  * Introduce [more granular errors](/docs/changelog-javascript-agent#more-granular-errors) for proxy integration failures and request filtering
  * Increase [Smart Signals accuracy](/docs/changelog-javascript-agent#smart-signals-accuracy)

  ### More granular errors

  Introduce more granular [error constants](/reference/v3/js-agent-error-handling#errors) for [network request filtering](/docs/network-request-filtering) and [proxy integration](/docs/protecting-the-javascript-agent-from-adblockers) failures:

  * `FingerprintJS.ERROR_NETWORK_RESTRICTED`, triggered when a request is filtered out based on an IP address or IP address range
  * `FingerprintJS.ERROR_INVALID_PROXY_INTEGRATION_SECRET`, occurs when the `Fpjs-Proxy-Secret` header contains an empty, invalid, or non-matching value
  * `FingerprintJS.ERROR_INVALID_PROXY_INTEGRATION_HEADERS`, triggered when the proxy integration headers are misconfigured or partially provided in those specific cases:
    * Missing required headers (`Fpjs-Proxy-Client-IP`, `Fpjs-Proxy-Forwarded-Host`).
    * Duplicate headers
    * Invalid patterns for `Client-IP` or `Forwarded-Host`

  ### Smart Signals accuracy

  Significantly improve the accuracy of the [Virtual Machine Detection](/docs/smart-signals-reference#virtual-machine-detection) Smart Signal.

  ## v3.11.6

  * Minor bug fixes and improvements
</Update>

<Update label="December 2024">
  ## v3.11.5

  * Minor bug fixes and improvements impacting signal collection
</Update>

<Update label="November 2024">
  ## v3.11.4

  * Minor bug fixes and stability improvements
</Update>

<Update label="October 2024">
  ## v3.11.3

  * Drop official support for older browsers (older versions should still work but it is not guaranteed). Updated list is available in the [browser and device support documentation](/docs/browser-and-device-support).
  * JavaScript agent now throws the error from the first attempt instead of the one from the last retry. This makes it more clear what the error was because our retry/fallback endpoints are prone to get blocked by ad blockers.

  ## v3.11.2

  * Minor bug fixes and stability improvements
</Update>

<Update label="September 2024">
  ## v3.11.1

  * Improve the identification accuracy in some Android browsers
  * Improve the accuracy of [Smart Signals](/docs/smart-signals-reference)
</Update>

<Update label="August 2024">
  ## v3.11.0

  * Minor bug fixes in signal collection
  * Improve back/forward cache support to prevent full page reloads
  * Add [`urlHashing option`](/reference/v3/js-agent-load-function#urlhashing)
</Update>

<Update label="July 2024">
  ## v3.10.1

  * Improved accuracy of identification
  * Improved performance

  ## v3.10.0

  * A new JavaScript agent option: `remoteControlDetection` (has been deprecated since)
  * Fix incompatibility with some iOS versions
  * Remove the `Feature policy 'Payment' check failed...` console error in cross-origin iframes in Safari

  ## v3.9.10

  * Improved performance.
  * Improved accuracy of identification.
</Update>

<Update label="June 2024">
  ## v3.9.9

  * Improve the performance

  ## v3.9.8

  * fix: A message related to `AudioContext` is printed to the browser console
  * Improve the performance

  ## v3.9.7

  * Improve the identification and bot detection accuracy
  * Improve the performance
</Update>

<Update label="May 2024">
  ## v3.9.6

  * Improve the performance

  ## v3.9.5

  * Minor improvements
</Update>

<Update label="April 2024">
  ## v3.9.4

  * Improve the Smart Signals accuracy
  * The [ipLocation](/reference/v3/js-agent-get-function#iplocation) response field is marked as deprecated. It will not return a result for **applications created after January 23rd, 2024**. See [IP Geolocation](/docs/smart-signals-reference#ip-geolocation) for a replacement available in our Smart Signals product.

  ## v3.9.3

  * Deprecate option [products](/reference/v3/js-agent-get-function#products). The option to configure products became obsolete with the introduction of Smart Signals. Billed amount is determined by the billing plan and the products option does not influence it. Just remove it from your [JavaScript agent configuration](/reference/v3/js-agent-get-function). It will likely be removed in the next major version.
  * Fix unexpected popup appearing in Android Chrome in rare cases.
</Update>

<Update label="March 2024">
  ## v3.9.2

  * Fixed an unhandled promise rejection happening in rare cases

  ## v3.9.1

  * Minor improvements
</Update>

<Update label="January 2024">
  ## v3.9.0

  * [Sealed Client Results](/docs/sealed-client-results) support. Namely, added a new `get()` response field: [`sealedResult`](/reference/v3/js-agent-get-function#sealedresult).

  ## v3.8.7

  * Improve the [retry](/reference/v3/js-agent-load-function#scripturlpattern) algorithm used in case JavaScript agent fails to load from the CDN.
</Update>

<Update label="October 2023">
  ## v3.8.6

  * Deprecate options [`tlsEndpoint`](/reference/v3/js-agent-load-function#tlsendpoint-deprecated) and [`disableTls`](/reference/v3/js-agent-load-function#disabletls-deprecated). They are not necessary because of recent improvements to the ad blocker protection. Just remove them from your [JavaScript agent configuration](/reference/v3/js-agent-load-function). They will likely be removed in the next major version.
</Update>

<Update label="July 2023">
  ## v3.8.5

  * Minor improvements
</Update>

<Update label="June 2023">
  ## v3.8.4

  * Fix the [`subdivisions`](/reference/v3/js-agent-get-function#iplocation) field type in the TypeScript declarations
</Update>

<Update label="April 2023">
  ## v3.8.3

  * Add an [error constant](/reference/v3/js-agent-error-handling) `ERROR_INVALID_ENDPOINT` which is used then the `endpoint` option value is not a valid URL
</Update>

<Update label="February 2023">
  ## v3.8.2

  * Add a license file to the NPM package
</Update>

<Update label="November 2022">
  ## v3.8.1

  * Add an [error constant](/reference/v3/js-agent-error-handling) `ERROR_INTEGRATION_FAILURE` which will be used for errors that happen on the [integration](/docs/protecting-the-javascript-agent-from-adblockers) side

  ## v3.8.0

  * Fallback endpoint. You can set multiple endpoints; JavaScript agent will try to send the request with the first endpoint, and if the request fails, retry the request with the second endpoint and so on. Supported by all options: [scriptUrlPattern](/reference/v3/js-agent-load-function#scripturlpattern), [endpoint](/reference/v3/js-agent-load-function#endpoint) and [tlsEndpoint](/reference/v3/js-agent-load-function#tlsendpoint-deprecated).
  * Placeholder values for cases where you want to use the default endpoint as a fallback endpoint: - `FingerprintJS.defaultScriptUrlPattern` for [scriptUrlPattern](/reference/v3/js-agent-load-function#scripturlpattern) - `FingerprintJS.defaultEndpoint` for [endpoint](/reference/v3/js-agent-load-function#endpoint) - `FingerprintJS.defaultTlsEndpoint` for [tlsEndpoint](/reference/v3/js-agent-load-function#tlsendpoint-deprecated)
</Update>

<Update label="August 2022">
  ## v3.7.1

  * A new [error is thrown](/reference/v3/js-agent-error-handling) when JavaScript agent is blocked by [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP): `FingerprintJS.ERROR_CSP_BLOCK`. JavaScript agent doesn't retry network requests blocked by CSP. In previous versions a common error was thrown in this case: `FingerprintJS.ERROR_NETWORK_CONNECTION`.
</Update>

<Update label="July 2022">
  ## v3.7.0

  * [Bot Detection agent](https://fingerprint.com/products/bot-detection/) is embedded into FingerprintJS Pro agent
  * A new `fp.get()` option [products](/reference/v3/js-agent-get-function#products) to enable or disable Fingerprint products (Browser Identification, BotDetection)

  ## v3.6.4

  * Security improvements
</Update>

<Update label="May 2022">
  ## v3.6.3

  * Add the [`zeroTrust`](/docs/zero-trust-mode) field to the TypeScript declaration of JavaScript agent result object

  ## v3.6.2

  * New error type: `ERROR_FORBIDDEN_ENDPOINT`. See the [error handling guide](/reference/v3/js-agent-error-handling) for more details.
</Update>

<Update label="April 2022">
  ## v3.6.1

  * fix: JavaScript agent installed from jsDelivr makes a network request to fpnpmcdn.io that can be blocked by your Content Security Policy. This is a temporary fix, it will be reverted. Please [switch to our CDN](/docs/migrating-from-fingerprintjs-to-fingerprint-pro#cdn-installation) to avoid this problem in future.
</Update>

<Update label="March 2022">
  ## v3.6.0

  * A new CDN for the CDN installation methods. Follow [this guide](/docs/migrating-from-fingerprintjs-to-fingerprint-pro#cdn-installation) to update. The old CDN URLs pointing to jsDelivr continue working, but we recommend switching to our CDN to avoid excess network requests.
  * JavaScript agent installed from NPM loads its code from our CDN in runtime. It guarantees that you always use the latest and the most accurate version of JavaScript agent.
    * If you use a Content Security Policy, add the CDN domain to the CSP as described in the [JavaScript agent CSP documentation](/docs/js-agent-csp) (see the "NPM installation" tab).
    * If you do an HTML preconnect, consider preconnecting to the CDN too as described in the [API preconnect documentation](/docs/optimize-javascript-agent#pre-connect-to-fingerprint-urls) (see the "NPM installation" tab).
  * Add `firstSeenAt` and `lastSeenAt` fields to JavaScript agent responses. See more details in [Visitor Footprint Timestamps](/docs/useful-timestamps).
  * New error types: ERROR\_SCRIPT\_LOAD\_FAIL and ERROR\_INSTALLATION\_METHOD\_RESTRICTED. See the [error handling guide](/reference/v3/js-agent-error-handling) for more details.
  * A new `load()` option in the NPM package of JavaScript agent: [`scriptUrlPattern`](/reference/v3/js-agent-load-function#scripturlpattern). See more details in the [JavaScript agent guide](/reference/v3/js-agent-load-function#scripturlpattern).

  ## v3.5.7

  * fix: If your project uses TypeScript and has the TypeScript's [isolatedModules](https://www.typescriptlang.org/tsconfig#isolatedModules) option is enabled, JavaScript agent causes an error: "TS2748: Cannot access ambient const enums"

  ## v3.5.6

  * Rename the token option of the `load` method of JavaScript agent to `apiKey`. The token option keeps working for backward compatibility. Also rename some error constants (the old names work too):
    * `ERROR_TOKEN_MISSING` → `ERROR_API_KEY_MISSING`
    * `ERROR_TOKEN_INVALID` → `ERROR_API_KEY_INVALID`
    * `ERROR_TOKEN_EXPIRED` → `ERROR_API_KEY_EXPIRED`
  * fix: JavaScript agent triggers a console error message unless the page's Content Security Policy allows `unsafe-inline` for `style-src`.
</Update>

<Update label="January 2022">
  ## v3.5.5

  * A new region: `ap` (Mumbai, India)
</Update>

<Update label="December 2021">
  ## v3.5.4

  * Improve incognito mode detection accuracy in Safari
  * Deprecate the `ipResolution` parameter because it affects nothing
  * The `get()` result's `ipLocation` field is marked is optional in the TypeScript declaration. The field could be undefined in fact, so this is a fix of the type declaration.
  * Actualize the [list of supported browsers](/docs/browser-and-device-support).
  * A new [error code](/reference/v3/js-agent-error-handling) for cases when the JavaScript agent version is not supported: `FingerprintJS.ERROR_UNSUPPORTED_VERSION`
  * Decrease the JavaScript agent code size by removing legacy parts
  * fix: An indefinite `setTimeout` loop in Firefox
</Update>

<Update label="September 2021">
  ## v3.5.3

  * Improve the tree-shaking capability
  * Confidence score calculations moved to server for increased accuracy (Pro version)

  ## v3.5.2

  * Improve the performance slightly
</Update>

<Update label="August 2021">
  ## v3.5.1

  * Improve identification time for visitors who use an ad blocker or an M1 Mac
  * Improve identification accuracy
</Update>

<Update label="July 2021">
  ## v3.5.0

  * Add a new result field: confidence score. The confidence score field tells how much the agent is sure about the visitor identifier. See [the API reference](/reference/v3/js-agent-get-function#confidence) for more details.
  * Fix an error that occurs in Firefox Add-ons
</Update>

<Update label="June 2021">
  ## v3.4.0

  * Makes `get` run much faster when some time passes between calling `load()` and `get()`. See the [JavaScript agent preloading guide](/docs/optimize-javascript-agent#preload-the-javascript-agent) to learn how to leverage it.
  * Added an error constant for bad server response format: `FingerprintJS.ERROR_BAD_RESPONSE_FORMAT`. The error can be caused by wrong endpoint.
  * The `disableTls` option is moved from the get options to the load options. It still works when set within get options for compatibility, but doesn't actually disable the TLS request. So we recommend updating your code if you use `disableTls`.
  * fix: JavaScript agent may never complete getting the visitor identifier when the page is in background.

  ## v3.3.3

  * Fix client timeouts in WeChat built-in browser on iOS 13
  * Increase the accuracy of agent when the page runs in background
</Update>

<Update label="May 2021">
  ## v3.3.2

  * Fix "Client timeout" errors that happen in bots that run `setTimeout` too quickly
  * Fix console WebGL warnings in IE 11
</Update>

<Update label="April 2021">
  ## v3.3.1

  * Incognito detection accuracy improvement
  * TypeScript compatibility improvement
  * Fix an error in Android 5.1 Browser: Failed to parse the response
  * Fix client timeouts in iOS WeChat built-in browser

  ## v3.3.0

  * Many new identification methods under the hood
  * JavaScript agent retries visitor identification request in case of error
  * A new billing model. Identifications are billed per a unique visitor instead of a request.
  * New [expected JavaScript agent errors](/reference/v3/js-agent-error-handling): `FingerprintJS.ERROR_WRONG_REGION`, `FingerprintJS.ERROR_SUBSCRIPTION_NOT_FOUND`.

  ## v3.2.6

  * fix: Remote monitoring doesn't work in Android Browser 4.1
  * fix: JavaScript agent script encoding can change the canvas fingerprint, that can reduce accuracy in rare cases
  * Add internal request encryption
  * Improve the fingerprinting performance

  ## v2.8.5

  * Fix incognito detection in some browsers based on Blink
  * Decrease the chance of getting `send()` call timeout by decreasing the TLS request timeout
  * Improve the fingerprinting performance
</Update>

<Update label="February 2021">
  ## v3.2.5

  * Increase the TLS request stability by retrying
  * Decrease the chance of getting `get()` call timeout by decreasing the TLS request timeout
  * fix: Monitoring reports aren't sent sometimes

  ## v3.2.4

  * Improve the accuracy of Chrome incognito detection
  * Add the `requestId` field to errors emitted by the servers
  * Make JavaScript agent [easier to use](https://github.com/fingerprintjs/fingerprintjs/pull/610) in server side rendering environments like Next.js and Gatsby

  ## v2.8.4

  * Fix cookie `SameSite` attribute warnings in Firefox
  * Increase the accuracy of Chrome incognito detection
  * Add the `requestId` field to errors emitted by the servers
</Update>

<Update label="January 2021">
  ## v3.2.3

  * Add [JavaScript agent constants](/reference/v3/js-agent-error-handling) for the new [request filtering](/docs/request-filtering) errors
  * Fix cookie `SameSite` attribute warnings in Firefox
  * Improve the identification mechanism
</Update>

<Update label="December 2020">
  ## v3.2.2

  * fix: `load()` takes a huge time to run in some conditions
  * Handle cases where `navigator.deviceMemory` is a string

  ## v3.2.1

  * Add more information to JavaScript agent monitoring

  ## v3.2.0

  * Add an experimental API for JavaScript agent debugging. We can use it to analyze agent operation on your side and solve problems faster. [Contact support](mailto:support@fingerprintjs.com) for more details.
  * The minimal supported version of TypeScript is 4.0.0.
  * Amend Safari private mode detection. It always detected `incognito: true` in desktop Safari controlled by Karma or BrowserStack Automate.

  ## v2.8.3

  * fix: `FP.load()` takes a huge time to run in some conditions
  * Handle cases where `navigator.deviceMemory` is a string
</Update>

<Update label="November 2020">
  ## v3.1.0

  * Increased stability of the audio fingerprint component on iPhone
  * Made JavaScript agent use a TLS server located in Europe when the region is set to EU, for example:
    ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
    FingerprintJS.load({
      token: "your-token",
      region: "eu",
    });
    ```
  * Added an option to set a custom TLS endpoint:
    ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
    FingerprintJS.load({
        token: 'your-token',
        tlsEndpoint: 'https://mytls.example.com'
    })
    ```

  ## v3.0.3

  * fix: Incognito detection doesn't work in mobile Safari 13 and newer

  ## v3.0.2

  * fix: It's impossible to set an endpoint that is relative to the current domain in the `FingerprintJS.load()` function. For example, the following code didn't work:
    ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
    const fp = await FingerprintJS.load({ token: 'your-token', endpoint: '/metrics' })
    const result = await fp.get()
    ```
    Warning. If you set the endpoint option to something like `metrics.example.com`, it will break because this is not an expected behavior. Change the endpoint to `https://metrics.example.com`.

  ## v2.8.2

  * Amend Safari private mode detection. It always detected `incognito: true` in desktop Safari controlled by Karma or BrowserStack Automate.

  ## v2.8.0

  * Increased stability of the audio fingerprint component on iPhone
  * Made JavaScript agent use a TLS server located in Europe when the region is set to EU, for example:

    <CodeGroup>
      ```javascript NPM installation theme={"theme":"github-dark-dimmed"}
      import { FP } from "@fp-pro/client";
      FP.load({
        client: "your-token",
        region: "eu",
      });
      ```

      ```html CDN installation theme={"theme":"github-dark-dimmed"}
      <head>
        <script>
          window.fpLayer = window.fpLayer || [];
          function fp() {
            fpLayer.push(arguments);
          }
          fp("config", "client", "your-token");
          fp("config", "region", "eu");
        </script>
        <script async src="https://cdn.fpjs.io/@2/fp.js"></script>
      </head>
      ```
    </CodeGroup>
  * Added an option to set a custom TLS endpoint:

    <CodeGroup>
      ```javascript NPM installation theme={"theme":"github-dark-dimmed"}
      import { FP } from '@fp-pro/client';
      FP.load({
          client: 'your-token',
          tlsEndpoint: 'https://mytls.example.com'
      })
      ```

      ```html CDN installation theme={"theme":"github-dark-dimmed"}
      <head>
          <script>
          window.fpLayer = window.fpLayer || [];
          function fp() { fpLayer.push(arguments); }
          fp('config', 'client', 'your-token');
          fp('config', 'tlsEndpoint', 'https://mytls.example.com');
          </script>
          <script async src="https://cdn.fpjs.io/@2/fp.js"></script>
      </head>
      ```
    </CodeGroup>
</Update>

<Update label="October 2020">
  ## v3.0.1

  * Unexpected entropy component errors are printed in the [debug mode](/reference/js-agent-error-handling#handling-errors) of the JavaScript agent. Such errors should be reported to us.
  * Support elder browsers like IE 11, Chrome 42 and Firefox 48 (a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) polyfill is required)
  * Handle cases where `new Date().getTimezoneOffset()` returns a string
  * fix: Getting the visitor identifier takes a huge time in some conditions

  ## v3.0.0

  * The JavaScript agent API is changed to provide a simple transition from the [open-source version of the agent](https://github.com/fingerprintjs/fingerprintjs).
  * The installation methods have been unified so that they have same options and same usage methods. Also we've added a couple new ways to install.
  * Result and error handling has been simplified. A single value type is returned (resolved) and a single value type is thrown (rejected). The agent throws error only when a visitor identification fails due to incorrect agent setup or network issues; special kinds of visitors don't cause errors.

  Learn how to migrate:

  * [From FingerprintJS Pro version 2](/docs/migrating-from-fingerprintjs-to-fingerprint-pro)
  * [From FingerprintJS Open-Source version 3](/docs/migrating-from-fingerprintjs-to-fingerprint-pro#migrating-from-fingerprintjs-v3-open-source-to-fingerprint-identification)
  * [From FingerprintJS Open-Source version 2](/docs/migrating-from-open-source-v2)

  ## v2.7.7

  * fix: An error that occurs in a very rare case when `navigator.permissions` is present while `window.Notification` isn't.
  * Handle cases where `new Date().getTimezoneOffset()` returns a string
  * fix: Visitor identifier can change due to a daylight saving time shift
</Update>


# MCP server
Source: https://docs.fingerprint.com/docs/changelog-mcp-server

This changelog lists all additions and updates to the Fingerprint MCP server, in chronological order.

<Update label="August 2026">
  ## Available in the Anthropic connectors directory

  Fingerprint is now listed in the Anthropic connectors directory. In Claude, go to **Settings** > **Connectors**, click **Browse**, and search for `Fingerprint`. You no longer need to add a custom connector or enter the server URL.

  Adding Fingerprint as a custom connector still works, and remains the setup path for Claude Code, Cursor, VS Code, and other MCP clients. See the [MCP server guide](/docs/mcp-server).
</Update>

<Update label="August 2026">
  ## Tool list stays current without reconnecting

  Added three tools that keep newly released tools reachable without disconnecting and reconnecting your AI client:

  * `list_tools` reports the tools the server is currently serving.
  * `call_tool` runs any tool that `list_tools` reports.
  * `call_write_tool` runs write actions through a separate proxy with its own approval prompt.

  Some AI clients cache the tool list for a conversation, so tools added in a release did not appear until you reconnected or started a new conversation. These three tools stay constant, so once they are in your tool list, future tools stay reachable through them.

  After this update, start one new conversation for the three tools to appear. From then on, your tool list stays current.
</Update>

<Update label="July 2026">
  ## New `get_current_time` tool

  Added a `get_current_time` tool that returns the current time as a UTC RFC3339 timestamp and Unix epoch. Pass an optional IANA time zone (such as `America/New_York`) to also get the local time in that zone.

  This gives AI clients a reliable clock when building relative time ranges for `search_events`, instead of inferring the date from their training data.
</Update>

<Update label="June 2026">
  ## Bot detection filters for `search_events`

  Added bot detection filters to `search_events`: `bot_info`, `bot_info_category`, `bot_info_identity`, `bot_info_confidence`, `bot_info_provider`, and `bot_info_name`. You can now have your AI client search identification events by bot activity, confidence, and provider.
</Update>

<Update label="May 2026">
  ## Human-readable timestamps for `search_events`

  The `start` and `end` parameters on `search_events` now use human-readable RFC3339 timestamps instead of Unix milliseconds. This helps AI clients build correct time ranges and avoid querying dates outside the supported 90-day window.
</Update>

<Update label="March 2026">
  ## Fingerprint MCP server is now available

  Connect AI assistants and agents to Fingerprint device intelligence with the new [Fingerprint MCP server](/docs/mcp-server). Your AI tools can query identification events, detect anomalies, investigate fraud patterns, and manage your Fingerprint workspace through natural language.

  The server is available in two forms:

  * **Managed service**: Hosted by Fingerprint at `https://mcp.fpjs.io/mcp`, with no setup or maintenance required.
  * **Open source**: Self-host from the [GitHub repository](https://github.com/fingerprintjs/fingerprint-mcp-server) for full control over deployment.

  See the [MCP server guide](/docs/mcp-server) to get started.
</Update>


# Smart Signals
Source: https://docs.fingerprint.com/docs/changelog-smart-signals

This changelog lists all additions and updates to the Fingerprint Smart Signals documentation, in chronological order.

<Update label="September 2026">
  ## Factory Reset Detection — Android improvements

  Improved factory reset detection accuracy for Samsung (series A, S) and Xiaomi devices, where filesystem behavior specific to these manufacturers was previously causing some devices to be misclassified as factory reset.

  * New logic is available in [Android SDK 2.10.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#v2-10-0)
</Update>

<Update label="April 2026">
  ## Suspect Score Recommendations — New Smart Signals Capability ML-based

  Allows you to upload labeled fraud data and receive optimized signal weights tailored to your traffic. You can review, accept, or reject recommendations in the dashboard. Check the [Suspect Score](https://docs.fingerprint.com/docs/suspect-score) page for more details.
</Update>

<Update label="August 2026">
  ## Raw Device Attributes - New Web Attributes

  Expanded the `raw_device_attributes` Smart Signal with new web attributes: `battery_level`, `battery_charging`, `keyboard_layout_name`, `keyboard_layout_hash`, `font_hash`, and `timezone_offset`.

  * `keyboard_layout_name`, `keyboard_layout_hash`, `font_hash`, `battery_level`, and `battery_charging` are only available in Chrome and other Chromium-based browsers.
  * Available to Enterprise plan customers.

  See the [full list of supported attributes](https://docs.fingerprint.com/docs/smart-signals-reference#raw-device-attributes) for details.
</Update>

<Update label="August 2026">
  ## Active Call Detection - Available for iOS and Android

  Introduced a new mobile Smart Signal that detects whether the user's device has an active cellular or internet (VoIP) call in progress. See [Smart Signals reference](/docs/smart-signals-reference#active-call-detection) for additional details.

  * Requires [iOS SDK 2.16.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#june-2026) and [Android SDK 2.16.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#june-2026).
  * Supported via [API v4](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) responses.
</Update>

<Update label="July 2026">
  ## **Device Rarity Detection - New Browser Smart Signal**

  Introduced a new Smart Signal that identifies devices whose combination of core attributes is statistically uncommon or previously unseen across global traffic.

  * Requires JavaScript Agent version 3.8.10 or higher.
</Update>

<Update label="June 2026">
  ## **ML-Based VPN, Proxy & Virtual Machine Detection**

  Strengthened the detection of VPNs, proxies, and virtual machines using machine learning-based models.

  * Requires JavaScript Agent version 3.12.9 or higher.
</Update>

<Update label="June 2026">
  ## Rooted Device Detection - Android Improvements

  Strengthened the detection logic for identifying rooted Android devices.

  * New logic is available in [Android SDK v2.15.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#april-2026).
</Update>

<Update label="May 2026">
  ## Proximity Detection - Available on Web

  Proximity detection is now available on web. The proximity ID represents a fixed geographical zone rather than a unique device, it is useful for detecting device clusters in the same area or a device that changed identity but not location. See the [Proximity detection reference](/docs/smart-signals-reference#proximity-detection).

  * Requires JavaScript Agent version 3.12.9 or higher.
</Update>

<Update label="May 2026">
  ## Developer Tools Detection - Available for iOS and Android

  Detect whether developer tools are active on a mobile device via the [Developer Tools Detection](https://docs.fingerprint.com/docs/smart-signals-reference#developer-tools-detection-for-mobile-devices) smart signal.

  * Helps identify environments where developer tools are active, which may indicate reverse engineering, dynamic instrumentation, or automated abuse when combined with other signals.
  * Requires [iOS SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#december-2025) and [Android SDK 2.6.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#v2-6-0).
  * Supported via [API v4](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) and API v3 responses.
</Update>

<Update label="May 2026">
  ## Raw Device Attributes Now Available on Mobile

  The following Raw Device Attributes are now collected by native mobile SDKs:

  * Android: screen resolution, device memory, languages, battery level, low power mode
  * iOS: screen resolution, device memory, languages, battery level, low power mode

    Notes:

    * Requires [iOS SDK 2.15.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#may-2026-2) and [Android SDK 2.15.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#april-2026).
    * Supported via [API v4](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) responses.
    * The device memory attribute on iOS is available starting in [iOS SDK 2.16.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#june-2026)

    See the [full list of supported attributes](https://docs.fingerprint.com/docs/smart-signals-reference#raw-device-attributes) for details.
</Update>

<Update label="May 2026">
  ## Frida detection — iOS improvements

  Improved the detection mechanism for active Frida connections in the [iOS SDK v2.14.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#march-2026).
</Update>

<Update label="April 2026">
  ## Suspect Score Recommendations — New Smart Signals Capability ML-based

  Allows you to upload labeled fraud data and receive optimized signal weights tailored to your traffic. You can review, accept, or reject recommendations in the dashboard. Check the [Suspect Score](https://docs.fingerprint.com/docs/suspect-score) page for more details.
</Update>

<Update label="March 2026">
  ## iOS Simulator Detection — New Mobile Smart Signal

  Detect whether your app is running on an [iOS simulator](https://docs.fingerprint.com/docs/smart-signals-reference#ios-simulator-detection) instead of a physical device.

  * Helps detecting whether your app is running on an iOS simulator rather than a physical device.
  * Requires [iOS SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#december-2025).
  * Supported via [API v4](https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4) responses.
</Update>

<Update label="March 2026">
  ## Geolocation Spoofing Detection — iOS Improvements

  Improved accuracy in detecting mocked locations on iOS devices.

  * Requires geolocation permissions
  * Available in [iOS SDK 2.13.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#february-2026).
</Update>

<Update label="March 2026">
  ## ML-based Anti-Detect Browser Detection — Tampering Signal Enhancement

  Introduced an ML-based layer for [Anti-Detect Browser detection](https://docs.fingerprint.com/docs/smart-signals-reference#anti_detect_browser), improving coverage and accuracy. Added `tampering_confidence` and `tampering_score` fields to the response.

  * Supported across API v3 and v4.
</Update>

<Update label="January 2026">
  ## Detecting real location — iOS VPN detection improvements

  [Origin country field](https://docs.fingerprint.com/docs/smart-signals-reference#vpn_origin_country-2) on iOS has been enhanced to infer a user's true country even without location permissions, helping teams go beyond broad VPN-based risk assumptions and focus on genuine location mismatches. Check out the full [*product updates article*](https://fingerprint.com/blog/q1-2026-product-roundup/#real-location-detection-mobile-see-past-vpns-to-reveal-true-device-origin) for more details.

  * Doesn't require geolocation permission
  * New logic is available in [iOS SDK 2.9.0+](https://docs.fingerprint.com/docs/changelog-ios-sdk#august-2025).
</Update>

<Update label="January 2026">
  ## Proxy Provider Name — Proxy Signal Enhancement

  Added proxy provider name to API responses for improved transparency.

  * Supported across API v3 and v4.
</Update>

<Update label="January 2026">
  ## Raw Device Attributes

  Introduced a curated set of stable and reliable [device and browser attributes](https://docs.fingerprint.com/docs/smart-signals-reference#raw-device-attributes).

  * Supported on API v4.
</Update>

<Update label="December 2025">
  ## Organization name and type fields — IP Geolocation Signal Enhancement

  Added `organization name` and `type` fields to the [IP Geolocation signal](https://docs.fingerprint.com/docs/smart-signals-reference#ip-geolocation). Improved network-level insights.

  * Supported across API v3 and v4.
</Update>

<Update label="December 2025">
  ## Cloned App Detection — Android Improvements

  Strengthened [cloned app detection](https://docs.fingerprint.com/docs/smart-signals-reference#cloned-app-detection) on Android through improvements to the core detection logic.

  * New logic is available in [Android SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#december-2025).
</Update>

<Update label="October 2025">
  ## Rooted Device Detection — Android Improvements

  Refined the underlying detection algorithm for identifying [rooted devices](https://docs.fingerprint.com/docs/smart-signals-reference#rooted-device-detection) and [emulators](https://docs.fingerprint.com/docs/smart-signals-reference#android-emulator-detection) on Android.

  * New logic is available in [Android SDK 2.12.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#december-2025).
</Update>

<Update label="September 2025">
  ## Factory Reset Detection — Android Improvements

  Enhanced the detection logic to more accurately identify true [factory resets on Android devices](https://docs.fingerprint.com/docs/smart-signals-reference#factory-reset-detection).

  * This update reduces false positives and improves signal reliability for fraud prevention workflows.
  * New logic is available in [Android SDK 2.10.0+](https://docs.fingerprint.com/docs/changelog-android-sdk#september-2025).
</Update>


# API Deprecation Policy
Source: https://docs.fingerprint.com/reference/api-deprecation-policy

At Fingerprint, we regularly release updates to our JavaScript agent, APIs, and SDKs, to give you more features, increased security, and better performance. Sometimes, this means older versions of our APIs will no longer be supported.

## Quick overview

* All of your APIs and SDKs follow [semantic versioning](#semantic-versioning).
* Major releases of the JavaScript agent, Android SDK, iOS SDK, and all server-side APIs follow our [Deprecation and notice policy](#deprecation-and-notice-policy). You will have **1 year** from the major version release date to upgrade your implementation using the provided migration guides.
* Client and Backend SDKs are wrappers for the underlying JavaScript agent, mobile SDKs, or server-side APIs. They follow their own semantic versioning. The Deprecation and notice policy applies to them [only when the underlying SDK or API is deprecated](#exceptions-to-the-deprecation-and-notice-policy).

## Semantic versioning

All of our products are versioned using the [Semantic versioning](https://semver.org/) format `MAJOR.MINOR.PATCH`.

* We increment the `PATCH` version, for example, from `1.2.0` to `1.2.1`, when we make backward-compatible bug fixes. You can upgrade to a new patch version without making any changes to your application.
* We increment the `MINOR` version, for example, from `1.2.1` to `1.3.0`, when we add new features without any breaking changes. You can upgrade to a new minor version without making any changes to your application.

> Note: We can also use MINOR releases to update mobile SDK runtime requirements, for example, dropping support for old versions of iOS or Android.

* We increment the `MAJOR` version, for example, from `1.3.0` to `2.0.0`, when we make improvements that require you to make changes to your application. Upgrading to a new major version requires updating your application’s code, dependencies, or minimum required platform version to follow the new contract.

<Info>
  **Versioning REST APIs**

  REST and server-side APIs like [Server API](/reference/server-api), [Management API](/reference/management-api), [Device Reputation Network API](/reference/drn-api-overview), [Webhooks](/docs/webhooks) and [Sealed client results](/docs/sealed-client-results) only use the `MAJOR` version.

  * Non-breaking changes and additions to these APIs can happen at any time.
  * The API endpoint version is usually indicated by a **query parameter** (e.g. `/events?version=4`) or a **path parameter** (e.g. `/<version>/events`).
</Info>

## Deprecation and notice policy

When we release a new **MAJOR** version of the JavaScript agent, mobile SDKs, REST API endpoint, or another server-side API, the following policy applies since March 2025:

### One-year migration period

* You will have **one year** from the release date to switch to the new major version.
* We recommend upgrading as soon as possible to avoid any disruptions. We will always provide detailed migration guides and our customer success team will work with individual customers to ensure a smooth transition.
* During the migration period, we will continue to support both the deprecated and the new versions. The deprecated version will receive security fixes, but no new features or improvements.
* After the migration period ends, the previous (deprecated) major version will stop working.

### Deprecation notice

* We will inform you by email when a new major version is released. From this point, the previous major version is marked as **deprecated** and will stop working in one year.
* The relevant documentation will include a clear deprecation notice including the exact date of the API/SDK removal and end of support.
* If we detect you have not upgraded to the new version (for example, you are calling a deprecated API endpoint), we will send you reminder emails from [\[email protected\]](mailto:support@fingerprint.com) *once a month*. The email frequency will increase to *once a week* in the last month before the end of support.

<Info>
  Note: Some legacy APIs or SDKs might be deprecated without a direct replacement. In those cases, we will follow the same Deprecation and notice policy outlined above, including the one-year migration period.
</Info>

The Deprecation and notice policy covers the following:

* [JavaScript Agent](/reference/js-agent)
* [iOS SDK](/docs/ios-sdk)
* [Android SDK](/docs/android-sdk)
* [Webhook format](/docs/webhooks)
* [Sealed client results format](/docs/sealed-client-results)
* [Server API](/reference/server-api) (each endpoint can be versioned and deprecated individually) — see the [v3 to v4 migration guide](/reference/migrating-from-server-api-v3-to-v4)
* [Management API](/reference/management-api) (each endpoint can be versioned and deprecated individually)
* [Device Reputation Network API](/reference/drn-api-overview) (each endpoint can be versioned and deprecated individually)

## Exceptions to the Deprecation and notice policy

### Cloud proxy integrations

[Cloud proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers#cloud-proxy-integrations) have a large number of internal dependencies (JavaScript agent, Identification API, etc.) and external dependencies (cloud platforms and their products).

* In most cases, cloud proxy integrations follow the Deprecation and notice policy.
* However, in exceptional circumstances beyond our control (for example, a sudden change in a cloud platform dependency), we might be forced to end support for a deprecated version of a cloud proxy integration in **less than one year**.

### Wrapper SDKs

The Deprecation and notice policy **does not generally apply** to the following:

* [Frontend SDKs](/docs/frontend-libraries): React, Angular, Svelte, Vue, etc.
* Multi-platform SDKs: [React Native](/docs/fingerprintjs-pro-react-native) and [Flutter](/docs/flutter).
* [Server SDKs](/reference/server-sdks): Node, PHP, Go, Java, Python, and #C.

These SDKs (let’s call them *wrapper* SDKs) give you a smoother developer experience by providing utilities *on top* *of* the underlying JavaScript agent, mobile SDKs, and server-side APIs respectively.

* Wrapper SDKs follow their own semantic versioning.
* They can regularly release new major versions independently of the underlying SDK or API.
* The [Deprecation and notice policy](#deprecation-and-notice-policy) applies to them **only when the underlying SDK or API is deprecated**.

<Accordion title="Example A (Policy does not apply)">
  If we release a major version of the Node SDK that uses the same version of the underlying Server API as before, the deprecation policy **does not apply:**

  * For example, we improve the runtime function signature of some methods in the Node SDK. This breaking change (however small) requires releasing a new major version of the Node SDK. However, the SDK still uses the same version of the underlying Server API.
  * Therefore, the previous Node SDK major version is NOT \*\*deprecated, it stays available and continues to work.
  * There are no notice emails or deprecation notices.
  * The previous Node SDK major version continues to receive security fixes, but new features or improvements are only added to the latest major version.
  * The previous Node SDK major version can become deprecated later: 
    * As a result of the [Node SDK deprecation policy](https://github.com/fingerprintjs/node-sdk?tab=readme-ov-file#requirements) (e.g., if the underlying Node version is deprecated).
    * If the underlying Server API endpoint version is deprecated, as discussed below.
</Accordion>

<Accordion title="Example B (Policy applies)">
  If we release a major version of the Node SDK that uses a new major version of the underlying Server API, the deprecation policy **applies:**

  * All previous major versions of the Node SDK, using the now deprecated version of the Server API are now also deprecated according to the [Deprecation and notice policy](#deprecation-and-notice-policy).
</Accordion>


# Create API key
Source: https://docs.fingerprint.com/reference/apikeyscontroller_create

reference/management-api_2025-11-20.json POST /api-keys
Creates an API key for the workspace associated with the Management API key. Maximum number of API keys in defined by your plan limits. If you need additional API keys, contact our support team.



# Delete API key
Source: https://docs.fingerprint.com/reference/apikeyscontroller_deleteapikey

reference/management-api_2025-11-20.json DELETE /api-keys/{id}
Deletes an API key with the given ID. Make sure that the key you are deleting is not used in production environment. This action is not reversible.



# List API keys
Source: https://docs.fingerprint.com/reference/apikeyscontroller_findall

reference/management-api_2025-11-20.json GET /api-keys
Lists all API keys for the workspace associated with the Management API key.



# Get API key
Source: https://docs.fingerprint.com/reference/apikeyscontroller_findone

reference/management-api_2025-11-20.json GET /api-keys/{id}
Fetch an API key by ID.



# Update API key
Source: https://docs.fingerprint.com/reference/apikeyscontroller_update

reference/management-api_2025-11-20.json PATCH /api-keys/{id}
Updates a single API key. You can update the keys name, description, status, and rate limit. You cannot mutate the actual key itself.



# Authentication
Source: https://docs.fingerprint.com/reference/drn-api-authentication

DRN API requests are authorized by using the **secret API key**.

You can create one in your Fingerprint Dashboard by visiting **[API Keys](https://dashboard.fingerprint.com/api-keys)**.

<Warning>
  **Your secret API keys can be used query sensitive information about Android devices, be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, or with AI tools.**
</Warning>

Authentication is done with **Bearer authentication** (also called token authentication), and it involves providing the *secret* API key in a HTTP header. Use the `Authorization` header to authenticate requests to the DRN API.

```txt theme={"theme":"github-dark-dimmed"}
Authorization: Bearer SECRET_API_KEY
```

```bash cURL theme={"theme":"github-dark-dimmed"}
curl --request GET \
  --url 'https://drn-api.fpjs.io/drn/{visitor-id-from-your-app}?signals=regional_activity' \
  --header 'Authorization: Bearer SECRET_API_KEY' \
  --header 'X-API-Version: 2024-09-01'
```

Requests without a valid Authorization header will return `HTTP 401` error:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP Status: 401
{
  "error": {
    "code": "secret_key_not_found",
    "message": "secret key not found"
  }
}
```

This error will be returned if a correct Authorization header is not provided or when a secret API key is not found.


# Changelog
Source: https://docs.fingerprint.com/reference/drn-api-changelog

This changelog lists all additions and updates to the DRN API, in chronological order.

## 2024-09-01

* Initial release.
* Adds support for `regional_activity` signal.
* Adds support for `suspect_score` signal.
* Adds support for `timestamps` signal.


# Overview
Source: https://docs.fingerprint.com/reference/drn-api-drn-endpoint

`drn`endpoint

The DRN API supports a `drn` endpoint, that has two required parameters: `visitor_id` and `signals`.

### `GET https://drn-api.fpjs.io/drn/{visitor_id}?signals={signal}`

See the [Get by visitor ID reference](/reference/drn-api-get-by-visitor-id).


# Error handling and edge cases
Source: https://docs.fingerprint.com/reference/drn-api-error-handling

Handling errors when working with the DRN

There are certain errors that are possible when working with the DRN API:

## General error format

When the DRN API cannot process your request, it will return an error in the following format:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "error": {
    "code": "fixed_code",
    "message": "descriptive error message"
  }
}
```

The `code` is fixed inside a version, but the `message` can be updated to be more clear. Only the `code` value compatibility is guaranteed inside a specific [version](/reference/drn-api-versioning) !

For specific errors related to authentication, versioning, and rate limiting please refer to the specific reference pages.

## Unknown resource path

If a request is made to an unknown resource path (the part after the domain), an HTTP 404 error will be returned:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP Status 404
{
  "error": {
    "code": "http.not_found",
    "message": "not found"
}
```

The only valid resource path (the part that goes after fpjs.io) is `drn`:

**`GET https://drn-api.fpjs.io/drn/{visitor_id}`**

## Invalid `visitor_id` parameter.

If the `visitor_id` parameter that was provided is not known to the DRN API, e.g. if it's not generated by our Android SDK or is unknown entirely, an HTTP 404 error will be returned:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP Status 404
{
  "error": {
    "code": "http.not_found",
    "message": "visitor_id is not found"
  }
}
```

## Invalid `signals` parameter

A request without at least one `signals` parameter will return an HTTP 400 error:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP Status 400
{
  "error": {
    "code": "invalid_signals_parameter",
    "message": "Invalid `signals` query parameter"
}
```

## Empty response

If you requested the signals from a device with activity older than 30 days, you'll get an empty state response:

```json JSON theme={"theme":"github-dark-dimmed"}
"regionalActivity": [
  // will be at 30 days in the past in RFC3369 format, UTC timezone
  "startDate": "2024-09-01T23:12:59Z",
  "endDate": "2024-10-01T23:12:59Z",
  "countries": []
},
"suspectScore": {
  // will be at 30 days in the past in RFC3369 format, UTC timezone
  "startDate": "2024-09-01T23:12:59Z",
  "endDate": "2024-10-01T23:12:59Z",
  "minimum": {
    "value": 0,
    "signals": {}
  },
  "maximum": {
    "value": 0,
    "percentile": 0
    "signals": {}
  }
},
"timestamps": {
  "firstSeenAt": "2024-09-01T00:00:00Z" // format RFC3339, equal to current API version 
  "lastSeenAt": "2024-09-01T00:00:00Z" // format RFC3339, equal to current API version
  }
```


# Get device reputation signals
Source: https://docs.fingerprint.com/reference/drn-api-get-by-visitor-id

get /drn/{visitorId}
Returns device reputation information of a visitor.



# Overview
Source: https://docs.fingerprint.com/reference/drn-api-overview

How to get started with Fingerprint's global device intelligence network API (DRN API)

**Device Reputation Network API** allows making requests to Fingerprint's expansive device intelligence network and get global behavior and risk information about Android devices. To understand the underlying architecture of the DRN API, please refer to this [guide](/docs/drn-overview).

<Note>
  **DRN API only supports Fingerprint's [Android SDK](/docs/android-sdk)**
</Note>

DRN API is only for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. Since Fingerprint doesn't bill for server-side API calls, DRN API is free to use and does not count toward your monthly plan, however API key rate limits apply.

<Check>
  **DRN API requests do not count toward your monthly plan and are not billed.**
</Check>

# Getting started

DRN API is available globally:

| Region | Base URL                  |
| ------ | ------------------------- |
| Global | `https://drn-api.fpjs.io` |

You can use DRN API for all your workspaces, regardless of their [region](/docs/regions).

## Authentication

DRN API requests are authorized with a **Secret API key** that can be obtained in your Fingerprint Dashboard by visiting **[API Keys](https://dashboard.fingerprint.com/api-keys)**.

Set your API key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer SECRET_API_KEY
```

Read more in [Authentication](/reference/drn-api-authentication).

## Version

DRN API is versioned by date. This date represents when a backwards-incompatible change was made. The latest version is **`2024-09-01`**.

Set the version as in the `X-API-Version` header:

```
X-API-Version: 2024-09-01
```

Read more in [Versioning](/reference/drn-api-versioning).

## Signals

DRN API supports three signals in the current version: `regional_activity`, `suspect_score`, and `timestamps`. You can request all three signals in a single request.

## Making a request

The DRN API has two required parameters: `visitor_id` and `signals`:

### `GET https://drn-api.fpjs.io/drn/{visitor_id}?signals={signals}`

We'll be using the `regional_activity` signal for our request by specifying it in the `signals` URL query parameter. Before you can make the request, you need to get a device `visitor_id`. You can [start a trial](http://dashboard.fingerprint.com/signup), run a sample project, and use your device `visitor_id` as a parameter. Once you have the `visitor_id` and the secret API key, build a curl request. The `visitor_id` goes in the path, `signals=regional_activity` as a query parameter, both `Authorization`, and `X-API-Version` as HTTP headers:

<CodeGroup>
  ```bash curl theme={"theme":"github-dark-dimmed"}
  curl --request GET \
    --url 'https://drn-api.fpjs.io/drn/{visitor-id-from-your-app}?signals=regional_activity' \
    --header 'Authorization: Bearer {secret-api-key}' \
    --header 'X-API-Version: 2024-09-01'
  ```

  ```bash wget theme={"theme":"github-dark-dimmed"}
  wget --method GET \
    --header 'X-API-Version: 2024-09-01' \
    --header 'Authorization: Bearer {secret-api-key}' \
    --output-document \
    - 'https://drn-api.fpjs.io/drn/{visitor_id}?signals=regional_activity'
  ```
</CodeGroup>

You will get a response with a list of countries where this device was active in the last 30 days:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "data": {
    "regionalActivity": {
      "startDate": "2024-08-06T23:00:13Z",
      "endDate": "2024-09-05T23:00:13Z",
      "countries": [
        {
          // this device was active in France via VPN and we detected it by IP
          "code": "FR",
          "detectors": [
            {
              "type": "ip",
              "activityPercentage": 0.20
            }
          ]
        },
        {
          // this device was also active in Russia and we detect it using our 
          // real location detection smart signal
          // /docs/smart-signals-overview#vpn-detection-for-mobile-devices
          "code": "RU",
          "detectors": [
            {
              "type": "origin",
              "activityPercentage": 1.0
            },
              {
              "type": "ip",
              "activityPercentage": 0.8
            }
          ]
        }
      ]
    }
  }
}
```

Even though you just identified this device in your app, you can get a **global** location history for any device in the Fingerprint network, including the **real location** even with VPN enabled!

### Rate limiting

DRN API is rate limited. **The** limit is enforced for every **Secret API key**, and the default rate limit per API key is **5 req/sec**. More details available in the [Rate limiting reference page](/reference/drn-api-rate-limiting). If you need a higher limit, reach out to [drn@fingerprint.com](mailto:drn@fingerprint.com).

### API client SDKs

SDKs for specific languages are coming soon! Email [drn@fingerprint.com](mailto:drn@fingerprint.com) if you want to request an SDK or integration for your stack.


# Rate limiting
Source: https://docs.fingerprint.com/reference/drn-api-rate-limiting

DRN API is rate limited. The limit is enforced for every , and the default rate limit per API key is **5 req/sec**.

If you exceed the rate limit when making a DRN API call, you'll get an HTTP 429 error:

```json JSON theme={"theme":"github-dark-dimmed"}
// HTTP 429
{
  "error": {
    "code": "http.too_many_requests",
    "message": "Too many requests"
  }
}
```

You can use the `Retry-After` response header to get the number of seconds after which you can retry your request.

If you need a higher limit, reach out to [drn@fingerprint.com](mailto:drn@fingerprint.com).


# Versioning
Source: https://docs.fingerprint.com/reference/drn-api-versioning

DRN API is *versioned*. When backwards-incompatible changes are made to the API, we release a new, dated version. The current version is `2024-09-01`.

Specifying API version is required to prevent breaking changes in the new versions breaking your integration. Any breaking changes will always be released as a new API version.

When making an API request, add `X-API-Version` HTTP header with the API version you’re using.

```text theme={"theme":"github-dark-dimmed"}
X-API-Version: 2024-09-01
```

```bash cURL theme={"theme":"github-dark-dimmed"}
curl -XGET -H 'Authorization: Bearer SECRET_API_KEY' -H 'X-API-Version: 2024-09-01'\
  'https://drn-api.fpjs.io/drn/...'
```

Requests without a valid API version will return `HTTP 400` error.

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "error": {
    "code": "version_not_found",
    "message": "version is not found"
  }
}
```

Before upgrading to a new API version, you should read the **[Changelog](/reference/drn-api-changelog)** to understand what breaking changes are included and to learn more about how to upgrade to the new API version.


# Create an environment
Source: https://docs.fingerprint.com/reference/environmentcontroller_create

reference/management-api_2025-11-20.json POST /environments
Creates a new environment for the workspace associated with the Management API key. Maximum number of environments in defined by your plan limits. If you need additional environments, contact our support team.



# Delete an environment
Source: https://docs.fingerprint.com/reference/environmentcontroller_delete

reference/management-api_2025-11-20.json DELETE /environments/{id}
Deletes an environment with the given environment ID. You can only delete environments that don't have any active API keys associated with it.



# Update an environment
Source: https://docs.fingerprint.com/reference/environmentcontroller_update

reference/management-api_2025-11-20.json POST /environments/{id}
Updates an environment with the given environment ID. You can update the name, description, and limit settings.



# Overview
Source: https://docs.fingerprint.com/reference/management-api

Management API allows you to manage your Fingerprint account and workspaces programmatically from a server environment.

Management API is only for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device.

<Check>
  **Management API requests do not count toward your monthly plan and are not billed.**
</Check>

# Getting started

Management API is available globally:

| Region | Base URL                         |
| ------ | -------------------------------- |
| Global | `https://management-api.fpjs.io` |

You can use Management API for all your workspaces, regardless of their region.

### Authentication

Management API requests are authorized by using the **Management API key** that can be obtained in your Fingerprint Dashboard by visiting **[API Keys](https://dashboard.fingerprint.com/api-keys)**.

Set your API key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer your-management-api-key
```

Read more about [Authentication](/reference/management-api-authentication).

### Version

Management API is versioned by date of the backwards-incompatible change made to the API. The latest version is `2025-11-20`.

Set the version as in the `X-API-Version` header:

```
X-API-Version: 2025-11-20
```

Read more about [Versioning](/reference/management-api-versioning).

### Making a request

Now we're ready to make our first request!

We can try to list all our environments by calling `GET https://management-api.fpjs.io/environments`. Note the added `Authorization` and `X-API-Version` headers.

```bash cURL theme={"theme":"github-dark-dimmed"}
curl -XGET -H 'Authorization: Bearer your-management-api-key' -H 'X-API-Version: 2024-05-20' 'https://management-api.fpjs.io/environments'
```

You should get a response listing all your workspace environments:

```json JSON theme={"theme":"github-dark-dimmed"}
{
  "data": [
    {
      "id": "env_ff035a1dd7655da15295fa5fa89362a7",
      "name": "Default environment",
      "created_at": "2023-10-05T14:48:00.000Z"
    }
  ]
}
```

And you're all set! Feel free to explore other methods available in Management API.

### Rate limiting

Management API is rate limited. The limit is enforced for every **Management API key**, and the default rate limit per API key is **5 req/sec**.

If you are an [Enterprise plan](https://fingerprint.com/pricing/) customer and your use case requires a higher limit, please reach out to our [support team](https://fingerprint.com/support/).

### Client SDKs

SDKs for specific languages are coming soon!

# Using API reference

You can try calling the Management API directly from this documentation:

1. Go to one listed API methods, for example **[List environments](/reference/2024-05-20-environmentcontroller_findall)**.
2. Set your API key as **Authorization**  bearer token.
3. Set API version by setting **X-API-Version** header to `2025-11-20`.
4. Click **Try it!**.

A real API response will appear in the **Response** section.

# Other resources

<Info>
  If you want to get information about visitors and identification events, check the [Server API](/reference/server-api) .

  If you want to identify browsers in your web application, read our [JavaScript agent guide](/reference/js-agent).

  If you want to identify mobile devices using native mobile SDKs, see [Android](/docs/native-android-integration) or [iOS](/docs/ios).
</Info>


# Authentication
Source: https://docs.fingerprint.com/reference/management-api-authentication

Management API requests are authorized by using the **Management API key**.

You can create one in your Fingerprint Dashboard by visiting **[API Keys](https://dashboard.fingerprint.com/api-keys)**, and opening **Management API** tab.

<Warning>
  **Your API key can be used to make changes to your Fingerprint account, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.**
</Warning>

Authentication is facilitated with **Bearer authentication** (also called token authentication), and it involves providing the API key as authorization token. The caller must send this token in the `Authorization` header when making requests to Management API.

When making an API request, add `Authorization` HTTP header with your Management API key.

```
Authorization: Bearer your-management-api-key
```

```bash cURL theme={"theme":"github-dark-dimmed"}
curl -XGET -H 'Authorization: Bearer your-management-api-key' -H 'X-API-Version: 2025-11-20' 'https://management-api.fpjs.io/hello'
```

Requests without a valid Authorization header will return `HTTP 401` error.


# Changelog
Source: https://docs.fingerprint.com/reference/management-api-changelog

This changelog lists all additions and updates to the Management API, in chronological order.

## Version 2025-11-20

**Breaking changes**

* Adds support for managing [Filtering Rules V2](/docs/request-filtering-v2).
* Standardizes response format for all routes to use `snake_case` exclusively.

**Non-breaking changes**

* *\[Aug 26th, 2026]* Adds general support for managing [custom subdomains](/docs/custom-subdomain-setup) (`subdomains`).

## Version 2024-05-20

* Initial release.
* Adds general support for managing API keys (`api-keys`).
* Adds general support for managing environments (`environments`).
* Adds general support for managing request filtering rules (`filtering-rules`).

**Non-breaking changes**

* *\[Oct 1st, 2025]* Adds general support for managing webhooks (`webhooks`)


# Pagination
Source: https://docs.fingerprint.com/reference/management-api-pagination



Some API resources have support for bulk fetches through “list” API methods. For example, you can list environments, list API keys, etc. These list API methods share a common structure and accept the following two parameters: `limit` and `cursor`.

Management API list methods use cursor-based pagination through the `cursor` parameter. After fetching the first page of resources, the response body will contain `metadata` information containing `next_cursor` token used to navigate to the next page.

```json JSON theme={"theme":"github-dark-dimmed"}
"metadata": {
    "pagination": {
      "nextCursor": "938c2cc0dcc05f2b68c4287040cfcf71",
      "prevCursor": null
    }
  }
```

To navigate to the next page, simply put this cursor token in the URL query for the next request:

```html URL query theme={"theme":"github-dark-dimmed"}
?limit=10&cursor=938c2cc0dcc05f2b68c4287040cfcf71
```

If you've already navigated forward, you can also use `prev_cursor` token from the response metadata to navigate backwards.


# Versioning
Source: https://docs.fingerprint.com/reference/management-api-versioning

Management API is *versioned*. When backwards-incompatible changes are made to the API, we release a new, dated version.

**The latest version is `2025-11-20`.**

Specifying API version is required to prevent breaking changes in the new versions breaking your integration. Any breaking changes will always be released in a new API version.

When making an API request, add `X-API-Version` HTTP header with the API version you’re using.

```
X-API-Version: 2025-11-20
```

```curl cURL theme={"theme":"github-dark-dimmed"}
curl -XGET -H 'Authorization: Bearer SECRET_API_KEY' -H 'X-API-Version: 2025-11-20' 'https://management-api.fpjs.io/hello'
```

Requests without a valid API version will return `HTTP 400` error.

Before upgrading to a new API version, you should read the **[Changelog](/reference/management-api-changelog)** to understand what breaking changes are included and to learn more about how to upgrade to a new API version.


# Migrating from Server API v3 to v4
Source: https://docs.fingerprint.com/reference/migrating-from-server-api-v3-to-v4

Learn how to migrate your integration from the deprecated Server API v3 endpoints to the new, improved Server API v4. This guide covers endpoint changes, authentication updates, and best practices for a smooth transition.

We are dedicated to providing the best and cleanest APIs possible. Our existing [Server API](/reference/v3/server-api) (v3) and Webhooks formats had inconsistencies and legacy baggage from our rapid growth. That's why we are introducing a new major iteration of our Server API and Webhooks. Read on to learn about the most important changes.

## Server SDK compatibility for Server API v4

| Server SDK                                                                          | Support status | Minimum version with v4 support                                                                     |
| ----------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| [Node Server SDK](/reference/node-server-sdk#migration-guide-for-node-sdk-v7)       | ✅ Supported    | [v7.0.0+](https://github.com/fingerprintjs/node-sdk/releases/tag/%40fingerprint%2Fnode-sdk%407.0.0) |
| [Python Server SDK](/reference/python-server-sdk#migration-guide-for-python-sdk-v9) | ✅ Supported    | [v9.0.0+](https://github.com/fingerprintjs/python-sdk/releases/tag/v9.0.0)                          |
| [Java Server SDK](/reference/java-server-sdk#migration-guide-for-java-sdk-v8)       | ✅ Supported    | [v8.0.0+](https://github.com/fingerprintjs/java-sdk/releases/tag/v8.0.0)                            |
| [.NET Server SDK](/reference/net-server-sdk#migration-guide-for-net-sdk-v8)         | ✅ Supported    | [v8.0.0+](https://github.com/fingerprintjs/dotnet-sdk/releases/tag/v8.0.0)                          |
| [PHP Server SDK](/reference/php-server-sdk#migration-guide-for-php-sdk-v7)          | ✅ Supported    | [v7.0.0+](https://github.com/fingerprintjs/php-sdk/releases/tag/v7.0.0)                             |
| [Go Server SDK](/reference/go-server-sdk#migration-guide-for-go-sdk-v8)             | ✅ Supported    | [v8.0.0+](https://github.com/fingerprintjs/go-sdk/releases/tag/v8.0.0)                              |

# What's new

* Removed excessive nesting in responses. Payloads are no longer nested under top-level `data` and `products`, including at individual Smart Signals level (removed `result`). This makes the format and generated documentation clearer and easier to consume.
  * See [example V3 Event response](/reference/v3/server-api-get-event), [v3 OpenAPI schema](https://fingerprintjs.github.io/fingerprint-pro-server-api-openapi/schemas/fingerprint-server-api.yaml).
  * See [example V4 Event response](/reference/server-api-get-event), [v4 full OpenAPI schema](https://fingerprintjs.github.io/fingerprint-pro-server-api-openapi/schemas/fingerprint-server-api-v4.yaml).
* Unified Webhooks and Server API (events format). All Server API responses now share the same data format described in our public documentation. [Sealed Client Results](/docs/sealed-client-results) use the same format with [JavaScript agent v4](/reference/js-agent).
* **Deprecated** the `/visitors` search endpoint in favor of `/v4/events` (which provides the same and more functionality). This legacy endpoint will be removed.
* Introduced more descriptive error codes and messages. Errors now include suggestions and links to relevant documentation where applicable.
* Removed the possibility of partial payloads when an internal service fails (previously it was possible to receive Identification data with Smart Signals errors). Unreliable partial responses are replaced with a clear error instead.
* Properties are omitted from events if they are not supported for the platform they were generated on. In v3, properties were set to `null` or `false` instead.
* Replaced the `Auth-Api-Key` header and `apiKey` parameter with the standard `Authorization: Bearer` header. Existing secret API keys work with this header without issues.
* Upgraded the OpenAPI version and started using an OpenAPI definition for Webhooks alongside the rest of the Server API documentation.
* Removed the `Retry-After` header as it did not work well with our rate limiting logic.
* Renamed `request_id` to `event_id`.
* Unified usage of `snake_case` across URLs and request/response payload fields.

# Migration Overview

<Warning>
  **Deprecation Notice**

  The [previous version of Server API](/reference/v3/server-api) was deprecated. If you still use this version, follow this guide to migrate from this deprecated version to the new one. The [one year deprecation period](/reference/api-deprecation-policy#one-year-migration-period) will start after the entire ecosystem supports API v4.
</Warning>

| v3 endpoint            | v4 endpoint                | action                                                 |
| ---------------------- | -------------------------- | ------------------------------------------------------ |
| `GET /visitors`        | `GET /v4/events`           | migrate to `GET /v4/events`                            |
| `GET /events`          | `GET /v4/events/:event_id` | migrate to `GET /v4/events/:event_id`                  |
| `PUT /events` (update) | `PATCH /v4/event`          | migrate to `PATCH /v4/event`                           |
| `GET /events/search`   | `GET /v4/events`           | migrate to `GET /v4/events`                            |
| Webhooks v3            | Webhooks v4                | configure new webhooks via Dashboard or Management API |

# How to migrate from v3 to v4

Migration needs depend on which deprecated endpoints you are using. If you are not using Server API or Webhooks, there is nothing to migrate today. For JavaScript agent changes, see [Migrating JavaScript agent from v3 to v4](/reference/migrating-from-v3-to-v4).

## Migrating GET /visitors

The `GET /visitors` endpoint is fully replaced by `/v4/events`, which is an extended version of the v3 `/events/search` endpoint.

* In `v4`, use filters such as `visitor_id`, `linked_id`, `suspect`, `start`, and `end` to get the same results.
* Latency differences: `/visitors` had latency independent of event age. In `/v4/events`, most recent events (≤24h) are served from cache and are very fast. Older events may take longer to load from archival storage.
* To minimize latency, always pass a time window with `start` and `end`.

<CodeGroup>
  ```bash v3 (/visitors) to v4 (/v4/events) theme={"theme":"github-dark-dimmed"}
  curl --request GET \
       --url "https://api.fpjs.io/v4/events?start=1725148800&end=1727731199" # [!code ++]
       --url "https://api.fpjs.io/visitors?limit=100" # [!code --] 
       --header 'Accept: application/json' \
       --header 'Authorization: Bearer SECRET_API_KEY' # [!code ++]
       --header 'Auth-Api-Key: SECRET_API_KEY' # [!code --]
  ```
</CodeGroup>

## Migrating GET /events

The current version of `GET /events` uses the old nested event format and the old `Auth-Api-Key` header. To migrate to the new `/v4/event` endpoint, you have to

1. Start using the `Authorization: Bearer SECRET_API_KEY` header for authorization
2. Migrate to the new format, either by using our Server SDKs or adopting the model to the v4 [specification](/reference/server-api-get-event)

## Migrating GET /events/search

The current version of `GET /events/search` uses the old nested event format and the old `Auth-Api-Key` header. To migrate to the new `/v4/events` endpoint, you have to

1. Start using the `Authorization: Bearer SECRET_API_KEY` header for authorization
2. Migrate to the new format, either by using our Server SDKs or adopting the model to the v4 [specification](/reference/server-api-search-events)

## Migrating UPDATE /events

The update operation remains conceptually the same, but method, path, auth header, and some field names have changed.

1. Exchange the `Auth-Api-Key: SECRET_API_KEY` header for `Authorization: Bearer SECRET_API_KEY`
2. Change the method from `PUT` to `PATCH`
3. Update the path to `/v4/events/:event_id`
4. Rename fields to `snake_case` (e.g., `linkedId` -> `linked_id`)
5. (optional) Check the documentation for new error codes and adapt your implementation to handle them

<CodeGroup>
  ```bash v3 to v4 theme={"theme":"github-dark-dimmed"}
    curl --request PATCH # [!code ++]
    curl --request PUT # [!code --]
       --url https://api.fpjs.io/v4/events/:event_id # [!code ++]
       --url https://api.fpjs.io/events # [!code --]
       --header 'Accept: application/json' \
       --header 'Content-type: application/json' \
       --header 'Authorization: Bearer SECRET_API_KEY' # [!code ++]
       --header 'Auth-Api-Key: SECRET_API_KEY' # [!code --]

       --data '
      {
        "linked_id": "<user_id>" [!code ++]
        "linkedId": "<user_id>" [!code --]
      }'

  ```
</CodeGroup>

## Response Fields Mapping

The following tables describe the field names in API v3 and their API v4 equivalents.

### Core and Identification Fields

This table maps the nested `products.identification.data.*` fields to the top-level of the v4 API response.

| v3                                       | v4                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------- |
| `requestId`                              | `event_id`                                                                      |
| `timestamp`                              | `timestamp`                                                                     |
| `time` (ISO-8601)                        | removed                                                                         |
| `tag`                                    | `tags`                                                                          |
| `linkedId`                               | `linked_id`                                                                     |
| `sdk`                                    | `sdk`                                                                           |
| `environmentId`                          | `environment_id`                                                                |
| `visitorId`                              | `identification.visitor_id`                                                     |
| `confidence.score`                       | `identification.confidence.score`                                               |
| `confidence.revision`                    | `identification.confidence.version` (renamed)                                   |
| `confidence.comment`                     | `identification.confidence.comment`                                             |
| `visitorFound`                           | `identification.visitor_found`                                                  |
| `firstSeenAt` / `lastSeenAt` (ISO-8601)  | `identification.first_seen_at` / `last_seen_at` (Unix millis int64)             |
| `ip`                                     | `ip_address`                                                                    |
| `ipLocation`                             | `ip_info.(v4,v6).geolocation`                                                   |
| `url`                                    | `url` (browser) / `bundle_id` (iOS) / `package_name` (Android) — platform-gated |
| `browserDetails.userAgent`               | `user_agent`                                                                    |
| `browserDetails.{device, os, osVersion}` | `device` / `os` / `os_version` **and** still nested under `browser_details`     |
| `incognito`                              | `incognito`                                                                     |
| `suspect`                                | `suspect`                                                                       |
| `replayed`                               | `replayed`                                                                      |

The `browserDetails.{browserName, browserMajorVersion, browserFullVersion}` fields have no v4 top-level equivalent field because these parsed values are only valid for browsers. They remain accessible under the `browser_details` field.

### Bot Detection, Smart Signals and Other Fields

This table maps the nested `products.<name>.data.*` fields to the top-level of the v4 API response.

| v3                                                                      | v4                                                                                  |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `botd.data.{bot, type}`                                                 | `bot`, `bot_type`, `bot_info`                                                       |
| `vpn.data.{result, confidence, methods, originCountry, originTimezone}` | `vpn`, `vpn_confidence`, `vpn_methods`, `vpn_origin_country`, `vpn_origin_timezone` |
| `proxy.data.{result, confidence, details, mlScore}`                     | `proxy`, `proxy_confidence`, `proxy_details`, `proxy_ml_score`                      |
| `tampering.data.{result, confidence, details, mlScore}`                 | `tampering`, `tampering_confidence`, `tampering_details`, `tampering_ml_score`      |
| `tor.data.result`                                                       | `ip_blocklist { email_spam, attack_source }`                                        |
| `ipBlocklist.data.details.{emailSpam, attackSource}`                    | `ip_blocklist { tor_node }`                                                         |
| `ipInfo.data.*`                                                         | `ip_info`                                                                           |
| `incognito.data.result`                                                 | `incognito`                                                                         |
| `jailbroken.data.result`                                                | `jailbroken`                                                                        |
| `frida.data.result`                                                     | `frida`                                                                             |
| `rootApps.data.result`                                                  | `root_apps`                                                                         |
| `emulator.data.result`                                                  | `emulator`                                                                          |
| `clonedApp.data.result`                                                 | `cloned_app`                                                                        |
| `factoryReset.data.time`                                                | `factory_reset_timestamp`                                                           |
| `privacySettings.data.result`                                           | `privacy_settings`                                                                  |
| `virtualMachine.data.{result, mlScore}`                                 | `virtual_machine`, `virtual_machine_ml_score`                                       |
| `mitmAttack.data.result`                                                | `mitm_attack`                                                                       |
| `locationSpoofing.data.result`                                          | `location_spoofing`                                                                 |
| `developerTools.data.result`                                            | `developer_tools`                                                                   |
| `suspectScore.data.result`                                              | `suspect_score`                                                                     |
| `highActivity.data.result`                                              | `high_activity_device`                                                              |
| `rareDevice.data.{result, percentileBucket}`                            | `rare_device`, `rare_device_percentile_bucket`                                      |
| `velocity.data.*`                                                       | `velocity`                                                                          |
| `proximity.data.*`                                                      | `proximity`                                                                         |
| `rawDeviceAttributes.data.*`                                            | `raw_device_attributes`                                                             |
| `remoteControl` (deprecated in v3)                                      | removed                                                                             |

## Migrating Webhooks

Webhooks v4 follow the same format as `/v4/events`, so you can reuse most of the code used with other Server API endpoints.

* See [v3 legacy webhook payload](/docs/webhooks#legacy-webhook-payload)
* See [v4 webhook payload](/reference/posteventwebhook)

You can manage both new and legacy Webhooks in the Dashboard. To migrate your legacy webhook to v4, you need to re-create it, and then delete the legacy webhook.

<img alt="" />

Alternatively, you can create Webhooks v4 via Management API. Follow this basic example to create a Webhook:

<CodeGroup>
  ```bash Create v4 Webhook theme={"theme":"github-dark-dimmed"}
  curl --request POST \
       --url https://management-api.fpjs.io/webhooks \
       --header 'Accept: application/json' \
       --header 'Content-type: application/json' \
       --header 'Authorization: Bearer SECRET_API_KEY' \
       --data '
      {
      "url": "https://example.com",
      "description": "My example v4 webhook",
      "status": "enabled"
      }'
  ```
</CodeGroup>

Review the Management API documentation on [Webhooks](/reference/webhookscontroller_findallv2/) for more detail about how to manage webhooks.

<Note>
  ### Set up the old and the new webhook side by side

  We recommend setting up a new webhook alongside the old one. Create a new webhook through the Management API mentioned above, integrate it, test that it delivers the new information correctly, and then remove the old one without any loss of data.
</Note>


# Register a subdomain
Source: https://docs.fingerprint.com/reference/subdomainscontroller_create

reference/management-api_2025-11-20.json POST /subdomains
Register a new custom subdomain and receive its DNS records. Optionally pass `webhook_url` to get a signed POST callback on every status change instead of polling; the signing secret is returned once in this response as `webhook_secret`.

Every DNS record you need is returned in this response at once: the verification `CNAME` record and the two routing `A` records. You can add them all to your DNS provider in a single pass. The `A` records start routing traffic only after your certificate is issued, so adding them early is safe.

Optionally pass a `webhook_url` to receive a signed `POST` callback each time the subdomain's status changes, instead of polling [Get subdomain](/reference/subdomainscontroller_findone). The `webhook_secret` used to verify those callbacks is returned only in this response, so store it now. It can't be retrieved later.

Subdomains are immutable. To change a subdomain, [delete it](/reference/subdomainscontroller_delete) and register a new one.

See the [Custom subdomain setup](/docs/custom-subdomain-setup#manage-subdomains-with-the-management-api) guide for the full flow.


# Delete subdomain
Source: https://docs.fingerprint.com/reference/subdomainscontroller_delete

reference/management-api_2025-11-20.json DELETE /subdomains/{id}
Delete a subdomain by ID.

Deletes the subdomain and revokes its SSL certificate. This action is irreversible.

Deleting a subdomain whose status is `active` stops routing its traffic to Fingerprint. Any JavaScript agent still configured with this subdomain as its [`endpoints`](/reference/js-agent-start-function#endpoints) will fail to identify visitors, so update your agent configuration before you delete a subdomain that's in use.

Note: Does not support `Legacy` subdomains. Migrate old certificates via the Dashboard to manage them via API.


# List subdomains
Source: https://docs.fingerprint.com/reference/subdomainscontroller_findall

reference/management-api_2025-11-20.json GET /subdomains
Lists all custom subdomains for the workspace associated with the Management API key.

Returns a compact representation of each subdomain, without DNS records. Use [Get subdomain](/reference/subdomainscontroller_findone) to retrieve the DNS records and full details for a single subdomain.

Filter by `status` to narrow the results, and use the `cursor` and `limit` parameters to page through them. See [Pagination](/reference/management-api-pagination) for details.

Note: Does not support `Legacy` subdomains. Migrate old certificates via the Dashboard to manage them via API.


# Get subdomain
Source: https://docs.fingerprint.com/reference/subdomainscontroller_findone

reference/management-api_2025-11-20.json GET /subdomains/{id}
Fetch a subdomain by ID.

Returns the full subdomain, including its DNS records and current status. Poll this endpoint to track a subdomain's progress until its status is `active`, or configure a `webhook_url` when you [register the subdomain](/reference/subdomainscontroller_create) to receive status changes without polling.

See [Subdomain statuses](/docs/custom-subdomain-setup#subdomain-statuses) for what each status means.

Note: Does not support `Legacy` subdomains. Migrate old certificates via the Dashboard to manage them via API.


# Verify subdomain
Source: https://docs.fingerprint.com/reference/subdomainscontroller_verify

reference/management-api_2025-11-20.json POST /subdomains/{id}/verify
Trigger manual verification for a subdomain.

Triggers an on-demand DNS check instead of waiting for the next background check. Use it right after you add your DNS records to move the subdomain forward without waiting.

This endpoint is idempotent: if the check doesn't advance the subdomain, or the subdomain is already `active`, it still returns `200` with the current state. It's rate limited per subdomain, so call it sparingly rather than in a tight loop. To poll for status, use [Get subdomain](/reference/subdomainscontroller_findone) instead.


# Create a webhook
Source: https://docs.fingerprint.com/reference/webhookscontroller_create

reference/management-api_2025-11-20.json POST /webhooks
Creates a new webhook in the workspace associated with the Management API key.
Webhook needs to be verified before it will start sending identification events to your server. See webhook verification.
If webhook signatures are enabled (enterprise only), signing key will be visible in the response after creation. When fetching webhooks after creation, signing key will not be visible!
See webhooks documentation for more details.
When specifying an environment during creation, webhook should be assigned to the given environment. Setting environment to null creates a global webhook.

Webhook needs to be [verified](/reference/webhookscontroller_verify/) before it will start sending identification events to your server.

The response will include a [signing key](/docs/webhooks#webhook-signatures). When fetching webhooks after creation, signing key will not be visible!

When specifying an environment during creation, webhook will report events only from an associated environment. Setting environment to null creates a workspace-scoped webhook that reports on all events.

See [webhooks](/docs/webhooks/) documentation for more details.


# Get webhook by ID
Source: https://docs.fingerprint.com/reference/webhookscontroller_findone

reference/management-api_2025-11-20.json GET /webhooks/{id}
Fetch a specific webhook by ID.



# Delete webhook
Source: https://docs.fingerprint.com/reference/webhookscontroller_remove

reference/management-api_2025-11-20.json DELETE /webhooks/{id}
Deletes the webhook with the given ID. This action is not reversible. Changes will take affect in a few minutes.



# Update webhook
Source: https://docs.fingerprint.com/reference/webhookscontroller_update

reference/management-api_2025-11-20.json PATCH /webhooks/{id}
Updates the webhook with the given ID. You can update the name, description, status, URL, and set basic authentication.
Changing the URL will require this webhook to be verified again.
Changing the status will disable/enable sending of identification events to your webhook.

You can update the `name`, `description`, `status`, `URL`.

Changing the URL will require this webhook to be verified again.

Changing the status will disable/enable sending of identification events to your webhook.


# Verify webhook
Source: https://docs.fingerprint.com/reference/webhookscontroller_verify

reference/management-api_2025-11-20.json POST /webhooks/{id}/verification
Send a mocked test event in order to verify your webhook endpoint, it needs to respond with HTTP 200 to be verified.
Webhook needs to be verified before it will receive identification events.

---

# Fingerprint API Reference

Complete API reference generated from the Fingerprint OpenAPI specifications. Includes all endpoints, parameters (with types, required status, defaults), request bodies, and response schemas.

## Fingerprint Server API v4
Source: https://docs.fingerprint.com/reference/server-api-v4
Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios.
Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mob
Base URL: `https://api.fpjs.io/v4`

**Authentication:**
- bearerAuth: http

### POST /edge
**Collect Automation Intelligence.**
The Automation Intelligence API gives you the tools to determine whether traffic is legitimate and should be accepted by your application.

This feature is currently in a Public Preview testing phase. All feedback is welcome! If you encounter any issues, please [contact our support team](https://fingerprint.com/support/).

The API detects automation tools like AI Agents, AI Assistants, AI Browsers, and other bots. Additionally, it provides IP intelligence like geolocation, residential proxy, VPN...
Full URL: `https://api.fpjs.io/v4/edge`
Tags: Edge

**Request Body:**
Content-Type: `application/json`
- `headers` (array of object) (required): Ordered header entries from the request made to your server. Each entry represents one header line. If one header name appears as multiple lines, send each as a separate item in the array.
  - `name` (string) (required): Header name as forwarded by your server. Headers must be valid according to RFC 7230 and will be canonicalized according to RFC 9112.
  - `value` (string) (required): Value of a single forwarded header entry. Be careful to preserve the original encoding and escaping. For example, do not double escape quotes.
- `method` (string) (required): The original HTTP method of the request. If supported in your runtime, preserve the original casing.
- `url` (string uri) (required): Absolute URL of the request, without a \#fragment suffix. Only HTTP and HTTPS schemes are supported.
- `ipv4_address` (string ipv4): Client IPv4 address observed by your server.
- `ipv6_address` (string ipv6): Client IPv6 address observed by your server.
- `linked_id` (string): A customer-provided ID that was sent with the request.
- `tags` (object): A customer-provided value or an object that was sent with the identification request or updated later.

**Responses:**
- `200`: OK.
  - `event_id` (string) (required): Unique identifier of the user's request. The first portion of the event_id is a unix epoch milliseconds timestamp.
  - `timestamp` (integer int64) (required): Timestamp of the event with millisecond precision in Unix time.
  - `source` (enum: device | edge): Identifies how the event was generated.
  - `linked_id` (string): A customer-provided ID that was sent with the request.
  - `tags` (object): A customer-provided value or an object that was sent with the identification request or updated later.
  - `url` (string): Page URL from which the request was sent.
  - `bot_info` (object): Extended bot information.
    - `category` (enum: advertising_and_marketing | aggregator | ai_agent | ai_assistant | ai_browser | ai_crawler | ai_search | browser_automation | ecommerce | monitoring_and_analytics | other | scraping | security | search_engine_crawler | search_engine_optimization | unknown) (required): The type and purpose of the bot.
    - `provider` (string) (required): The organization or company operating the bot.
    - `provider_url` (string): The URL of the bot provider's website.
    - `name` (string) (required): The specific name or identifier of the bot.
    - `identity` (enum: verified | signed | spoofed | unknown) (required): The verification status of the bot's identity:
    - `confidence` (enum: low | medium | high) (required): Confidence level of the bot identification.
  - `ip_info` (object) (required): Details about the request IP address. Has separate fields for v4 and v6 IP address versions.
    - `v4` (object): 
      - `address` (string ipv4) (required): 
      - `geolocation` (object): 
        - `accuracy_radius` (integer): The IP address is likely to be within this radius (in km) of the specified location.
        - `latitude` (number double): 
        - `longitude` (number double): 
        - `postal_code` (string): 
        - `timezone` (string timezone): 
        - `city_name` (string): 
        - `country_code` (string): 
        - `country_name` (string): 
        - `continent_code` (string): 
        - `continent_name` (string): 
        - `subdivisions` (array of object): 
      - `asn` (string): 
      - `asn_name` (string): 
      - `asn_network` (string): 
      - `asn_type` (string): 
      - `datacenter_result` (boolean): When true, the request originated from a datacenter.
      - `datacenter_name` (string): 
    - `v6` (object): 
      - `address` (string ipv6) (required): 
      - `geolocation` (object): 
        - `accuracy_radius` (integer): The IP address is likely to be within this radius (in km) of the specified location.
        - `latitude` (number double): 
        - `longitude` (number double): 
        - `postal_code` (string): 
        - `timezone` (string timezone): 
        - `city_name` (string): 
        - `country_code` (string): 
        - `country_name` (string): 
        - `continent_code` (string): 
        - `continent_name` (string): 
        - `subdivisions` (array of object): 
      - `asn` (string): 
      - `asn_name` (string): 
      - `asn_network` (string): 
      - `asn_type` (string): 
      - `datacenter_result` (boolean): When true, the request originated from a datacenter.
      - `datacenter_name` (string): 
  - `proxy` (boolean): IP address was used by a public proxy provider or belonged to a known recent residential proxy
  - `proxy_confidence` (enum: low | medium | high): Confidence level of the proxy detection. If a proxy is not detected, confidence is "high". If it's detected, can be "low", "medium", or "high".
  - `proxy_details` (object): Proxy detection details (present if `proxy` is `true`)
    - `proxy_type` (enum: residential | data_center | unknown) (required): Proxy type:
    - `last_seen_at` (integer int64): Unix millisecond timestamp with hourly resolution of when this IP was last seen as a proxy
    - `provider` (string): String representing the last proxy service provider detected when this
  - `vpn` (boolean): VPN or other anonymizing service has been used when sending the request.
  - `vpn_confidence` (enum: low | medium | high): A confidence rating for the VPN detection result — "low", "medium", or "high". Depends on the combination of results returned from all VPN detection methods.
  - `vpn_methods` (object): 
    - `timezone_mismatch` (boolean): The browser timezone doesn't match the timezone inferred from the request IP address.
    - `public_vpn` (boolean): Request IP address is owned and used by a public VPN service provider.
    - `auxiliary_mobile` (boolean): This method applies to mobile devices only. Indicates the result of additional methods used to detect a VPN in mobile devices.
    - `os_mismatch` (boolean): The browser runs on a different operating system than the operating system inferred from the request network signature.
    - `relay` (boolean): Request IP address belongs to a relay service provider, indicating the use of relay services like [Apple Private relay](https://support.apple.com/en-us/102602) or [Cloudflare Warp](https://developers.cloudflare.com/warp-client/).
    - `ml_prediction` (boolean): `true` if the request came from a device running a VPN, `false` otherwise.
- `400`: Bad request. The request payload is not valid.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `403`: Forbidden. Access to this API is denied.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `413`: Bad request. The request payload is too large.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `429`: Too Many Requests. The request is throttled.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `500`: Workspace error.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 

### GET /events/{event_id}
**Get an event by event ID**
Get a detailed analysis of an individual identification event, including Smart Signals.

Use `event_id` as the URL path parameter. This API method is scoped to a request, i.e. all returned information is by `event_id`.
Full URL: `https://api.fpjs.io/v4/events/{event_id}`
Tags: Events

**Parameters:**
- `event_id` [path] (string) (required): The unique [identifier](https://docs.fingerprint.com/reference/js-agent-get-function#event_id) of each identification request (`requestId` can be used in its place).
- `ruleset_id` [query] (string) (optional): The ID of the ruleset to evaluate against the event, producing the action to take for this event. The resulting action is returned in the `rule_action` attribute of the response.

**Responses:**
- `200`: OK.
  - `event_id` (string) (required): Unique identifier of the user's request. The first portion of the event_id is a unix epoch milliseconds timestamp.
  - `timestamp` (integer int64) (required): Timestamp of the event with millisecond precision in Unix time.
  - `source` (enum: device | edge): Identifies how the event was generated.
  - `incremental_identification_status` (enum: partially_completed | completed): Only included for requests using incremental identification.
  - `linked_id` (string): A customer-provided ID that was sent with the request.
  - `environment_id` (string): Environment ID of the event.
  - `suspect` (boolean): Field is `true` if you have previously set the `suspect` flag for this event using the [Server API Update event endpoint](https://docs.fingerprint.com/reference/server-api-update-event).
  - `sdk` (object): Contains information about the SDK used to perform the request.
    - `platform` (enum: js | android | ios | unknown) (required): Platform of the SDK used for the identification request.
    - `version` (string) (required): Version string of the SDK used for the identification request.
    - `integrations` (array of object): 
      - `name` (string): The name of the specific integration.
      - `version` (string): The version of the specific integration.
      - `subintegration` (object): 
        - `name` (string): The name of the specific subintegration.
        - `version` (string): The version of the specific subintegration.
  - `replayed` (boolean): `true` if we determined that this payload was replayed, `false` otherwise.
  - `identification` (object): 
    - `visitor_id` (string) (required): String of 20 characters that uniquely identifies the visitor's browser or mobile device.
    - `confidence` (object): The confidence score represents the probability of a false-positive identification. To learn more, visit [Confidence Score](https://docs.fingerprint.com/docs/identification-accuracy-and-confidence#confidence-score). Please note that the confidence score is not yet supported for [High Recall ID](https://docs.fingerprint.com/docs/supplementary-identifiers-highrecall).
      - `score` (number double) (required): A floating-point number between 0 and 1 that represents the probability of a false-positive identification. For High Recall ID, this value is 0.
      - `version` (string): The version name of the method used to calculate the confidence score. For High Recall ID, this value is "Not Supported".
      - `comment` (string): 
    - `visitor_found` (boolean) (required): Attribute represents if a visitor had been identified before.
    - `first_seen_at` (integer int64): Unix epoch time milliseconds timestamp indicating the time at which this visitor ID was first seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000
    - `last_seen_at` (integer int64): Unix epoch time milliseconds timestamp indicating the time at which this visitor ID was last seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000
  - `supplementary_id_high_recall` (object): The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental.
    - `visitor_id` (string) (required): The High Recall identifier for the visitor's browser. It is an alphanumeric string with a maximum length of 25 characters.
    - `visitor_found` (boolean) (required): True if this is a returning browser and has been previously identified. Otherwise, false.
    - `confidence` (object): The confidence score represents the probability of a false-positive identification. To learn more, visit [Confidence Score](https://docs.fingerprint.com/docs/identification-accuracy-and-confidence#confidence-score). Please note that the confidence score is not yet supported for [High Recall ID](https://docs.fingerprint.com/docs/supplementary-identifiers-highrecall).
      - `score` (number double) (required): A floating-point number between 0 and 1 that represents the probability of a false-positive identification. For High Recall ID, this value is 0.
      - `version` (string): The version name of the method used to calculate the confidence score. For High Recall ID, this value is "Not Supported".
      - `comment` (string): 
    - `first_seen_at` (integer int64): Unix epoch timestamp (in milliseconds) indicating when the browser was first identified. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000
    - `last_seen_at` (integer int64): Unix epoch timestamp (in milliseconds) corresponding to the most recent visit by this browser. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000
  - `tags` (object): A customer-provided value or an object that was sent with the identification request or updated later.
  - `url` (string): Page URL from which the request was sent.
  - `bundle_id` (string): Bundle ID of the iOS application integrated with the Fingerprint SDK for the event.
  - `package_name` (string): Package name of the Android application integrated with the Fingerprint SDK for the event.
  - `ip_address` (string): IP address of the requesting browser or bot.
  - `user_agent` (string): User Agent of the client.
  - `device` (string): Device model or family extracted from the user agent string. On web, this field is also present inside `browser_details`.
  - `os` (string): Operating system family extracted from the user agent string. On web, this field is also present inside `browser_details`.
  - `os_version` (string): Operating system version string extracted from the user agent string. On web, this field is also present inside `browser_details`.
  - `client_referrer` (string): Client Referrer field corresponds to the `document.referrer` field gathered during an identification request. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, by using a bookmark).
  - `browser_details` (object): 
    - `browser_name` (string) (required): 
    - `browser_major_version` (string) (required): 
    - `browser_full_version` (string) (required): 
    - `os` (string) (required): 
    - `os_version` (string) (required): 
    - `device` (string) (required): 
  - `proximity` (object): Proximity ID represents a fixed geographical zone in a discrete global grid within which the device is observed.
    - `id` (string) (required): A stable privacy-preserving identifier for a given proximity zone.
    - `precision_radius` (enum: 10 | 25 | 65 | 175 | 450 | 1200 | 3300 | 8500 | 22500) (required): The radius of the proximity zone’s precision level, in meters.
    - `confidence` (number float) (required): A value between `0` and `1` representing the likelihood that the true device location lies within the mapped proximity zone.
  - `active_call` (boolean): Indicates whether the mobile device had an active call (cellular or VoIP) at the time of the request. Available from SDK 2.16.0+ on iOS and Android.
  - `bot` (enum: bad | good | not_detected): Bot detection result:
  - `bot_type` (string): Additional classification of the bot type if detected.
  - `bot_info` (object): Extended bot information.
    - `category` (enum: advertising_and_marketing | aggregator | ai_agent | ai_assistant | ai_browser | ai_crawler | ai_search | browser_automation | ecommerce | monitoring_and_analytics | other | scraping | security | search_engine_crawler | search_engine_optimization | unknown) (required): The type and purpose of the bot.
    - `provider` (string) (required): The organization or company operating the bot.
    - `provider_url` (string): The URL of the bot provider's website.
    - `name` (string) (required): The specific name or identifier of the bot.
    - `identity` (enum: verified | signed | spoofed | unknown) (required): The verification status of the bot's identity:
    - `confidence` (enum: low | medium | high) (required): Confidence level of the bot identification.
  - `cloned_app` (boolean): Android specific cloned application detection. There are 2 values: 
  - `developer_tools` (boolean): `true` if the browser has DevTools open (Chrome, Firefox) or the Android/iOS device has Developer Tools enabled, `false` otherwise.
  - `emulator` (boolean): Android specific emulator detection. There are 2 values: 
  - `factory_reset_timestamp` (integer int64): The time of the most recent factory reset that happened on the **mobile device** is expressed as Unix epoch time. When a factory reset cannot be detected on the mobile device or when the request is initiated from a browser,  this field will correspond to the *epoch* time (i.e 1 Jan 1970 UTC) as a value of 0. See [Factory Reset Detection](https://docs.fingerprint.com/docs/smart-signals-reference#factory-reset-detection) to learn more about this Smart Signal.
  - `frida` (boolean): [Frida](https://frida.re/docs/) detection for Android and iOS devices. There are 2 values:
  - `ip_blocklist` (object): 
    - `email_spam` (boolean): IP address was part of a known email spam attack (SMTP).
    - `attack_source` (boolean): IP address was part of a known network attack (SSH/HTTPS).
    - `tor_node` (boolean): IP address was part of known TOR network activity.
  - `ip_info` (object): Details about the request IP address. Has separate fields for v4 and v6 IP address versions.
    - `v4` (object): 
      - `address` (string ipv4) (required): 
      - `geolocation` (object): 
        - `accuracy_radius` (integer): The IP address is likely to be within this radius (in km) of the specified location.
        - `latitude` (number double): 
        - `longitude` (number double): 
        - `postal_code` (string): 
        - `timezone` (string timezone): 
        - `city_name` (string): 
        - `country_code` (string): 
        - `country_name` (string): 
        - `continent_code` (string): 
        - `continent_name` (string): 
        - `subdivisions` (array of object): 
      - `asn` (string): 
      - `asn_name` (string): 
      - `asn_network` (string): 
      - `asn_type` (string): 
      - `datacenter_result` (boolean): When true, the request originated from a datacenter.
      - `datacenter_name` (string): 
    - `v6` (object): 
      - `address` (string ipv6) (required): 
      - `geolocation` (object): 
        - `accuracy_radius` (integer): The IP address is likely to be within this radius (in km) of the specified location.
        - `latitude` (number double): 
        - `longitude` (number double): 
        - `postal_code` (string): 
        - `timezone` (string timezone): 
        - `city_name` (string): 
        - `country_code` (string): 
        - `country_name` (string): 
        - `continent_code` (string): 
        - `continent_name` (string): 
        - `subdivisions` (array of object): 
      - `asn` (string): 
      - `asn_name` (string): 
      - `asn_network` (string): 
      - `asn_type` (string): 
      - `datacenter_result` (boolean): When true, the request originated from a datacenter.
      - `datacenter_name` (string): 
  - `proxy` (boolean): IP address was used by a public proxy provider or belonged to a known recent residential proxy
  - `proxy_confidence` (enum: low | medium | high): Confidence level of the proxy detection. If a proxy is not detected, confidence is "high". If it's detected, can be "low", "medium", or "high".
  - `proxy_details` (object): Proxy detection details (present if `proxy` is `true`)
    - `proxy_type` (enum: residential | data_center | unknown) (required): Proxy type:
    - `last_seen_at` (integer int64): Unix millisecond timestamp with hourly resolution of when this IP was last seen as a proxy
    - `provider` (string): String representing the last proxy service provider detected when this
  - `proxy_ml_score` (number double): Machine learning–based proxy score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `proxy` detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
  - `incognito` (boolean): `true` if we detected incognito mode used in the browser, `false` otherwise.
  - `jailbroken` (boolean): iOS specific jailbreak detection. There are 2 values: 
  - `location_spoofing` (boolean): Flag indicating whether the request came from a mobile device with location spoofing enabled.
  - `mitm_attack` (boolean): * `true` - When requests made from your users' mobile devices to Fingerprint servers have been intercepted and potentially modified. 
  - `privacy_settings` (boolean): `true` if the request is from a privacy aware browser (e.g. Tor) or from a browser in which fingerprinting is blocked. Otherwise `false`.
  - `root_apps` (boolean): Android specific root management apps detection. There are 2 values: 
  - `rule_action` (object | object): Describes the action the client should take, according to the rule in the ruleset that matched the event. When getting an event by event ID, the rule_action will only be included when the ruleset_id query parameter is specified.
  - `simulator` (boolean): iOS specific simulator detection. There are 2 values:
  - `suspect_score` (integer): Suspect Score is an easy way to integrate Smart Signals into your fraud protection work flow.  It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. The value range is [0; S] where S is sum of all Smart Signals weights.  See more details here: https://docs.fingerprint.com/docs/suspect-score
  - `tampering` (boolean): The field can be used as a standalone flag for tampering detection. Alternatively, the more granular fields documented below can be used for workflows that require more context.
  - `tampering_confidence` (enum: low | medium | high): The confidence level indicates how certain Fingerprint is that the current request involves browser tampering. This confidence level is determined by evaluating multiple factors, such as heuristic rules, probabilistic anomaly detection, an anti detect browser ml model, and other relevant methods. It is conveyed as a string with possible values such as high, medium, or low
  - `tampering_ml_score` (number double): The output of this model is captured as tampering_ml_score, a number indicating how likely an event is coming from an anti detect browser. Values close to 1 signify higher confidence and we consider anything above the threshold of 0.8 to be actionable (the result and anti_detect_browser fields conveniently captures that fact)
  - `tampering_details` (object): 
    - `anomaly_score` (number double): The output of this model is captured as anomaly_score, a statistical score indicating how rare the visitor's browser signature is compared to the overall population. Values close to 1 signify highly anomalous browsers and we consider anything above the threshold of 0.5 to be actionable (the result field conveniently captures that fact).
    - `anti_detect_browser` (boolean): Detects whether the request shows evidence of anti-detect browser usage.
  - `velocity` (object): Sums key data points for a specific `visitor_id`, `ip_address` and `linked_id` at three distinct time
    - `distinct_ip` (object): Is absent if the velocity data could not be generated for the visitor ID.
      - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
      - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
      - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
    - `distinct_linked_id` (object): Is absent if the velocity data could not be generated for the visitor ID.
      - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
      - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
      - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
    - `distinct_country` (object): Is absent if the velocity data could not be generated for the visitor ID.
      - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
      - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
      - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
    - `events` (object): Is absent if the velocity data could not be generated for the visitor ID.
      - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
      - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
      - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
    - `ip_events` (object): Is absent if the velocity data could not be generated for the visitor ID.
      - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
      - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
      - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
    - `distinct_ip_by_linked_id` (object): Is absent if the velocity data could not be generated for the visitor ID.
      - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
      - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
      - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
    - `distinct_visitor_id_by_linked_id` (object): Is absent if the velocity data could not be generated for the visitor ID.
      - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
      - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
      - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
  - `virtual_machine` (boolean): `true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise.
  - `virtual_machine_ml_score` (number double): Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `virtual_machine` detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
  - `vpn` (boolean): VPN or other anonymizing service has been used when sending the request.
  - `vpn_confidence` (enum: low | medium | high): A confidence rating for the VPN detection result — "low", "medium", or "high". Depends on the combination of results returned from all VPN detection methods.
  - `vpn_ml_score` (number double): Machine learning–based VPN score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `vpn` detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
  - `vpn_origin_timezone` (string): Local timezone which is used in timezone_mismatch method.
  - `vpn_origin_country` (string): Country of the request (Android SDK version >= 2.4.0, iOS SDK version >= 2.9.0, JS agent >= 3.12.9 / 4.0.2), ISO 3166 format or unknown.
  - `vpn_methods` (object): 
    - `timezone_mismatch` (boolean): The browser timezone doesn't match the timezone inferred from the request IP address.
    - `public_vpn` (boolean): Request IP address is owned and used by a public VPN service provider.
    - `auxiliary_mobile` (boolean): This method applies to mobile devices only. Indicates the result of additional methods used to detect a VPN in mobile devices.
    - `os_mismatch` (boolean): The browser runs on a different operating system than the operating system inferred from the request network signature.
    - `relay` (boolean): Request IP address belongs to a relay service provider, indicating the use of relay services like [Apple Private relay](https://support.apple.com/en-us/102602) or [Cloudflare Warp](https://developers.cloudflare.com/warp-client/).
    - `ml_prediction` (boolean): `true` if the request came from a device running a VPN, `false` otherwise.
  - `high_activity_device` (boolean): Flag indicating if the request came from a high-activity visitor.
  - `rare_device` (boolean): `true` if the device is considered rare based on its combination of hardware and software attributes.  A device is classified as rare if it falls within the top 99.9 percentile (lowest-frequency segment) of observed traffic,  or if its configuration has not been previously seen (`not_seen`).
  - `rare_device_percentile_bucket` (enum: <p95 | p95-p99 | p99-p99.5 | p99.5-p99.9 | p99.9+ | not_seen): The rarity percentile bucket of the device, indicating how uncommon the device configuration is compared to all observed devices. 
  - `raw_device_attributes` (object): A curated subset of raw browser/device attributes that the API surface exposes. Each property contains a value or object with the data for the collected signal.
    - `font_preferences` (object): Baseline measurement of canonical fonts rendered on the device. Numeric width metrics, in CSS pixels, for the canonical fonts collected by the agent.
      - `default` (number double): 
      - `serif` (number double): 
      - `sans` (number double): 
      - `mono` (number double): 
      - `apple` (number double): 
      - `min` (number double): 
      - `system` (number double): 
    - `emoji` (object): Bounding box metrics describing how the emoji glyph renders.
      - `font` (string): Font family reported by the browser when drawing the emoji.
      - `width` (number double): 
      - `height` (number double): 
      - `top` (number double): 
      - `bottom` (number double): 
      - `left` (number double): 
      - `right` (number double): 
      - `x` (number double): 
      - `y` (number double): 
    - `fonts` (array of string): List of fonts detected on the device.
    - `device_memory` (integer int32): Rounded amount of RAM in gigabytes. Available for browsers, Android, and iOS devices.
    - `timezone` (string): Timezone identifier detected on the client.
    - `canvas` (object): Canvas fingerprint containing winding flag plus geometry/text hashes.
      - `winding` (boolean): 
      - `geometry` (string): Hash of geometry rendering output or `unsupported` markers.
      - `text` (string): Hash of text rendering output or `unsupported` markers.
    - `languages` (array of array of string): Navigator languages reported by the agent including fallbacks. Each inner array represents ordered language preferences reported by different APIs. Available for browsers, iOS, and Android devices.
    - `webgl_extensions` (object): Hashes of WebGL context attributes and extension support.
      - `context_attributes` (string): 
      - `parameters` (string): 
      - `shader_precisions` (string): 
      - `extensions` (string): 
      - `extension_parameters` (string): 
      - `unsupported_extensions` (array of string): 
    - `webgl_basics` (object): Render and vendor strings reported by the WebGL context.
      - `version` (string): 
      - `vendor` (string): 
      - `vendor_unmasked` (string): 
      - `renderer` (string): 
      - `renderer_unmasked` (string): 
      - `shading_language_version` (string): 
    - `screen_resolution` (array of integer int32): Current screen resolution. Available for both browsers and iOS devices
    - `touch_support` (object): Browser-reported touch capabilities.
      - `touch_event` (boolean): 
      - `touch_start` (boolean): 
      - `max_touch_points` (integer int64): 
    - `oscpu` (string): Navigator `oscpu` string.
    - `architecture` (integer int32): Integer representing the CPU architecture exposed by the browser.
    - `cookies_enabled` (boolean): Whether the cookies are enabled in the browser.
    - `hardware_concurrency` (integer int32): Number of logical CPU cores reported by the browser.
    - `date_time_locale` (string): Locale derived from the Intl.DateTimeFormat API. Negative values indicate known error states. The negative statuses can be:
    - `vendor` (string): Navigator vendor string.
    - `color_depth` (integer int32): Screen color depth in bits.
    - `platform` (string): Navigator platform string.
    - `session_storage` (boolean): Whether sessionStorage is available.
    - `local_storage` (boolean): Whether localStorage is available.
    - `audio` (number double): AudioContext fingerprint or negative status when unavailable. The negative statuses can be:
    - `plugins` (array of object): Browser plugins reported by `navigator.plugins`.
      - `name` (string) (required): 
      - `description` (string): 
      - `mimeTypes` (array of object): 
        - `type` (string): 
        - `suffixes` (string): 
        - `description` (string): 
    - `indexed_db` (boolean): Whether IndexedDB is available.
    - `math` (string): Hash of Math APIs used for entropy collection.
    - `device_model` (string): Device model string. Available only for Android and iOS devices.
    - `device_manufacturer` (string): Device manufacturer string. Available only for Android and iOS devices.
    - `font_hash` (string): Unique identifier for the user’s installed fonts.
    - `timezone_offset` (string): UTC offset in "±HH:MM" format derived from the detected IANA timezone.
    - `battery_level` (integer int32): Battery charge level as a percentage (0-100). Available for Android, iOS, and web devices. On web, only available in Chromium-based browsers.
    - `battery_charging` (boolean): When `true`, the device is currently charging. Available only for web devices on Chromium-based browsers.
    - `battery_low_power_mode` (boolean): Whether the device's low power mode is enabled. Available only for Android and iOS devices.
    - `keyboard_layout_hash` (string): Unique identifier for the user's keyboard layout.
    - `keyboard_layout_name` (string): Name of the user's configured keyboard layout as a BCP 47-style identifier. Only available in Chromium-based browsers, omitted otherwise.
  - `labels` (array of object): Each label returns a prediction (true or false) for a specific use case (label field) based on a machine learning score. The machine learning score is determined by a model trained on customer data for that use case. This field is in the beta phase and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
    - `label` (string) (required): Customer-facing label name defined by the customer.
    - `prediction` (boolean): 
    - `ml_score` (number double): Raw model score between 0 and 1.
- `400`: Bad request. The event ID provided is not valid.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `403`: Forbidden. Access to this API is denied.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `404`: Not found. The event ID cannot be found in this workspace's data.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `429`: Too Many Requests. The request is throttled.
To protect service stability during rare periods of extreme load, we may return HTTP 429 responses with message `too many search requests` even if you are within your assigned rate limits.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `500`: Workspace error.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `504`: Gateway Timeout. Search execution exceeded the allowed timeout window.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 

### PATCH /events/{event_id}
**Update an event**
Change information in existing events specified by `event_id` or *flag suspicious events*.

When an event is created, it can be assigned `linked_id` and `tags` submitted through the JS agent parameters. 
This information might not have been available on the client initially, so the Server API permits updating these attributes after the fact.

**Warning** It's not possible to update events older than one month. 

**Warning** Trying to update an event immediately after creation may temporarily res...
Full URL: `https://api.fpjs.io/v4/events/{event_id}`
Tags: Events

**Parameters:**
- `event_id` [path] (string) (required): The unique event [identifier](https://docs.fingerprint.com/reference/js-agent-get-function#event_id).

**Request Body:**
Content-Type: `application/json`
- `linked_id` (string): Linked ID value to assign to the existing event
- `tags` (object): A customer-provided value or an object that was sent with the identification request or updated later.
- `suspect` (boolean): Suspect flag indicating observed suspicious or fraudulent event

**Responses:**
- `200`: OK.
- `400`: Bad request. The request payload is not valid.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `403`: Forbidden. Access to this API is denied.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `404`: Not found. The event ID cannot be found in this workspace's data.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `409`: Conflict. The event is not mutable yet.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 

### POST /events/{event_id}/feedback
**Submit feedback for an event**
Use this API to submit feedback for a specific, existing event, identified by `event_id`.

Feedback is queued and processed asynchronously. Subsequent Server API responses may not reflect the feedback immediately.

Duplicate feedback requests for the same event are allowed; however, the most recent feedback overrides all previous submissions for that event.

### Availability
This API is currently in beta and available only for Enterprise plans. If you are interested, please [contact our support ...
Full URL: `https://api.fpjs.io/v4/events/{event_id}/feedback`
Tags: Events

**Parameters:**
- `event_id` [path] (string) (required): The [event ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#event_id) of the identification event you want to submit feedback for.

**Request Body:**
Content-Type: `application/json`
- `reset_identification_confidence_score` (boolean): Set to `true` to reset the identification confidence score for this event to `1.0`.

**Responses:**
- `202`: Accepted. The feedback has been accepted and will be processed asynchronously.
- `400`: Bad request. The request payload is not valid.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `403`: Forbidden. Access to this API is denied.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `404`: Not found. The event ID cannot be found in this workspace's data.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `429`: Too Many Requests. The request is throttled.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `500`: Internal server error.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 

### GET /events
**Search events**
## Search

The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include:

- Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor.
- Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier.
- Excluding all bot traffic from the query (`good` and `bad` bots)

By ...
Full URL: `https://api.fpjs.io/v4/events`
Tags: Events

**Parameters:**
- `limit` [query] (integer int32) (optional): Maximum number of events to return. Defaults to 10 when omitted. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events.
- `pagination_key` [query] (string) (optional): Use `pagination_key` to get the next page of results.  When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the `pagination_key` parameter to get the next page of results:  1. First request, returning most recent 100 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=S9rgMMUb4z3X5t5pr_tSgoSZlmyF0O8X7kCV2m981-iY1LmRTjraa1rTk3L-hQExnDWCi0RA-zAIjaVSTNO2AN2eqQWgzT0RjbieMxRfSdkM-HmOhdOgdQvYfPG3vqU1DJKh4Q`
- `visitor_id` [query] (string) (optional): Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals.  Filter events by matching Visitor ID (`identification.visitor_id` property).
- `high_recall_id` [query] (string) (optional): The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental.  Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property).
- `bot` [query] (enum: all | good | bad | none) (optional): Filter events by the Bot Detection result, specifically:   `all` - events where any kind of bot was detected.   `good` - events where a good bot was detected.   `bad` - events where a bad bot was detected.   `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response.
- `bot_info` [query] (enum: all | none) (optional): Filter events by their Bot Info result, specifically:   - `all` - events where any kind of bot was detected.   - `none` - events where no bot was detected, and no `bot_info` was present.
- `bot_info_category` [query] (array of enum: advertising_and_marketing | aggregator | ai_agent | ai_assistant | ai_browser | ai_crawler | ai_search | browser_automation | ecommerce | monitoring_and_analytics | other | scraping | security | search_engine_crawler | search_engine_optimization | unknown) (optional): Filter events by their Bot Info Category.  Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported.
- `bot_info_identity` [query] (array of enum: verified | signed | spoofed | unknown) (optional): Filter events by their Bot Info Identity type.  Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported.
- `bot_info_confidence` [query] (array of enum: low | medium | high) (optional): Filter events by their Bot Info Confidence.  Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported.
- `bot_info_provider` [query] (array of string) (optional): Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported.  Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported.
- `bot_info_name` [query] (array of string) (optional): Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported.  Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported.
- `ip_address` [query] (string) (optional): Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32
- `asn` [query] (string) (optional): Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response.
- `linked_id` [query] (string) (optional): Filter events by your custom identifier.  You can use [linked IDs](https://docs.fingerprint.com/reference/js-agent-get-function#linkedid) to associate identification requests with your own identifier, for example, session ID, purchase ID, or transaction ID. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier.
- `url` [query] (string) (optional): Filter events by the URL (`url` property) associated with the event.
- `bundle_id` [query] (string) (optional): Filter events by the Bundle ID (iOS) associated with the event.
- `package_name` [query] (string) (optional): Filter events by the Package Name (Android) associated with the event.
- `origin` [query] (string) (optional): Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com)
- `start` [query] (string date-time | integer int64) (optional): Include events that happened after the provided `start` date formatted as an RFC3339 timestamp. For backward compatibility, a Unix milliseconds timestamp is also accepted. Defaults to 7 days ago. Setting `start` does not change the default `end` date of `now` — adjust it separately if needed.
- `end` [query] (string date-time | integer int64) (optional): Include events that happened before the provided `end` date formatted as an RFC3339 timestamp. For backward compatibility, a Unix milliseconds timestamp is also accepted. Defaults to now. Setting `end` does not change the default `start` date of `7 days ago` — adjust it separately if needed.
- `reverse` [query] (boolean) (optional): When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (newest first, descending timestamp order).
- `suspect` [query] (boolean) (optional): Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/server-api-v4-update-event). > Note: When using this parameter, only events with the `suspect` property explicitly set to `true` or `false` are returned. Events with undefined `suspect` property are left out of the response.
- `vpn` [query] (boolean) (optional): Filter events by VPN Detection result. > Note: When using this parameter, only events with the `vpn` property set to `true` or `false` are returned. Events without a `vpn` Smart Signal result are left out of the response.
- `virtual_machine` [query] (boolean) (optional): Filter events by Virtual Machine Detection result. > Note: When using this parameter, only events with the `virtual_machine` property set to `true` or `false` are returned. Events without a `virtual_machine` Smart Signal result are left out of the response.
- `tampering` [query] (boolean) (optional): Filter events by Browser Tampering Detection result. > Note: When using this parameter, only events with the `tampering` property set to `true` or `false` are returned. Events without a `tampering` Smart Signal result are left out of the response.
- `anti_detect_browser` [query] (boolean) (optional): Filter events by Anti-detect Browser Detection result. > Note: When using this parameter, only events with the `tampering_details.anti_detect_browser` property set to `true` or `false` are returned. Events without a `tampering` Smart Signal result are left out of the response.
- `incognito` [query] (boolean) (optional): Filter events by Browser Incognito Detection result. > Note: When using this parameter, only events with the `incognito` property set to `true` or `false` are returned. Events without an `incognito` Smart Signal result are left out of the response.
- `privacy_settings` [query] (boolean) (optional): Filter events by Privacy Settings Detection result. > Note: When using this parameter, only events with the `privacy_settings` property set to `true` or `false` are returned. Events without a `privacy_settings` Smart Signal result are left out of the response.
- `jailbroken` [query] (boolean) (optional): Filter events by Jailbroken Device Detection result. > Note: When using this parameter, only events with the `jailbroken` property set to `true` or `false` are returned. Events without a `jailbroken` Smart Signal result are left out of the response.
- `frida` [query] (boolean) (optional): Filter events by Frida Detection result. > Note: When using this parameter, only events with the `frida` property set to `true` or `false` are returned. Events without a `frida` Smart Signal result are left out of the response.
- `factory_reset` [query] (boolean) (optional): Filter events by Factory Reset Detection result. > Note: When using this parameter, only events with a `factory_reset_timestamp` property populated are included. Events without a `factory_reset_timestamp` Smart Signal result are left out of the response.
- `cloned_app` [query] (boolean) (optional): Filter events by Cloned App Detection result. > Note: When using this parameter, only events with the `cloned_app` property set to `true` or `false` are returned. Events without a `cloned_app` Smart Signal result are left out of the response.
- `emulator` [query] (boolean) (optional): Filter events by Android Emulator Detection result. > Note: When using this parameter, only events with the `emulator` property set to `true` or `false` are returned. Events without an `emulator` Smart Signal result are left out of the response.
- `root_apps` [query] (boolean) (optional): Filter events by Rooted Device Detection result. > Note: When using this parameter, only events with the `root_apps` property set to `true` or `false` are returned. Events without a `root_apps` Smart Signal result are left out of the response.
- `vpn_confidence` [query] (enum: high | medium | low) (optional): Filter events by VPN Detection result confidence level. `high` - events with high VPN Detection confidence. `medium` - events with medium VPN Detection confidence. `low` - events with low VPN Detection confidence. > Note: When using this parameter, only events with the `vpn.confidence` property set to a valid value are returned. Events without a `vpn` Smart Signal result are left out of the response.
- `min_suspect_score` [query] (number float) (optional): Filter events with Suspect Score result above a provided minimum threshold. > Note: When using this parameter, only events where the `suspect_score` property set to a value exceeding your threshold are returned. Events without a `suspect_score` Smart Signal result are left out of the response.
- `developer_tools` [query] (boolean) (optional): Filter events by Developer Tools detection result. > Note: When using this parameter, only events with the `developer_tools` property set to `true` or `false` are returned. Events without a `developer_tools` Smart Signal result are left out of the response.
- `location_spoofing` [query] (boolean) (optional): Filter events by Location Spoofing detection result. > Note: When using this parameter, only events with the `location_spoofing` property set to `true` or `false` are returned. Events without a `location_spoofing` Smart Signal result are left out of the response.
- `mitm_attack` [query] (boolean) (optional): Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response.
- `rare_device` [query] (boolean) (optional): Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response.  > This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
- `rare_device_percentile_bucket` [query] (enum: <p95 | p95-p99 | p99-p99.5 | p99.5-p99.9 | p99.9+ | not_seen) (optional): Filter events by Device Rarity percentile bucket. `<p95` - device configuration is in the bottom 95% (most common). `p95-p99` - device is in the 95th to 99th percentile. `p99-p99.5` - device is in the 99th to 99.5th percentile. `p99.5-p99.9` - device is in the 99.5th to 99.9th percentile. `p99.9+` - device is in the top 0.1% (rarest). `not_seen` - device configuration has never been observed before.  > This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
- `proxy` [query] (boolean) (optional): Filter events by Proxy detection result. > Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response.
- `sdk_version` [query] (string) (optional): Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14`
- `sdk_platform` [query] (enum: js | android | ios) (optional): Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices.
- `environment` [query] (array of string) (optional): Filter for events by providing one or more environment IDs (`environment_id` property).  ### Array syntax To provide multiple environment IDs, use the repeated keys syntax (`environment=env1&environment=env2`). Other notations like comma-separated (`environment=env1,env2`) or bracket notation (`environment[]=env1&environment[]=env2`) are not supported.
- `proximity_id` [query] (string) (optional): Filter events by the most precise Proximity ID provided by default. > Note: When using this parameter, only events with the `proximity.id` property matching the provided ID are returned. Events without a `proximity` result are left out of the response.
- `total_hits` [query] (integer int64) (optional): When set, the response will include a `total_hits` property with a count of total query matches across all pages, up to the specified limit.
- `tor_node` [query] (boolean) (optional): Filter events by Tor Node detection result. > Note: When using this parameter, only events with the `tor_node` property set to `true` or `false` are returned. Events without a `tor_node` detection result are left out of the response.
- `incremental_identification_status` [query] (enum: partially_completed | completed) (optional): Filter events by their incremental identification status (`incremental_identification_status` property). Non incremental identification events are left out of the response.
- `simulator` [query] (boolean) (optional): Filter events by iOS Simulator Detection result.  > Note: When using this parameter, only events with the `simulator` property set to `true` or `false` are returned. Events without a `simulator` Smart Signal result are left out of the response.
- `active_call` [query] (boolean) (optional): Filter events by Active Call Detection result on mobile devices.  > Note: When using this parameter, only events with the `active_call` property set to `true` or `false` are returned. Events without an `active_call` Smart Signal result are left out of the response.
- `source` [query] (array of enum: edge) (optional): Selects the source of events to search. When omitted, only traditional identification events generated from devices are returned (the default behavior). When set to `edge`, only Automation Intelligence (Edge) events are returned.  To retrieve all events regardless of source, you must make two requests. One with the `source` parameter set to `edge`, and another with the `source` parameter omitted.  > Note: The Automation Intelligence API is in public preview testing phase.  If you encounter any issues, please [contact](https://fingerprint.com/support/) our support team.

**Responses:**
- `200`: Events matching the filter(s).
  - `events` (array of object) (required): 
    - `event_id` (string) (required): Unique identifier of the user's request. The first portion of the event_id is a unix epoch milliseconds timestamp.
    - `timestamp` (integer int64) (required): Timestamp of the event with millisecond precision in Unix time.
    - `source` (enum: device | edge): Identifies how the event was generated.
    - `incremental_identification_status` (enum: partially_completed | completed): Only included for requests using incremental identification.
    - `linked_id` (string): A customer-provided ID that was sent with the request.
    - `environment_id` (string): Environment ID of the event.
    - `suspect` (boolean): Field is `true` if you have previously set the `suspect` flag for this event using the [Server API Update event endpoint](https://docs.fingerprint.com/reference/server-api-update-event).
    - `sdk` (object): Contains information about the SDK used to perform the request.
      - `platform` (enum: js | android | ios | unknown) (required): Platform of the SDK used for the identification request.
      - `version` (string) (required): Version string of the SDK used for the identification request.
      - `integrations` (array of object): 
        - `name` (string): The name of the specific integration.
        - `version` (string): The version of the specific integration.
        - `subintegration` (object): 
    - `replayed` (boolean): `true` if we determined that this payload was replayed, `false` otherwise.
    - `identification` (object): 
      - `visitor_id` (string) (required): String of 20 characters that uniquely identifies the visitor's browser or mobile device.
      - `confidence` (object): The confidence score represents the probability of a false-positive identification. To learn more, visit [Confidence Score](https://docs.fingerprint.com/docs/identification-accuracy-and-confidence#confidence-score). Please note that the confidence score is not yet supported for [High Recall ID](https://docs.fingerprint.com/docs/supplementary-identifiers-highrecall).
        - `score` (number double) (required): A floating-point number between 0 and 1 that represents the probability of a false-positive identification. For High Recall ID, this value is 0.
        - `version` (string): The version name of the method used to calculate the confidence score. For High Recall ID, this value is "Not Supported".
        - `comment` (string): 
      - `visitor_found` (boolean) (required): Attribute represents if a visitor had been identified before.
      - `first_seen_at` (integer int64): Unix epoch time milliseconds timestamp indicating the time at which this visitor ID was first seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000
      - `last_seen_at` (integer int64): Unix epoch time milliseconds timestamp indicating the time at which this visitor ID was last seen. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000
    - `supplementary_id_high_recall` (object): The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental.
      - `visitor_id` (string) (required): The High Recall identifier for the visitor's browser. It is an alphanumeric string with a maximum length of 25 characters.
      - `visitor_found` (boolean) (required): True if this is a returning browser and has been previously identified. Otherwise, false.
      - `confidence` (object): The confidence score represents the probability of a false-positive identification. To learn more, visit [Confidence Score](https://docs.fingerprint.com/docs/identification-accuracy-and-confidence#confidence-score). Please note that the confidence score is not yet supported for [High Recall ID](https://docs.fingerprint.com/docs/supplementary-identifiers-highrecall).
        - `score` (number double) (required): A floating-point number between 0 and 1 that represents the probability of a false-positive identification. For High Recall ID, this value is 0.
        - `version` (string): The version name of the method used to calculate the confidence score. For High Recall ID, this value is "Not Supported".
        - `comment` (string): 
      - `first_seen_at` (integer int64): Unix epoch timestamp (in milliseconds) indicating when the browser was first identified. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000
      - `last_seen_at` (integer int64): Unix epoch timestamp (in milliseconds) corresponding to the most recent visit by this browser. example: `1758069706642` - Corresponding to Wed Sep 17 2025 00:41:46 GMT+0000
    - `tags` (object): A customer-provided value or an object that was sent with the identification request or updated later.
    - `url` (string): Page URL from which the request was sent.
    - `bundle_id` (string): Bundle ID of the iOS application integrated with the Fingerprint SDK for the event.
    - `package_name` (string): Package name of the Android application integrated with the Fingerprint SDK for the event.
    - `ip_address` (string): IP address of the requesting browser or bot.
    - `user_agent` (string): User Agent of the client.
    - `device` (string): Device model or family extracted from the user agent string. On web, this field is also present inside `browser_details`.
    - `os` (string): Operating system family extracted from the user agent string. On web, this field is also present inside `browser_details`.
    - `os_version` (string): Operating system version string extracted from the user agent string. On web, this field is also present inside `browser_details`.
    - `client_referrer` (string): Client Referrer field corresponds to the `document.referrer` field gathered during an identification request. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, by using a bookmark).
    - `browser_details` (object): 
      - `browser_name` (string) (required): 
      - `browser_major_version` (string) (required): 
      - `browser_full_version` (string) (required): 
      - `os` (string) (required): 
      - `os_version` (string) (required): 
      - `device` (string) (required): 
    - `proximity` (object): Proximity ID represents a fixed geographical zone in a discrete global grid within which the device is observed.
      - `id` (string) (required): A stable privacy-preserving identifier for a given proximity zone.
      - `precision_radius` (enum: 10 | 25 | 65 | 175 | 450 | 1200 | 3300 | 8500 | 22500) (required): The radius of the proximity zone’s precision level, in meters.
      - `confidence` (number float) (required): A value between `0` and `1` representing the likelihood that the true device location lies within the mapped proximity zone.
    - `active_call` (boolean): Indicates whether the mobile device had an active call (cellular or VoIP) at the time of the request. Available from SDK 2.16.0+ on iOS and Android.
    - `bot` (enum: bad | good | not_detected): Bot detection result:
    - `bot_type` (string): Additional classification of the bot type if detected.
    - `bot_info` (object): Extended bot information.
      - `category` (enum: advertising_and_marketing | aggregator | ai_agent | ai_assistant | ai_browser | ai_crawler | ai_search | browser_automation | ecommerce | monitoring_and_analytics | other | scraping | security | search_engine_crawler | search_engine_optimization | unknown) (required): The type and purpose of the bot.
      - `provider` (string) (required): The organization or company operating the bot.
      - `provider_url` (string): The URL of the bot provider's website.
      - `name` (string) (required): The specific name or identifier of the bot.
      - `identity` (enum: verified | signed | spoofed | unknown) (required): The verification status of the bot's identity:
      - `confidence` (enum: low | medium | high) (required): Confidence level of the bot identification.
    - `cloned_app` (boolean): Android specific cloned application detection. There are 2 values: 
    - `developer_tools` (boolean): `true` if the browser has DevTools open (Chrome, Firefox) or the Android/iOS device has Developer Tools enabled, `false` otherwise.
    - `emulator` (boolean): Android specific emulator detection. There are 2 values: 
    - `factory_reset_timestamp` (integer int64): The time of the most recent factory reset that happened on the **mobile device** is expressed as Unix epoch time. When a factory reset cannot be detected on the mobile device or when the request is initiated from a browser,  this field will correspond to the *epoch* time (i.e 1 Jan 1970 UTC) as a value of 0. See [Factory Reset Detection](https://docs.fingerprint.com/docs/smart-signals-reference#factory-reset-detection) to learn more about this Smart Signal.
    - `frida` (boolean): [Frida](https://frida.re/docs/) detection for Android and iOS devices. There are 2 values:
    - `ip_blocklist` (object): 
      - `email_spam` (boolean): IP address was part of a known email spam attack (SMTP).
      - `attack_source` (boolean): IP address was part of a known network attack (SSH/HTTPS).
      - `tor_node` (boolean): IP address was part of known TOR network activity.
    - `ip_info` (object): Details about the request IP address. Has separate fields for v4 and v6 IP address versions.
      - `v4` (object): 
        - `address` (string ipv4) (required): 
        - `geolocation` (object): 
        - `asn` (string): 
        - `asn_name` (string): 
        - `asn_network` (string): 
        - `asn_type` (string): 
        - `datacenter_result` (boolean): When true, the request originated from a datacenter.
        - `datacenter_name` (string): 
      - `v6` (object): 
        - `address` (string ipv6) (required): 
        - `geolocation` (object): 
        - `asn` (string): 
        - `asn_name` (string): 
        - `asn_network` (string): 
        - `asn_type` (string): 
        - `datacenter_result` (boolean): When true, the request originated from a datacenter.
        - `datacenter_name` (string): 
    - `proxy` (boolean): IP address was used by a public proxy provider or belonged to a known recent residential proxy
    - `proxy_confidence` (enum: low | medium | high): Confidence level of the proxy detection. If a proxy is not detected, confidence is "high". If it's detected, can be "low", "medium", or "high".
    - `proxy_details` (object): Proxy detection details (present if `proxy` is `true`)
      - `proxy_type` (enum: residential | data_center | unknown) (required): Proxy type:
      - `last_seen_at` (integer int64): Unix millisecond timestamp with hourly resolution of when this IP was last seen as a proxy
      - `provider` (string): String representing the last proxy service provider detected when this
    - `proxy_ml_score` (number double): Machine learning–based proxy score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `proxy` detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
    - `incognito` (boolean): `true` if we detected incognito mode used in the browser, `false` otherwise.
    - `jailbroken` (boolean): iOS specific jailbreak detection. There are 2 values: 
    - `location_spoofing` (boolean): Flag indicating whether the request came from a mobile device with location spoofing enabled.
    - `mitm_attack` (boolean): * `true` - When requests made from your users' mobile devices to Fingerprint servers have been intercepted and potentially modified. 
    - `privacy_settings` (boolean): `true` if the request is from a privacy aware browser (e.g. Tor) or from a browser in which fingerprinting is blocked. Otherwise `false`.
    - `root_apps` (boolean): Android specific root management apps detection. There are 2 values: 
    - `rule_action` (object | object): Describes the action the client should take, according to the rule in the ruleset that matched the event. When getting an event by event ID, the rule_action will only be included when the ruleset_id query parameter is specified.
    - `simulator` (boolean): iOS specific simulator detection. There are 2 values:
    - `suspect_score` (integer): Suspect Score is an easy way to integrate Smart Signals into your fraud protection work flow.  It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. The value range is [0; S] where S is sum of all Smart Signals weights.  See more details here: https://docs.fingerprint.com/docs/suspect-score
    - `tampering` (boolean): The field can be used as a standalone flag for tampering detection. Alternatively, the more granular fields documented below can be used for workflows that require more context.
    - `tampering_confidence` (enum: low | medium | high): The confidence level indicates how certain Fingerprint is that the current request involves browser tampering. This confidence level is determined by evaluating multiple factors, such as heuristic rules, probabilistic anomaly detection, an anti detect browser ml model, and other relevant methods. It is conveyed as a string with possible values such as high, medium, or low
    - `tampering_ml_score` (number double): The output of this model is captured as tampering_ml_score, a number indicating how likely an event is coming from an anti detect browser. Values close to 1 signify higher confidence and we consider anything above the threshold of 0.8 to be actionable (the result and anti_detect_browser fields conveniently captures that fact)
    - `tampering_details` (object): 
      - `anomaly_score` (number double): The output of this model is captured as anomaly_score, a statistical score indicating how rare the visitor's browser signature is compared to the overall population. Values close to 1 signify highly anomalous browsers and we consider anything above the threshold of 0.5 to be actionable (the result field conveniently captures that fact).
      - `anti_detect_browser` (boolean): Detects whether the request shows evidence of anti-detect browser usage.
    - `velocity` (object): Sums key data points for a specific `visitor_id`, `ip_address` and `linked_id` at three distinct time
      - `distinct_ip` (object): Is absent if the velocity data could not be generated for the visitor ID.
        - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
        - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
        - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
      - `distinct_linked_id` (object): Is absent if the velocity data could not be generated for the visitor ID.
        - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
        - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
        - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
      - `distinct_country` (object): Is absent if the velocity data could not be generated for the visitor ID.
        - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
        - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
        - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
      - `events` (object): Is absent if the velocity data could not be generated for the visitor ID.
        - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
        - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
        - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
      - `ip_events` (object): Is absent if the velocity data could not be generated for the visitor ID.
        - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
        - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
        - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
      - `distinct_ip_by_linked_id` (object): Is absent if the velocity data could not be generated for the visitor ID.
        - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
        - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
        - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
      - `distinct_visitor_id_by_linked_id` (object): Is absent if the velocity data could not be generated for the visitor ID.
        - `5_minutes` (integer) (required): Count for the last 5 minutes of velocity data, from the time of the event.
        - `1_hour` (integer) (required): Count for the last 1 hour of velocity data, from the time of the event.
        - `24_hours` (integer): Count for the last 24 hours of velocity data, from the time of the event.
    - `virtual_machine` (boolean): `true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise.
    - `virtual_machine_ml_score` (number double): Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `virtual_machine` detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
    - `vpn` (boolean): VPN or other anonymizing service has been used when sending the request.
    - `vpn_confidence` (enum: low | medium | high): A confidence rating for the VPN detection result — "low", "medium", or "high". Depends on the combination of results returned from all VPN detection methods.
    - `vpn_ml_score` (number double): Machine learning–based VPN score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `vpn` detection result. This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
    - `vpn_origin_timezone` (string): Local timezone which is used in timezone_mismatch method.
    - `vpn_origin_country` (string): Country of the request (Android SDK version >= 2.4.0, iOS SDK version >= 2.9.0, JS agent >= 3.12.9 / 4.0.2), ISO 3166 format or unknown.
    - `vpn_methods` (object): 
      - `timezone_mismatch` (boolean): The browser timezone doesn't match the timezone inferred from the request IP address.
      - `public_vpn` (boolean): Request IP address is owned and used by a public VPN service provider.
      - `auxiliary_mobile` (boolean): This method applies to mobile devices only. Indicates the result of additional methods used to detect a VPN in mobile devices.
      - `os_mismatch` (boolean): The browser runs on a different operating system than the operating system inferred from the request network signature.
      - `relay` (boolean): Request IP address belongs to a relay service provider, indicating the use of relay services like [Apple Private relay](https://support.apple.com/en-us/102602) or [Cloudflare Warp](https://developers.cloudflare.com/warp-client/).
      - `ml_prediction` (boolean): `true` if the request came from a device running a VPN, `false` otherwise.
    - `high_activity_device` (boolean): Flag indicating if the request came from a high-activity visitor.
    - `rare_device` (boolean): `true` if the device is considered rare based on its combination of hardware and software attributes.  A device is classified as rare if it falls within the top 99.9 percentile (lowest-frequency segment) of observed traffic,  or if its configuration has not been previously seen (`not_seen`).
    - `rare_device_percentile_bucket` (enum: <p95 | p95-p99 | p99-p99.5 | p99.5-p99.9 | p99.9+ | not_seen): The rarity percentile bucket of the device, indicating how uncommon the device configuration is compared to all observed devices. 
    - `raw_device_attributes` (object): A curated subset of raw browser/device attributes that the API surface exposes. Each property contains a value or object with the data for the collected signal.
      - `font_preferences` (object): Baseline measurement of canonical fonts rendered on the device. Numeric width metrics, in CSS pixels, for the canonical fonts collected by the agent.
        - `default` (number double): 
        - `serif` (number double): 
        - `sans` (number double): 
        - `mono` (number double): 
        - `apple` (number double): 
        - `min` (number double): 
        - `system` (number double): 
      - `emoji` (object): Bounding box metrics describing how the emoji glyph renders.
        - `font` (string): Font family reported by the browser when drawing the emoji.
        - `width` (number double): 
        - `height` (number double): 
        - `top` (number double): 
        - `bottom` (number double): 
        - `left` (number double): 
        - `right` (number double): 
        - `x` (number double): 
        - `y` (number double): 
      - `fonts` (array of string): List of fonts detected on the device.
      - `device_memory` (integer int32): Rounded amount of RAM in gigabytes. Available for browsers, Android, and iOS devices.
      - `timezone` (string): Timezone identifier detected on the client.
      - `canvas` (object): Canvas fingerprint containing winding flag plus geometry/text hashes.
        - `winding` (boolean): 
        - `geometry` (string): Hash of geometry rendering output or `unsupported` markers.
        - `text` (string): Hash of text rendering output or `unsupported` markers.
      - `languages` (array of array of object): Navigator languages reported by the agent including fallbacks. Each inner array represents ordered language preferences reported by different APIs. Available for browsers, iOS, and Android devices.
      - `webgl_extensions` (object): Hashes of WebGL context attributes and extension support.
        - `context_attributes` (string): 
        - `parameters` (string): 
        - `shader_precisions` (string): 
        - `extensions` (string): 
        - `extension_parameters` (string): 
        - `unsupported_extensions` (array of object): 
      - `webgl_basics` (object): Render and vendor strings reported by the WebGL context.
        - `version` (string): 
        - `vendor` (string): 
        - `vendor_unmasked` (string): 
        - `renderer` (string): 
        - `renderer_unmasked` (string): 
        - `shading_language_version` (string): 
      - `screen_resolution` (array of integer int32): Current screen resolution. Available for both browsers and iOS devices
      - `touch_support` (object): Browser-reported touch capabilities.
        - `touch_event` (boolean): 
        - `touch_start` (boolean): 
        - `max_touch_points` (integer int64): 
      - `oscpu` (string): Navigator `oscpu` string.
      - `architecture` (integer int32): Integer representing the CPU architecture exposed by the browser.
      - `cookies_enabled` (boolean): Whether the cookies are enabled in the browser.
      - `hardware_concurrency` (integer int32): Number of logical CPU cores reported by the browser.
      - `date_time_locale` (string): Locale derived from the Intl.DateTimeFormat API. Negative values indicate known error states. The negative statuses can be:
      - `vendor` (string): Navigator vendor string.
      - `color_depth` (integer int32): Screen color depth in bits.
      - `platform` (string): Navigator platform string.
      - `session_storage` (boolean): Whether sessionStorage is available.
      - `local_storage` (boolean): Whether localStorage is available.
      - `audio` (number double): AudioContext fingerprint or negative status when unavailable. The negative statuses can be:
      - `plugins` (array of object): Browser plugins reported by `navigator.plugins`.
        - `name` (string) (required): 
        - `description` (string): 
        - `mimeTypes` (array of object): 
      - `indexed_db` (boolean): Whether IndexedDB is available.
      - `math` (string): Hash of Math APIs used for entropy collection.
      - `device_model` (string): Device model string. Available only for Android and iOS devices.
      - `device_manufacturer` (string): Device manufacturer string. Available only for Android and iOS devices.
      - `font_hash` (string): Unique identifier for the user’s installed fonts.
      - `timezone_offset` (string): UTC offset in "±HH:MM" format derived from the detected IANA timezone.
      - `battery_level` (integer int32): Battery charge level as a percentage (0-100). Available for Android, iOS, and web devices. On web, only available in Chromium-based browsers.
      - `battery_charging` (boolean): When `true`, the device is currently charging. Available only for web devices on Chromium-based browsers.
      - `battery_low_power_mode` (boolean): Whether the device's low power mode is enabled. Available only for Android and iOS devices.
      - `keyboard_layout_hash` (string): Unique identifier for the user's keyboard layout.
      - `keyboard_layout_name` (string): Name of the user's configured keyboard layout as a BCP 47-style identifier. Only available in Chromium-based browsers, omitted otherwise.
    - `labels` (array of object): Each label returns a prediction (true or false) for a specific use case (label field) based on a machine learning score. The machine learning score is determined by a model trained on customer data for that use case. This field is in the beta phase and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/).
      - `label` (string) (required): Customer-facing label name defined by the customer.
      - `prediction` (boolean): 
      - `ml_score` (number double): Raw model score between 0 and 1.
  - `pagination_key` (string): Use this value in the `pagination_key` parameter to request the next page of search results.
  - `total_hits` (integer int64): This value represents the total number of events matching the search query, up to the limit provided in the `total_hits` query parameter. Only present if the `total_hits` query parameter was provided.
- `400`: Bad request. One or more supplied search parameters are invalid, or a required parameter is missing.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `403`: Forbidden. Access to this API is denied.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `404`: Not found. The requested visitor does not exist in this workspace's data.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `429`: Too Many Requests. The request is throttled.
To protect service stability during rare periods of extreme load, we may return HTTP 429 responses with message `too many search requests` even if you are within your assigned rate limits.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `500`: Workspace error.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `504`: Gateway Timeout. Search execution exceeded the allowed timeout window.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 

### DELETE /visitors/{visitor_id}
**Delete a visitor ID**
Use this API to request the deletion of all data associated with a specific visitor ID.

Upon a request to delete data for a visitor ID,
- The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID.
- The identification events made from this browser (or device) in the past 10 day...
Full URL: `https://api.fpjs.io/v4/visitors/{visitor_id}`
Tags: Visitors

**Parameters:**
- `visitor_id` [path] (string) (required): The [visitor ID](https://docs.fingerprint.com/reference/js-agent-get-function#visitor_id) you want to delete.

**Responses:**
- `200`: OK. The visitor ID is scheduled for deletion.
- `400`: Bad request. The visitor ID parameter is missing or in the wrong format.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `403`: Forbidden. Access to this API is denied.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `404`: Not found. The visitor ID cannot be found in this workspace's data.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 
- `429`: Too Many Requests. The request is throttled.
  - `error` (object) (required): 
    - `code` (enum: request_cannot_be_parsed | request_read_timeout | secret_api_key_required | secret_api_key_not_found | public_api_key_required | public_api_key_not_found | subscription_not_active | wrong_region | feature_not_enabled | visitor_not_found | too_many_requests | state_not_ready | failed | event_not_found | missing_module | payload_too_large | service_unavailable | ruleset_not_found) (required): Error code:
    - `message` (string) (required): 


## Fingerprint Management API
Source: https://docs.fingerprint.com/reference/management-api
Managment API allows you to manage your Fingerprint account and applications programmatically from a server environment.
Base URL: `https://management-api.fpjs.io`

**Authentication:**
- Management-API-key: http

### GET /health
**/health**
Full URL: `https://management-api.fpjs.io/health`

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: 

### GET /api-keys
**List API keys**
Lists all API keys for the workspace associated with the Management API key.
Full URL: `https://management-api.fpjs.io/api-keys`
Tags: api-keys

**Parameters:**
- `type` [query] (enum: public | secret | proxy) (optional): Filters by API key type.
- `status` [query] (enum: enabled | disabled) (optional): Filters by API key status.
- `environment` [query] (string) (optional): Filters by environment ID.
- `cursor` [query] (string) (optional): Cursor token used for pagination. Response will contain items appearing after the given cursor.
- `limit` [query] (number, default: 10) (optional): Sets the maximum number of items contained in a single page.
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of API keys matching the given query.
  - `data` (array of object) (required): 
    - `id` (string) (required): Auto-generated ID for an API key
    - `name` (string) (required): API key name
    - `description` (string): API key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (object) (required): ID of an environment the API key belongs to.
    - `type` (enum: public | secret | proxy) (required): Type of an API key.
    - `token` (string): Value of an API key. This field is immutable, and for secret keys it's only visible upon creation.
    - `rate_limit` (number) (required): Current limit in requests-per-second for the API key.
    - `created_at` (string date-time) (required): Date when API key was created.
    - `disabled_at` (string date-time): Date when API key was disabled.
  - `metadata` (object) (required): 
    - `pagination` (object) (required): Object containing pagination metadata.
      - `next_cursor` (string) (required): Cursor token to be used to get the next page of results.
      - `prev_cursor` (string) (required): Cursor token used to get the previous page of results.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /api-keys
**Create API key**
Creates an API key for the workspace associated with the Management API key. Maximum number of API keys in defined by your plan limits. If you need additional API keys, contact our support team.
Full URL: `https://management-api.fpjs.io/api-keys`
Tags: api-keys

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `type` (enum: public | secret | proxy) (required): Type of an API key.
- `name` (string) (required): Name of an API key.
- `description` (string): Description for an API key.
- `environment` (string): Environment in which to create an API key. If omitted for proxy or secret API keys, the key will be scoped to the workspace. If omitted for other types of keys, the API key will be created in the default environment.

**Responses:**
- `201`: Created API key object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an API key
    - `name` (string) (required): API key name
    - `description` (string): API key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (object) (required): ID of an environment the API key belongs to.
    - `type` (enum: public | secret | proxy) (required): Type of an API key.
    - `token` (string): Value of an API key. This field is immutable, and for secret keys it's only visible upon creation.
    - `rate_limit` (number) (required): Current limit in requests-per-second for the API key.
    - `created_at` (string date-time) (required): Date when API key was created.
    - `disabled_at` (string date-time): Date when API key was disabled.
- `400`: Error: API key can't be created due to validation errors.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /api-keys/{id}
**Get API key**
Fetch an API key by ID.
Full URL: `https://management-api.fpjs.io/api-keys/{id}`
Tags: api-keys

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: API key object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an API key
    - `name` (string) (required): API key name
    - `description` (string): API key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (object) (required): ID of an environment the API key belongs to.
    - `type` (enum: public | secret | proxy) (required): Type of an API key.
    - `token` (string): Value of an API key. This field is immutable, and for secret keys it's only visible upon creation.
    - `rate_limit` (number) (required): Current limit in requests-per-second for the API key.
    - `created_at` (string date-time) (required): Date when API key was created.
    - `disabled_at` (string date-time): Date when API key was disabled.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: API key with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### PATCH /api-keys/{id}
**Update API key**
Updates a single API key. You can update the keys name, description, status, and rate limit. You cannot mutate the actual key itself.
Full URL: `https://management-api.fpjs.io/api-keys/{id}`
Tags: api-keys

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `name` (string): Name of an API key.
- `description` (string): Description for an API key.
- `status` (enum: enabled | disabled): Set API key status. Use to enable or disable an API key.
- `rate_limit` (number): Set rate limit for an API key. Value is in request-per-second.

**Responses:**
- `200`: Updated API key object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an API key
    - `name` (string) (required): API key name
    - `description` (string): API key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (object) (required): ID of an environment the API key belongs to.
    - `type` (enum: public | secret | proxy) (required): Type of an API key.
    - `token` (string): Value of an API key. This field is immutable, and for secret keys it's only visible upon creation.
    - `rate_limit` (number) (required): Current limit in requests-per-second for the API key.
    - `created_at` (string date-time) (required): Date when API key was created.
    - `disabled_at` (string date-time): Date when API key was disabled.
- `400`: Error: API key can't be updated due to validation errors.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: API key with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### DELETE /api-keys/{id}
**Delete API key**
Deletes an API key with the given ID. Make sure that the key you are deleting is not used in production environment. This action is not reversible.
Full URL: `https://management-api.fpjs.io/api-keys/{id}`
Tags: api-keys

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `204`: Empty response indicating a successful operation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: API key with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /environments
**List environments**
Lists all environments for the workspace associated with the Management API key.
Full URL: `https://management-api.fpjs.io/environments`
Tags: environments

**Parameters:**
- `cursor` [query] (string) (optional): Cursor token used for pagination. Response will contain items appearing after the given cursor.
- `limit` [query] (number, default: 10) (optional): Sets the maximum number of items contained in a single page.
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of environments matching the given query.
  - `data` (array of object) (required): 
    - `id` (string) (required): Auto-generated ID for an environment
    - `name` (string) (required): Environment name
    - `description` (string): Environment description
    - `limit_mode` (enum: none | restrict | notify): Environment limit mode
    - `limit_value` (number): Environment limit value
    - `is_restricted` (boolean) (required): Whether the environment is restricted
    - `restricted_at` (string): Date when environment was restricted
    - `created_at` (string) (required): Date when environment was created
    - `updated_at` (string) (required): Date when environment was last updated
  - `metadata` (object) (required): 
    - `pagination` (object) (required): Object containing pagination metadata.
      - `next_cursor` (string) (required): Cursor token to be used to get the next page of results.
      - `prev_cursor` (string) (required): Cursor token used to get the previous page of results.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /environments
**Create an environment**
Creates a new environment for the workspace associated with the Management API key. Maximum number of environments in defined by your plan limits. If you need additional environments, contact our support team.
Full URL: `https://management-api.fpjs.io/environments`
Tags: environments

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `name` (string) (required): Name for the new environment
- `description` (string): Description for the environment
- `limit_mode` (enum: none | restrict | notify): Limit mode for the environment
- `limit_value` (number): Limit value for the environment (required when limitMode is not "none")

**Responses:**
- `201`: Created environment object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an environment
    - `name` (string) (required): Environment name
    - `description` (string): Environment description
    - `limit_mode` (enum: none | restrict | notify): Environment limit mode
    - `limit_value` (number): Environment limit value
    - `is_restricted` (boolean) (required): Whether the environment is restricted
    - `restricted_at` (string): Date when environment was restricted
    - `created_at` (string) (required): Date when environment was created
    - `updated_at` (string) (required): Date when environment was last updated
- `400`: Error: Environment can't be created due to validation errors.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /environments/{id}
**Update an environment**
Updates an environment with the given environment ID. You can update the name, description, and limit settings.
Full URL: `https://management-api.fpjs.io/environments/{id}`
Tags: environments

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `name` (string): Name for the environment
- `description` (string): Description for the environment
- `limit_mode` (enum: none | restrict | notify): Limit mode for the environment
- `limit_value` (number): Limit value for the environment (required when limitMode is not set to "none")

**Responses:**
- `200`: Updated environment object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an environment
    - `name` (string) (required): Environment name
    - `description` (string): Environment description
    - `limit_mode` (enum: none | restrict | notify): Environment limit mode
    - `limit_value` (number): Environment limit value
    - `is_restricted` (boolean) (required): Whether the environment is restricted
    - `restricted_at` (string): Date when environment was restricted
    - `created_at` (string) (required): Date when environment was created
    - `updated_at` (string) (required): Date when environment was last updated
- `400`: Error: Environment can't be updated due to validation errors.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Environment with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### DELETE /environments/{id}
**Delete an environment**
Deletes an environment with the given environment ID. You can only delete environments that don't have any active API keys associated with it.
Full URL: `https://management-api.fpjs.io/environments/{id}`
Tags: environments

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `204`: Empty response indicating a successful operation.
- `400`: Error: Environment can't be deleted due to validation errors.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Environment with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /filtering-rules
**List filtering rules**
Lists all filtering rules for the workspace associated with the Management API key. Supports filtering by environment, status, and name.
Full URL: `https://management-api.fpjs.io/filtering-rules`
Tags: filtering-rules

**Parameters:**
- `environment` [query] (string) (optional): Filters by environment ID.
- `status` [query] (enum: enabled | disabled) (optional): Filters by rule status.
- `name` [query] (string) (optional): Filters by rule name (partial match).
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of filtering rules matching the given query.
  - `data` (array of object) (required): 
    - `id` (string) (required): Auto-generated ID for the filtering rule
    - `name` (string) (required): Name of the filtering rule
    - `environment` (string) (required): Environment ID the rule belongs to
    - `expression` (string) (required): Expression in expr-lang format that defines the rule condition
    - `action` (enum: allow | deny) (required): Action to take when the rule matches
    - `status` (enum: enabled | disabled) (required): Status of the filtering rule
    - `deny_with` (string): Error message to return when denying a request
    - `created_at` (string date-time) (required): Date when the rule was created
    - `updated_at` (string date-time): Date when the rule was last updated
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /filtering-rules
**Create filtering rule**
Creates a new filtering rule. The rule will be evaluated in order based on the placement parameter. If no placement is specified, the rule is added to the end.
Full URL: `https://management-api.fpjs.io/filtering-rules`
Tags: filtering-rules

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `name` (string) (required): Name of the filtering rule
- `environment` (string) (required): Environment ID
- `expression` (string) (required): Expression in expr-lang format that defines the rule condition
- `action` (enum: allow | deny) (required): Action to take when the rule matches
- `status` (enum: enabled | disabled): Status of the filtering rule
- `deny_with` (enum: Forbidden): Error message to return when denying a request
- `placement` (object): Placement options for the rule
  - `position` (number): Position index to insert the rule at
  - `after` (string): ID of the rule to insert after
  - `before` (string): ID of the rule to insert before

**Responses:**
- `201`: Created filtering rule object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for the filtering rule
    - `name` (string) (required): Name of the filtering rule
    - `environment` (string) (required): Environment ID the rule belongs to
    - `expression` (string) (required): Expression in expr-lang format that defines the rule condition
    - `action` (enum: allow | deny) (required): Action to take when the rule matches
    - `status` (enum: enabled | disabled) (required): Status of the filtering rule
    - `deny_with` (string): Error message to return when denying a request
    - `created_at` (string date-time) (required): Date when the rule was created
    - `updated_at` (string date-time): Date when the rule was last updated
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /filtering-rules/v2-migration
**Migrate filtering rules from V1 to V2**
Migrates filtering rules from V1 to V2 format. Use the rollback query parameter to rollback to V1 instead.
Full URL: `https://management-api.fpjs.io/filtering-rules/v2-migration`
Tags: filtering-rules

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Migration or rollback completed successfully.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /filtering-rules/{id}
**Retrieve filtering rule**
Retrieves a single filtering rule by ID.
Full URL: `https://management-api.fpjs.io/filtering-rules/{id}`
Tags: filtering-rules

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Filtering rule object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for the filtering rule
    - `name` (string) (required): Name of the filtering rule
    - `environment` (string) (required): Environment ID the rule belongs to
    - `expression` (string) (required): Expression in expr-lang format that defines the rule condition
    - `action` (enum: allow | deny) (required): Action to take when the rule matches
    - `status` (enum: enabled | disabled) (required): Status of the filtering rule
    - `deny_with` (string): Error message to return when denying a request
    - `created_at` (string date-time) (required): Date when the rule was created
    - `updated_at` (string date-time): Date when the rule was last updated
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Filtering rule with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### DELETE /filtering-rules/{id}
**Delete filtering rule**
Deletes a filtering rule with the given ID. Make sure the rule is not critical for your production environment. This action is not reversible.
Full URL: `https://management-api.fpjs.io/filtering-rules/{id}`
Tags: filtering-rules

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `204`: Empty response indicating a successful operation.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Filtering rule with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /filtering-rules/{id}
**Update filtering rule**
Updates an existing filtering rule. Only provided fields will be updated.
Full URL: `https://management-api.fpjs.io/filtering-rules/{id}`
Tags: filtering-rules

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `name` (string): Name of the filtering rule
- `environment` (string): Environment ID
- `expression` (string): Expression in expr-lang format that defines the rule condition
- `action` (enum: allow | deny): Action to take when the rule matches
- `status` (enum: enabled | disabled): Status of the filtering rule
- `deny_with` (enum: Forbidden): Error message to return when denying a request
- `placement` (object): Placement options for the rule
  - `position` (number): Position index to insert the rule at
  - `after` (string): ID of the rule to insert after
  - `before` (string): ID of the rule to insert before
- `id` (string) (required): ID of the filtering rule

**Responses:**
- `200`: Updated filtering rule object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for the filtering rule
    - `name` (string) (required): Name of the filtering rule
    - `environment` (string) (required): Environment ID the rule belongs to
    - `expression` (string) (required): Expression in expr-lang format that defines the rule condition
    - `action` (enum: allow | deny) (required): Action to take when the rule matches
    - `status` (enum: enabled | disabled) (required): Status of the filtering rule
    - `deny_with` (string): Error message to return when denying a request
    - `created_at` (string date-time) (required): Date when the rule was created
    - `updated_at` (string date-time): Date when the rule was last updated
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Filtering rule with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /filtering-rules/bulk
**Bulk create/update filtering rules**
Creates or updates multiple filtering rules at once. In "merge" mode (default), rules with IDs are updated and rules without IDs are created. In "overwrite" mode, all existing rules for the given environment are deleted and replaced with the provided rules.
Full URL: `https://management-api.fpjs.io/filtering-rules/bulk`
Tags: filtering-rules

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `rules` (array of object) (required): Array of filtering rules to create or update
  - `name` (string) (required): Name of the filtering rule
  - `expression` (string) (required): Expression in expr-lang format that defines the rule condition
  - `action` (enum: allow | deny) (required): Action to take when the rule matches
  - `status` (enum: enabled | disabled): Status of the filtering rule
  - `deny_with` (enum: Forbidden): Error message to return when denying a request
  - `placement` (object): Placement options for the rule
    - `position` (number): Position index to insert the rule at
    - `after` (string): ID of the rule to insert after
    - `before` (string): ID of the rule to insert before
- `mode` (enum: merge | overwrite): Mode for bulk operation. "merge" (default) updates existing rules and creates new ones. "overwrite" deletes all existing rules for the environment and creates new ones.
- `environment` (string) (required): Environment ID

**Responses:**
- `200`: List of created/updated filtering rules.
  - `data` (array of object) (required): 
    - `id` (string) (required): Auto-generated ID for the filtering rule
    - `name` (string) (required): Name of the filtering rule
    - `environment` (string) (required): Environment ID the rule belongs to
    - `expression` (string) (required): Expression in expr-lang format that defines the rule condition
    - `action` (enum: allow | deny) (required): Action to take when the rule matches
    - `status` (enum: enabled | disabled) (required): Status of the filtering rule
    - `deny_with` (string): Error message to return when denying a request
    - `created_at` (string date-time) (required): Date when the rule was created
    - `updated_at` (string date-time): Date when the rule was last updated
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /filtering-rules/test
**Test filtering rules**
Tests filtering rules against a specified request ID or custom event payload. You can provide an existing request ID (up to 3 months old) or a custom JSON payload. Optionally, you can provide custom rules to test instead of using existing rules.
Full URL: `https://management-api.fpjs.io/filtering-rules/test`
Tags: filtering-rules

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `rules` (array of object): Array of rules to test. If omitted, provide environment ID to test against existing rules.
  - `expression` (string) (required): Expression in expr-lang format that defines the rule condition
  - `action` (enum: allow | deny) (required): Action to take when the rule matches
  - `deny_with` (enum: Forbidden): Error message to return when denying a request
- `environment` (string): Environment ID. Must be provided if rules are not
- `test_request_id` (string): Request ID to test against (up to 3 months old)
- `test_request_payload` (object): Request data to test against
  - `headers` (object): Request headers as key-value pairs with array values
  - `ip` (string): IP address of the request
  - `userAgent` (string): User agent string
  - `sdkPlatform` (enum: js | android | ios): SDK platform
  - `sdkVersion` (string): SDK version
  - `appPackageName` (string): Application package name

**Responses:**
- `200`: Test results showing which rule was triggered (if any) and the resulting action.
  - `data` (object) (required): 
    - `result` (enum: allow | deny) (required): Result of the test
    - `deny_with` (string) (required): Error message if request was denied
    - `triggered_rule` (string) (required): Expression of the triggered rule
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /webhooks/{webhookId}/rules
**List webhook rules**
Lists all rules for a webhook belonging to the workspace associated with the Management API key.
Full URL: `https://management-api.fpjs.io/webhooks/{webhookId}/rules`
Tags: webhook-rules

**Parameters:**
- `webhookId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of webhook rules matching the given query.
  - `data` (array of object) (required): 
    - `id` (string) (required): Auto-generated ID for a webhook rule
    - `name` (string) (required): Webhook rule name
    - `description` (string): Webhook rule description
    - `rule` (string) (required): Content of the rule
    - `createdAt` (string date-time) (required): Date when webhook rule was created
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Webhook with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /webhooks/{webhookId}/rules
**Create webhook rule**
Creates a rule for a webhook belonging to the workspace associated with the Management API key.  Maximum number of API keys in defined by your plan limits. If you need additional API keys, contact our support team.
Full URL: `https://management-api.fpjs.io/webhooks/{webhookId}/rules`
Tags: webhook-rules

**Parameters:**
- `webhookId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `name` (string) (required): 
- `description` (string) (required): 
- `rule` (string) (required): 

**Responses:**
- `201`: Created webhook rule object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for a webhook rule
    - `name` (string) (required): Webhook rule name
    - `description` (string): Webhook rule description
    - `rule` (string) (required): Content of the rule
    - `createdAt` (string date-time) (required): Date when webhook rule was created
- `400`: Error: Webhook rule can't be created due to validation errors.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Webhook with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### DELETE /webhooks/{webhookId}/rules/{id}
**Delete webhook rule**
Deletes a webhook rule with the given ID. Make sure that the key you are deleting is not used in production environment. This action is not reversible.
Full URL: `https://management-api.fpjs.io/webhooks/{webhookId}/rules/{id}`
Tags: webhook-rules

**Parameters:**
- `webhookId` [path] (string) (required): 
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `204`: Empty response indicating a successful operation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Webhook or webhook rule with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /webhooks
**List webhooks**
Lists all webhooks associated to the Management API key, optionally filtered by status.
Full URL: `https://management-api.fpjs.io/webhooks`
Tags: webhooks

**Parameters:**
- `status` [query] (enum: enabled | disabled) (optional): Filters by webhook status.
- `environment` [query] (string) (optional): Filters by webhook environment ID.
- `cursor` [query] (string) (optional): Cursor token used for pagination. Response will contain items appearing after the given cursor.
- `limit` [query] (number, default: 10) (optional): Sets the maximum number of items contained in a single page.
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of webhooks matching the given query.
  - `data` (array of object) (required): 
    - `id` (string) (required): Webhook ID.
    - `description` (string) (required): Description of the webhook.
    - `status` (enum: enabled | disabled) (required): Status of the webhook: 'enabled' or 'disabled'.
    - `verified` (boolean) (required): Indicates if the webhook endpoint has been verified.
    - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
    - `url` (string) (required): URL of the webhook endpoint. Must start with https://.
    - `legacy` (boolean) (required): True if webhook is legacy. See docs for more details.
    - `signing_key` (string): The signing key for verifying webhook payloads. Will only be returned on creation. See docs for more details.
    - `basic_auth` (object) (required): Basic authentication credentials. Only applies to legacy webhooks.
    - `created_at` (string date-time) (required): Timestamp of when the webhook was created.
    - `last_enabled_at` (object): Timestamp of when the webhook was last enabled.
    - `last_disabled_at` (object): Timestamp of when the webhook was last disabled.
  - `metadata` (object) (required): 
    - `pagination` (object) (required): Object containing pagination metadata.
      - `next_cursor` (string) (required): Cursor token to be used to get the next page of results.
      - `prev_cursor` (string) (required): Cursor token used to get the previous page of results.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Unauthorized. API key is invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Webhook does not exist.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /webhooks
**Create webhook**
Creates a new webhook in the workspace associated with the Management API key.
Webhook needs to be verified before it will start sending identification events to your server. See webhook verification.
If webhook signatures are enabled (enterprise only), signing key will be visible in the response after creation. When fetching webhooks after creation, signing key will not be visible!
See webhooks documentation for more details.
When specifying an environment during creation, webhook should be ass...
Full URL: `https://management-api.fpjs.io/webhooks`
Tags: webhooks

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `url` (string) (required): URL of the webhook endpoint. Must start with https://.
- `description` (string): Description of the webhook.
- `status` (enum: enabled | disabled): Status of the webhook: 'enabled' or 'disabled'.
- `environment` (object): Environment ID this webhook is associated with. Null if global.

**Responses:**
- `201`: Webhook created, but needs to be verified before it's active.
  - `data` (object) (required): 
    - `id` (string) (required): Webhook ID.
    - `description` (string) (required): Description of the webhook.
    - `status` (enum: enabled | disabled) (required): Status of the webhook: 'enabled' or 'disabled'.
    - `verified` (boolean) (required): Indicates if the webhook endpoint has been verified.
    - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
    - `url` (string) (required): URL of the webhook endpoint. Must start with https://.
    - `legacy` (boolean) (required): True if webhook is legacy. See docs for more details.
    - `signing_key` (string): The signing key for verifying webhook payloads. Will only be returned on creation. See docs for more details.
    - `basic_auth` (object) (required): Basic authentication credentials. Only applies to legacy webhooks.
    - `created_at` (string date-time) (required): Timestamp of when the webhook was created.
    - `last_enabled_at` (object): Timestamp of when the webhook was last enabled.
    - `last_disabled_at` (object): Timestamp of when the webhook was last disabled.
  - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Unauthorized. API key is invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Webhook does not exist.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /webhooks/{id}
**Get webhook by ID**
Fetch a specific webhook by ID.
Full URL: `https://management-api.fpjs.io/webhooks/{id}`
Tags: webhooks

**Parameters:**
- `id` [path] (string) (required): Webhook ID
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Webhook object.
  - `data` (object) (required): 
    - `id` (string) (required): Webhook ID.
    - `description` (string) (required): Description of the webhook.
    - `status` (enum: enabled | disabled) (required): Status of the webhook: 'enabled' or 'disabled'.
    - `verified` (boolean) (required): Indicates if the webhook endpoint has been verified.
    - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
    - `url` (string) (required): URL of the webhook endpoint. Must start with https://.
    - `legacy` (boolean) (required): True if webhook is legacy. See docs for more details.
    - `signing_key` (string): The signing key for verifying webhook payloads. Will only be returned on creation. See docs for more details.
    - `basic_auth` (object) (required): Basic authentication credentials. Only applies to legacy webhooks.
    - `created_at` (string date-time) (required): Timestamp of when the webhook was created.
    - `last_enabled_at` (object): Timestamp of when the webhook was last enabled.
    - `last_disabled_at` (object): Timestamp of when the webhook was last disabled.
  - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Unauthorized. API key is invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Webhook does not exist.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### PATCH /webhooks/{id}
**Update webhook**
Updates the webhook with the given ID. You can update the name, description, status, URL, and set basic authentication.
Changing the URL will require this webhook to be verified again.
Changing the status will disable/enable sending of identification events to your webhook.
Full URL: `https://management-api.fpjs.io/webhooks/{id}`
Tags: webhooks

**Parameters:**
- `id` [path] (string) (required): Webhook ID
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `url` (string): URL of the webhook endpoint. Must start with https://.
- `description` (string): Description of the webhook.
- `status` (enum: enabled | disabled): Status of the webhook: 'enabled' or 'disabled'.
- `environment` (object): Environment ID this webhook is associated with. Null if global.

**Responses:**
- `200`: Webhook updated. Changes will take effect in a few minutes.
  - `data` (object) (required): 
    - `id` (string) (required): Webhook ID.
    - `description` (string) (required): Description of the webhook.
    - `status` (enum: enabled | disabled) (required): Status of the webhook: 'enabled' or 'disabled'.
    - `verified` (boolean) (required): Indicates if the webhook endpoint has been verified.
    - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
    - `url` (string) (required): URL of the webhook endpoint. Must start with https://.
    - `legacy` (boolean) (required): True if webhook is legacy. See docs for more details.
    - `signing_key` (string): The signing key for verifying webhook payloads. Will only be returned on creation. See docs for more details.
    - `basic_auth` (object) (required): Basic authentication credentials. Only applies to legacy webhooks.
    - `created_at` (string date-time) (required): Timestamp of when the webhook was created.
    - `last_enabled_at` (object): Timestamp of when the webhook was last enabled.
    - `last_disabled_at` (object): Timestamp of when the webhook was last disabled.
  - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Unauthorized. API key is invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Webhook does not exist.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### DELETE /webhooks/{id}
**Delete webhook**
Deletes the webhook with the given ID. This action is not reversible. Changes will take affect in a few minutes.
Full URL: `https://management-api.fpjs.io/webhooks/{id}`
Tags: webhooks

**Parameters:**
- `id` [path] (string) (required): Webhook ID
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `204`: Empty response indicating a successful operation.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Unauthorized. API key is invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Webhook does not exist.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /webhooks/{id}/verification
**Verify webhook**
Send a mocked test event in order to verify your webhook endpoint, it needs to respond with HTTP 200 to be verified.
Webhook needs to be verified before it will receive identification events.
Full URL: `https://management-api.fpjs.io/webhooks/{id}/verification`
Tags: webhooks

**Parameters:**
- `id` [path] (string) (required): Webhook ID
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Webhook verification process initiated. Make sure webhook is active in order to receive identification events.
  - `data` (object) (required): 
    - `id` (string) (required): Webhook ID.
    - `description` (string) (required): Description of the webhook.
    - `status` (enum: enabled | disabled) (required): Status of the webhook: 'enabled' or 'disabled'.
    - `verified` (boolean) (required): Indicates if the webhook endpoint has been verified.
    - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
    - `url` (string) (required): URL of the webhook endpoint. Must start with https://.
    - `legacy` (boolean) (required): True if webhook is legacy. See docs for more details.
    - `signing_key` (string): The signing key for verifying webhook payloads. Will only be returned on creation. See docs for more details.
    - `basic_auth` (object) (required): Basic authentication credentials. Only applies to legacy webhooks.
    - `created_at` (string date-time) (required): Timestamp of when the webhook was created.
    - `last_enabled_at` (object): Timestamp of when the webhook was last enabled.
    - `last_disabled_at` (object): Timestamp of when the webhook was last disabled.
  - `environment` (object) (required): Environment ID this webhook is associated with. Null if global.
- `400`: Bad request. Webhook is already verified.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `401`: Unauthorized. API key is invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Webhook does not exist.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /encryption-keys
**List encryption keys**
Lists all encryption keys for the workspace associated with the Management API key.
Full URL: `https://management-api.fpjs.io/encryption-keys`
Tags: encryption-keys

**Parameters:**
- `status` [query] (enum: enabled | disabled) (optional): Filters by encryption key status.
- `environment` [query] (string) (optional): Filters by environment ID.
- `cursor` [query] (string) (optional): Cursor token used for pagination. Response will contain items appearing after the given cursor.
- `limit` [query] (number, default: 10) (optional): Sets the maximum number of items contained in a single page.
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of encryption keys matching the given query.
  - `data` (array of object) (required): 
    - `id` (string) (required): Auto-generated ID for an encryption key
    - `name` (string) (required): Encryption key name
    - `description` (string): Encryption key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (string) (required): ID of an environment the encryption key belongs to.
    - `previous_token` (string): Previous value of an encryption key. When a key is rotated, the previous value is stored so the rotation can be reverted. This field is immutable, and only visible upon creation.
    - `token` (string): Value of an encryption key. This field is immutable, and only visible upon creation.
    - `next_token` (string): Next value of an encryption key. Becomes the current value when a key is rotated.
    - `created_at` (string date-time) (required): Date when encryption key was created.
    - `last_activated_at` (string date-time) (required): Date when encryption key status was last changed to active.
    - `last_rotated_at` (string date-time) (required): Date when encryption key status was last rotated.
    - `last_deactivated_at` (string date-time): Date when encryption key was disabled.
  - `metadata` (object) (required): 
    - `pagination` (object) (required): Object containing pagination metadata.
      - `next_cursor` (string) (required): Cursor token to be used to get the next page of results.
      - `prev_cursor` (string) (required): Cursor token used to get the previous page of results.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /encryption-keys/{id}
**Get encryption key**
Fetch an encryption key by ID.
Full URL: `https://management-api.fpjs.io/encryption-keys/{id}`
Tags: encryption-keys

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Encryption key object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an encryption key
    - `name` (string) (required): Encryption key name
    - `description` (string): Encryption key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (string) (required): ID of an environment the encryption key belongs to.
    - `previous_token` (string): Previous value of an encryption key. When a key is rotated, the previous value is stored so the rotation can be reverted. This field is immutable, and only visible upon creation.
    - `token` (string): Value of an encryption key. This field is immutable, and only visible upon creation.
    - `next_token` (string): Next value of an encryption key. Becomes the current value when a key is rotated.
    - `created_at` (string date-time) (required): Date when encryption key was created.
    - `last_activated_at` (string date-time) (required): Date when encryption key status was last changed to active.
    - `last_rotated_at` (string date-time) (required): Date when encryption key status was last rotated.
    - `last_deactivated_at` (string date-time): Date when encryption key was disabled.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Encryption key with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### PATCH /encryption-keys/{id}
**Update encryption key**
Updates a single encryption key. You can update the keys name, description, and status. You cannot mutate the actual key itself.
Full URL: `https://management-api.fpjs.io/encryption-keys/{id}`
Tags: encryption-keys

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `name` (string): Set encryption key name.
- `description` (string): Set encryption key description.
- `status` (enum: enabled | disabled): Set encryption key status. Use to enable or disable an encryption key.

**Responses:**
- `200`: Updated encryption key object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an encryption key
    - `name` (string) (required): Encryption key name
    - `description` (string): Encryption key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (string) (required): ID of an environment the encryption key belongs to.
    - `previous_token` (string): Previous value of an encryption key. When a key is rotated, the previous value is stored so the rotation can be reverted. This field is immutable, and only visible upon creation.
    - `token` (string): Value of an encryption key. This field is immutable, and only visible upon creation.
    - `next_token` (string): Next value of an encryption key. Becomes the current value when a key is rotated.
    - `created_at` (string date-time) (required): Date when encryption key was created.
    - `last_activated_at` (string date-time) (required): Date when encryption key status was last changed to active.
    - `last_rotated_at` (string date-time) (required): Date when encryption key status was last rotated.
    - `last_deactivated_at` (string date-time): Date when encryption key was disabled.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Error: Encryption key with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /encryption-keys/{id}/rotate
**Rotate encryption key**
Full URL: `https://management-api.fpjs.io/encryption-keys/{id}/rotate`
Tags: encryption-keys

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Encryption key object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an encryption key
    - `name` (string) (required): Encryption key name
    - `description` (string): Encryption key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (string) (required): ID of an environment the encryption key belongs to.
    - `previous_token` (string): Previous value of an encryption key. When a key is rotated, the previous value is stored so the rotation can be reverted. This field is immutable, and only visible upon creation.
    - `token` (string): Value of an encryption key. This field is immutable, and only visible upon creation.
    - `next_token` (string): Next value of an encryption key. Becomes the current value when a key is rotated.
    - `created_at` (string date-time) (required): Date when encryption key was created.
    - `last_activated_at` (string date-time) (required): Date when encryption key status was last changed to active.
    - `last_rotated_at` (string date-time) (required): Date when encryption key status was last rotated.
    - `last_deactivated_at` (string date-time): Date when encryption key was disabled.
- `400`: Error: Bad request.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Encryption key with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /encryption-keys/{id}/revert
**Revert encryption key rotation**
Reverts the last encryption key rotation.
Full URL: `https://management-api.fpjs.io/encryption-keys/{id}/revert`
Tags: encryption-keys

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Encryption key object.
  - `data` (object) (required): 
    - `id` (string) (required): Auto-generated ID for an encryption key
    - `name` (string) (required): Encryption key name
    - `description` (string): Encryption key description
    - `status` (enum: enabled | disabled) (required): API key status, indicates if an API keys is enabled or disabled.
    - `environment` (string) (required): ID of an environment the encryption key belongs to.
    - `previous_token` (string): Previous value of an encryption key. When a key is rotated, the previous value is stored so the rotation can be reverted. This field is immutable, and only visible upon creation.
    - `token` (string): Value of an encryption key. This field is immutable, and only visible upon creation.
    - `next_token` (string): Next value of an encryption key. Becomes the current value when a key is rotated.
    - `created_at` (string date-time) (required): Date when encryption key was created.
    - `last_activated_at` (string date-time) (required): Date when encryption key status was last changed to active.
    - `last_rotated_at` (string date-time) (required): Date when encryption key status was last rotated.
    - `last_deactivated_at` (string date-time): Date when encryption key was disabled.
- `400`: Error: No rotation to revert.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `403`: Forbidden. Insufficient permissions.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Encryption key with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Error: Payload parameters are invalid.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### PUT /marketplace/vercel/v1/installations/{installationId}
**Upsert Vercel installation**
Called by Vercel when a user installs or updates the integration.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `scopes` (array of string) (required): 
- `acceptedPolicies` (object) (required): 
- `credentials` (object) (required): 
  - `access_token` (string) (required): 
  - `token_type` (string) (required): 
- `account` (object): 
  - `name` (string): 
  - `email` (string): 

**Responses:**
- `201`: Installation created/updated successfully.
- `401`: Invalid Vercel JWT.

### GET /marketplace/vercel/v1/installations/{installationId}
**Get Vercel installation**
Called by Vercel to retrieve the current installation status.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Installation details returned.

### DELETE /marketplace/vercel/v1/installations/{installationId}
**Delete Vercel installation**
Called by Vercel when a user uninstalls the integration.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `cascadeResourceDeletion` (boolean): Whether to delete the installation resources along with the installation.
- `reason` (string): The reason for deleting the installation.

**Responses:**
- `204`: 

### POST /marketplace/vercel/v1/installations/{installationId}/resources
**Provision a Fingerprint resource (workspace)**
Called by Vercel when a user creates a new Fingerprint resource.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}/resources`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `productId` (string) (required): The partner-specific product ID/slug.
- `name` (string) (required): User-inputted name for the resource.
- `metadata` (object) (required): User-inputted metadata based on the registered metadata schema.
- `billingPlanId` (enum: free-trial | pro-plus | freemium) (required): Partner-provided billing plan ID.
- `externalId` (string): External ID for tracking the source of provisioning.

**Responses:**
- `200`: Resource provisioned successfully.
- `401`: Invalid Vercel JWT.

### GET /marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}
**Get a Fingerprint resource**
Called by Vercel to retrieve resource status.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `resourceId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Resource details returned.

### PATCH /marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}
**Update a Fingerprint resource**
Called by Vercel to apply plan changes or update metadata.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `resourceId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `name` (string): User-inputted name for the resource.
- `metadata` (object): User-inputted metadata.
- `billingPlanId` (enum: free-trial | pro-plus | freemium): Partner-provided billing plan ID.

**Responses:**
- `200`: Resource updated successfully.

### DELETE /marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}
**Delete a Fingerprint resource**
Called by Vercel to decommission a workspace.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `resourceId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `204`: 

### GET /marketplace/vercel/v1/products/{productSlug}/plans
**List billing plans for a product**
Returns available billing plans for the Fingerprint integration.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/products/{productSlug}/plans`
Tags: marketplace-vercel

**Parameters:**
- `productSlug` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of billing plans.
- `401`: Invalid Vercel JWT.

### GET /marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}/plans
**List billing plans available for a resource**
Returns upgrade/downgrade options for an existing workspace.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}/plans`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `resourceId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of available billing plans for this resource.

### GET /marketplace/vercel/v1/installations/{installationId}/plans
**List billing plans for an installation**
Returns billing plans available at the installation level.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}/plans`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of billing plans.

### POST /marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}/secrets/rotate
**Rotate resource secrets**
Called by Vercel when a user requests credential rotation.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/v1/installations/{installationId}/resources/{resourceId}/secrets/rotate`
Tags: marketplace-vercel

**Parameters:**
- `installationId` [path] (string) (required): 
- `resourceId` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `reason` (string): Reason for the secrets rotation request.
- `delayOldSecretsExpirationHours` (number): Delay in hours before old secrets expire after rotation (0-720).

**Responses:**
- `401`: Invalid Vercel JWT.

### GET /marketplace/vercel/callback
**Vercel OAuth callback (GET)**
Called by Vercel after user authorizes the integration via SSO.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/callback`
Tags: marketplace-vercel

**Parameters:**
- `code` [query] (string) (required): 
- `state` [query] (string) (required): 
- `resource_id` [query] (string) (required): 
- `project_id` [query] (string) (required): 
- `invoice_id` [query] (string) (required): 
- `check_id` [query] (string) (required): 
- `support` [query] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: 

### POST /marketplace/vercel/callback
**Vercel OAuth callback (POST)**
Called by Vercel after user authorizes the integration via SSO.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/callback`
Tags: marketplace-vercel

**Parameters:**
- `code` [query] (string) (required): 
- `state` [query] (string) (required): 
- `resource_id` [query] (string) (required): 
- `project_id` [query] (string) (required): 
- `invoice_id` [query] (string) (required): 
- `check_id` [query] (string) (required): 
- `support` [query] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `201`: 

### POST /marketplace/vercel/webhook
**Receive Vercel webhook events**
Called by Vercel to deliver integration events.
Full URL: `https://management-api.fpjs.io/marketplace/vercel/webhook`
Tags: marketplace-vercel

**Parameters:**
- `x-vercel-signature` [header] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: 

### GET /subdomains
**List subdomains**
Lists all custom subdomains for the workspace associated with the Management API key.
Full URL: `https://management-api.fpjs.io/subdomains`
Tags: subdomains

**Parameters:**
- `status` [query] (enum: pending | active | timed_out | failed) (optional): Filter by subdomain status
- `cursor` [query] (string) (optional): Cursor token used for pagination. Response will contain items appearing after the given cursor.
- `limit` [query] (number, default: 10) (optional): Sets the maximum number of items contained in a single page.
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: List of subdomains matching the given query.
  - `data` (array of object) (required): 
    - `id` (string) (required): Subdomain ID
    - `subdomain` (string) (required): Subdomain hostname
    - `status` (enum: pending | active | timed_out | failed) (required): Current subdomain status. `pending` = DNS/certificate setup in progress; `active` = live and serving traffic; `timed_out` = setup timed out (usually the required DNS records were never added) — safe to delete and recreate; `failed` = terminal failure.
    - `created_at` (string date-time) (required): When the subdomain was created
    - `updated_at` (string date-time) (required): When the subdomain was last updated
  - `metadata` (object) (required): 
    - `pagination` (object) (required): Object containing pagination metadata.
      - `next_cursor` (string) (required): Cursor token to be used to get the next page of results.
      - `prev_cursor` (string) (required): Cursor token used to get the previous page of results.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /subdomains
**Create subdomain**
Register a new custom subdomain and receive its DNS records. Optionally pass `webhook_url` to get a signed POST callback on every status change instead of polling; the signing secret is returned once in this response as `webhook_secret`.
Full URL: `https://management-api.fpjs.io/subdomains`
Tags: subdomains

**Parameters:**
- `X-API-Version` [header] (string) (required): Management API version.

**Request Body:**
Content-Type: `application/json`
- `subdomain` (string) (required): The FQDN to register as a custom subdomain.
- `webhook_url` (string): HTTPS URL that receives a signed POST callback each time the subdomain status changes, removing the need to poll `GET /subdomains/{id}`. The URL must be publicly reachable — IP addresses, custom ports and hosts resolving to private networks are rejected. Deliveries are signed; see `webhook_secret` in the create response for the verification scheme.

**Responses:**
- `201`: Subdomain created.
  - `data` (object) (required): 
    - `id` (string) (required): Subdomain ID
    - `subdomain` (string) (required): Subdomain hostname
    - `status` (enum: pending | active | timed_out | failed) (required): Current subdomain status. `pending` = DNS/certificate setup in progress; `active` = live and serving traffic; `timed_out` = setup timed out (usually the required DNS records were never added) — safe to delete and recreate; `failed` = terminal failure.
    - `created_at` (string date-time) (required): When the subdomain was created
    - `updated_at` (string date-time) (required): When the subdomain was last updated
    - `webhook_url` (string): HTTPS URL receiving a signed POST callback on every status change. Null when not configured. Set at creation only — subdomains are immutable.
    - `dns_records` (object) (required): 
      - `verification` (object) (required): 
        - `type` (string) (required): DNS record type the customer must create.
        - `host` (string) (required): Host/name of the DNS record.
        - `value` (string) (required): Value the DNS record must point to.
        - `status` (enum: pending_validation | validated | failed) (required): Whether this individual record has been detected and validated yet.
      - `routing` (array of object) (required): 
        - `type` (string) (required): DNS record type the customer must create.
        - `host` (string) (required): Host/name of the DNS record.
        - `value` (string) (required): Value the DNS record must point to.
        - `status` (enum: pending_validation | validated | failed) (required): Whether this individual record has been detected and validated yet.
    - `webhook_secret` (string): Secret for verifying status webhook signatures. **Only returned on creation — store it now; it cannot be retrieved later.** Null when no `webhook_url` was provided.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `409`: Subdomain already exists in this workspace, or workspace subdomain limit reached.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `422`: Invalid subdomain or request body.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
    - `violations` (array of object): List of validation violations.
      - `property` (string) (required): Property that has failed validation.
      - `message` (string) (required): Description of the violation.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### GET /subdomains/{id}
**Get subdomain**
Fetch a subdomain by ID.
Full URL: `https://management-api.fpjs.io/subdomains/{id}`
Tags: subdomains

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Subdomain object.
  - `data` (object) (required): 
    - `id` (string) (required): Subdomain ID
    - `subdomain` (string) (required): Subdomain hostname
    - `status` (enum: pending | active | timed_out | failed) (required): Current subdomain status. `pending` = DNS/certificate setup in progress; `active` = live and serving traffic; `timed_out` = setup timed out (usually the required DNS records were never added) — safe to delete and recreate; `failed` = terminal failure.
    - `created_at` (string date-time) (required): When the subdomain was created
    - `updated_at` (string date-time) (required): When the subdomain was last updated
    - `webhook_url` (string): HTTPS URL receiving a signed POST callback on every status change. Null when not configured. Set at creation only — subdomains are immutable.
    - `dns_records` (object) (required): 
      - `verification` (object) (required): 
        - `type` (string) (required): DNS record type the customer must create.
        - `host` (string) (required): Host/name of the DNS record.
        - `value` (string) (required): Value the DNS record must point to.
        - `status` (enum: pending_validation | validated | failed) (required): Whether this individual record has been detected and validated yet.
      - `routing` (array of object) (required): 
        - `type` (string) (required): DNS record type the customer must create.
        - `host` (string) (required): Host/name of the DNS record.
        - `value` (string) (required): Value the DNS record must point to.
        - `status` (enum: pending_validation | validated | failed) (required): Whether this individual record has been detected and validated yet.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Subdomain with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### DELETE /subdomains/{id}
**Delete subdomain**
Delete a subdomain by ID.
Full URL: `https://management-api.fpjs.io/subdomains/{id}`
Tags: subdomains

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `204`: Subdomain deleted.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Subdomain ID does not exist in this workspace.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.

### POST /subdomains/{id}/verify
**Verify subdomain**
Trigger manual verification for a subdomain.
Full URL: `https://management-api.fpjs.io/subdomains/{id}/verify`
Tags: subdomains

**Parameters:**
- `id` [path] (string) (required): 
- `X-API-Version` [header] (string) (required): Management API version.

**Responses:**
- `200`: Subdomain object.
  - `data` (object) (required): 
    - `id` (string) (required): Subdomain ID
    - `subdomain` (string) (required): Subdomain hostname
    - `status` (enum: pending | active | timed_out | failed) (required): Current subdomain status. `pending` = DNS/certificate setup in progress; `active` = live and serving traffic; `timed_out` = setup timed out (usually the required DNS records were never added) — safe to delete and recreate; `failed` = terminal failure.
    - `created_at` (string date-time) (required): When the subdomain was created
    - `updated_at` (string date-time) (required): When the subdomain was last updated
    - `webhook_url` (string): HTTPS URL receiving a signed POST callback on every status change. Null when not configured. Set at creation only — subdomains are immutable.
    - `dns_records` (object) (required): 
      - `verification` (object) (required): 
        - `type` (string) (required): DNS record type the customer must create.
        - `host` (string) (required): Host/name of the DNS record.
        - `value` (string) (required): Value the DNS record must point to.
        - `status` (enum: pending_validation | validated | failed) (required): Whether this individual record has been detected and validated yet.
      - `routing` (array of object) (required): 
        - `type` (string) (required): DNS record type the customer must create.
        - `host` (string) (required): Host/name of the DNS record.
        - `value` (string) (required): Value the DNS record must point to.
        - `status` (enum: pending_validation | validated | failed) (required): Whether this individual record has been detected and validated yet.
- `401`: Error: Invalid API key.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `404`: Subdomain with the given ID was not found.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.
- `429`: Error: API key has exceeded its rate limit.
  - `error` (object) (required): 
    - `message` (string) (required): Verbal description of the error.
    - `code` (string) (required): Error code.


## Fingerprint Related Visitors API
Source: https://docs.fingerprint.com/reference/related-visitors-api
> 🚧 Deprecation Notice
>
> This version of Server API is marked as deprecated starting on **Jan 7th 2026** and will be fully defunct on **Jan 7th 2027** according to our [API Deprecation Policy](https://dev.fingerprint.com/reference/api-deprecation-policy). If you still use this version, please fol
Base URL: `https://api.fpjs.io`

**Authentication:**
- ApiKeyHeader: apiKey in header as `Auth-API-Key`
- ApiKeyQuery: apiKey in query as `api_key`

### GET /related-visitors
**Get Related Visitors**
> 🚧 Deprecation Notice
>
> This version of Server API is marked as deprecated starting on **Jan 7th 2026** and will be fully removed on **Jan 7th 2027** according to our [API Deprecation Policy](https://dev.fingerprint.com/reference/api-deprecation-policy).

Related visitors API lets you link web visits and in-app browser visits that originated from the same mobile device.
It searches the past 6 months of identification events to find the visitor IDs that belong to the same mobile device as the...
Full URL: `https://api.fpjs.io/related-visitors`
Tags: Related Visitors

**Parameters:**
- `visitor_id` [query] (string) (required): The [visitor ID](https://dev.fingerprint.com/reference/get-function#visitorid) for which you want to find the other visitor IDs that originated from the same mobile device.

**Responses:**
- `200`: OK.
  - `relatedVisitors` (array of object) (required): 
    - `visitorId` (string) (required): Visitor ID of a browser that originates from the same mobile device as the input visitor ID.
- `400`: Bad request. The visitor ID parameter is missing or in the wrong format.
  - `error` (object) (required): 
    - `code` (enum: RequestCannotBeParsed | TokenRequired | TokenNotFound | SubscriptionNotActive | WrongRegion | FeatureNotEnabled | RequestNotFound | VisitorNotFound | TooManyRequests | 429 Too Many Requests | StateNotReady | Failed) (required): Error code:
    - `message` (string) (required): 
- `403`: Forbidden. Access to this API is denied.
  - `error` (object) (required): 
    - `code` (enum: RequestCannotBeParsed | TokenRequired | TokenNotFound | SubscriptionNotActive | WrongRegion | FeatureNotEnabled | RequestNotFound | VisitorNotFound | TooManyRequests | 429 Too Many Requests | StateNotReady | Failed) (required): Error code:
    - `message` (string) (required): 
- `404`: Not found. The visitor ID cannot be found in this application's data.
  - `error` (object) (required): 
    - `code` (enum: RequestCannotBeParsed | TokenRequired | TokenNotFound | SubscriptionNotActive | WrongRegion | FeatureNotEnabled | RequestNotFound | VisitorNotFound | TooManyRequests | 429 Too Many Requests | StateNotReady | Failed) (required): Error code:
    - `message` (string) (required): 
- `429`: Too Many Requests. The request is throttled.
  - `error` (object) (required): 
    - `code` (enum: RequestCannotBeParsed | TokenRequired | TokenNotFound | SubscriptionNotActive | WrongRegion | FeatureNotEnabled | RequestNotFound | VisitorNotFound | TooManyRequests | 429 Too Many Requests | StateNotReady | Failed) (required): Error code:
    - `message` (string) (required): 


## Fingerprint DRN API
Source: https://docs.fingerprint.com/reference/drn-api-overview
Device Reputation Network (DRN) [API](https://dev.fingerprint.com/reference/drn-api)
Base URL: `https://drn-api.fpjs.io`

**Authentication:**
- SecretAPIKey: http

### GET /drn/{visitorId}
**Returns device reputation information of a visitor.**
Returns device reputation information of a visitor.
Full URL: `https://drn-api.fpjs.io/drn/{visitorId}`

**Parameters:**
- `X-API-Version` [header] (string, default: 2024-09-01) (required): The API version to use.
- `visitorId` [path] (string) (required): The visitor id to get information on.
- `signals` [query] (array of enum: regional_activity | suspect_score | timestamps) (required): The information signals to retrieve.

**Responses:**
- `200`: A JSON object representing reputation information related to requested signals.
  - `data` (object): Object containing properties of the signals requested
    - `regionalActivity` (object): 
      - `startDate` (string date): 
      - `endDate` (string date): 
      - `countries` (array of object): 
        - `code` (string): 
        - `detectors` (array of object): 
    - `suspectScore` (object): 
      - `startDate` (string date): 
      - `endDate` (string date): 
      - `minimum` (object): 
        - `value` (number): 
        - `signals` (object): 
      - `maximum` (object): 
        - `value` (number): 
        - `percentile` (number float): 
        - `signals` (object): 
    - `timestamps` (object): 
      - `firstSeentAt` (string date): 
      - `lastSeenAt` (string date): 
- `400`: Bad request
  - `error` (object): 
    - `code` (string): 
    - `message` (string): 
    - `requestId` (string): 
- `401`: Unauthorized
  - `error` (object): 
    - `code` (string): 
    - `message` (string): 
    - `requestId` (string): 
- `403`: Forbidden
  - `error` (object): 
    - `code` (string): 
    - `message` (string): 
    - `requestId` (string): 
- `404`: Visitor not found
  - `error` (object): 
    - `code` (string): 
    - `message` (string): 
    - `requestId` (string): 
- `500`: Unexpected error
  - `error` (object): 
    - `code` (string): 
    - `message` (string): 
    - `requestId` (string):