# Quick start guide Source: /docs/quickstart # Quickstart From nothing to a verified event in about 15 minutes. You need Docker with Compose, and a page you can edit (any local HTML file served over `http://localhost` works). ## 1. Start Trace (one command) You need [Docker](https://docs.docker.com/get-docker/). Then: ```sh git clone https://github.com/trace-id/trace.git cd trace ./setup.sh # Windows PowerShell: .\setup.ps1 ``` That's all. The script creates `docker/.env` with random secrets the first time (and keeps it afterwards), starts the database, Redis, the server and the dashboard, waits until they are ready, and prints: ```text Trace is running. Dashboard: http://localhost:3000 API: http://localhost:8080 ``` The first start builds the images and takes a few minutes; later starts take seconds. Stop with `docker compose -f docker/compose.yml down`.

Ports in use?

Set `SERVER_PORT` or `DASHBOARD_PORT` in `docker/.env` and run the script again. If you change the dashboard's address, also set `DASHBOARD_URL` to exactly the URL you open in the browser.
Without the script Copy `docker/.env.example` to `docker/.env`, set `POSTGRES_PASSWORD`, `TOKEN_SECRET` and `AUTH_SECRET` to 32 or more random letters and digits each (for example `openssl rand -hex 32`; avoid `/` and `+`, which break the database URL), then run `docker compose -f docker/compose.yml up --build -d`.
## 2. Create your account and keys (3 minutes) 1. Open `http://localhost:3000` and choose **Create an account**. The first account becomes the administrator; further sign-ups are closed unless you enable them. 2. Create a project. 3. On **Keys**, create a **public** key. Under allowed origins, enter the origin of the page that will load the SDK, for example `http://localhost:5500`. Copy the `pk_...` key. 4. Create a **secret** key and copy the `sk_...` key. Both are shown only once. ## 3. Add the SDK to a page (3 minutes) The server hosts the browser SDK itself. Add this to your page and replace the key: ```html


```

Serve the page from the origin you allowed (for example `npx serve -l 5500` in its folder) and click **Identify**. You get an `eventId` and a `visitorId`. Open the page in a private window and click again: the `visitorId` should match.

Origin not allowed?

The page's origin must match an allowed origin on the public key exactly, including the port. `file://` pages have no usable origin; serve the page over `http://localhost`.
## 4. Verify on your backend (2 minutes) Never trust the result in the browser. Send the `eventId` to your server and fetch the verified event with the secret key: ```sh curl -H "Authorization: Bearer sk_REPLACE_ME" http://localhost:8080/v1/events/EVENT_ID ``` Or from Node 18+: ```js const res = await fetch(`http://localhost:8080/v1/events/${eventId}`, { headers: { Authorization: `Bearer ${process.env.SECRET_KEY}` }, signal: AbortSignal.timeout(2000), }); const event = await res.json(); // visitorId, suspectScore, reasons, signals, ... ``` Events can be verified for 60 minutes. The response explains the score in `reasons`. ## 5. Look around (2 minutes) Back in the dashboard, **Overview** shows the events per day, **Events** lets you search by `linkedId`, visitor or score, and each event page explains its score signal by signal. ## Next steps - Decide what happens when the service is slow or down: [fail open or fail closed](/integration#fail-open-or-fail-closed). - Use the [React SDK](/integration#react) or install the SDKs from npm. - Before going live: TLS, `TRUST_PROXY`, backups and IP data in the [self-hosting guide](/self-hosting). - Receive [signed webhooks](/api#webhooks) instead of polling. --- # How Trace works Source: /docs/overview # Overview Trace is an open-source, self-hostable service that recognises returning devices and flags risky ones. A page loads the browser SDK, which collects device signals and sends them to your server. The server answers with a stable `visitorId`, a suspect score and the reasons behind it. Your backend then verifies the event with a secret key before trusting it. It runs entirely on your infrastructure. No data leaves your deployment unless you configure an external provider. ## What you get - **Visitor identification** that survives private windows, cleared cookies and minor browser updates, with a confidence value. - **Signals:** bot and automation, browser tampering, Tor, datacenter IPs, IP blocklists, velocity, incognito, developer tools, virtual machines, privacy-focused browsers and high-activity devices. Every event explains which signals contributed to its score. - **Server-side verification** (`GET /v1/events/:eventId`), visitor history, deletion for privacy requests, signed webhooks. - **A dashboard** for projects, keys, events, visitors, usage and webhooks. - **SDKs:** browser (npm or one script tag), React, Node. ## How it fits together ``` Browser (SDK) --POST /v1/identify, public key--> server --> Postgres, Redis Your backend --GET /v1/events/:id, secret key--> server Dashboard --session cookie--> server ``` ## Honest expectations Identification accuracy is measured on labeled and synthetic data and published on the [accuracy page](/accuracy). It is well below commercial services on real traffic, and client-side signals can be spoofed by a determined attacker. Use the score as one input next to your own defences, and start in shadow mode. Next: the [15-minute quickstart](/quickstart). --- # Install with AI Source: /docs/agents # AI agents and MCP Trace is built to be used by AI agents as well as people: an MCP server for assistants such as Claude, a machine-readable API description, docs in a form language models read well, and a prompt that lets a coding agent integrate it into your app. ## MCP server `@trace-id/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server. It gives an assistant read-only access to your project through your secret key, so you can ask "why was this signup blocked?" or "which other accounts used this device?" in plain language. | Tool | What it does | | --- | --- | | `explain_event` | The verdict for an event's suspect score, which signals fired and why, when each can be wrong, other browsers on the same device | | `get_event` | The full verified event (same as `GET /v1/events/:eventId`) | | `get_visitor` | A visitor's history, paginated | | `get_device` | Every browser and account on one device (multi-accounting investigations) | | `list_signals` | The signal catalog, offline | | `delete_visitor` | Permanent deletion for a data request. Only present with `TRACE_ALLOW_DELETE=true`, marked destructive, and requires `confirm: true` | Configuration is two environment variables: `TRACE_ENDPOINT` (your server, e.g. `https://id.example.com`) and `TRACE_SECRET_KEY` (`sk_...`). Use a separate secret key for the assistant so you can revoke it on its own. Claude Code: ```sh claude mcp add trace -e TRACE_ENDPOINT=https://id.example.com -e TRACE_SECRET_KEY=sk_... -- npx -y @trace-id/mcp ``` Claude Desktop, Cursor and other clients that read an `mcpServers` file: ```json { "mcpServers": { "trace": { "command": "npx", "args": ["-y", "@trace-id/mcp"], "env": { "TRACE_ENDPOINT": "https://id.example.com", "TRACE_SECRET_KEY": "sk_..." } } } } ``` From a checkout (before the package is published), use `"command": "node", "args": ["/path/to/trace/packages/mcp-server/dist/cli.js"]` after `npm run build`. The server speaks MCP over stdio (protocol versions 2025-06-18, 2025-03-26 and 2024-11-05) and writes nothing but protocol messages to stdout. API failures come back as tool errors the model can read (`invalid_api_key (HTTP 401): ...`), not as crashes. ## OpenAPI Every server publishes its API description at `GET /openapi.json` (OpenAPI 3.1, no key needed). Point client generators, API tools or agents with an HTTP tool at it. It covers identify, events, visitors, devices, webhooks and health, including every signal id. ## Docs for language models The docs site serves [`/llms.txt`](/llms.txt), an index of every page, and [`/llms-full.txt`](/llms-full.txt), all pages in one plain-text file, following the [llms.txt convention](https://llmstxt.org). Give either to an assistant before asking it about trace. ## Integrating with a coding agent Paste this into Claude Code, Cursor or a similar agent in your app's repository, after filling in the two values: ```text Integrate Trace device identification into this app. Server: https://id.example.com (public key pk_..., secret key in the TRACE_SECRET_KEY environment variable). Docs: https:///llms-full.txt and the API at https://id.example.com/openapi.json. 1. Add the browser SDK for this app's framework (@trace-id/sdk-js, sdk-react, sdk-vue or sdk-svelte). Call it on signup, login and checkout with linkedId set to our internal user id (never an email), and send the returned eventId with the form request. 2. On the backend, verify that eventId with the server SDK for this language (sdk-node, Python, PHP, Java) or GET /v1/events/:eventId. Never trust the visitorId or score the browser sends. 3. Policy: suspectScore >= 60 -> block or challenge; 25-59 -> challenge; signals.multiAccount.detected -> flag for review. Log the eventId with the decision. 4. If the Trace call fails or times out (2 s), let the request continue (fail open) and log it. 5. Add tests with the SDK mocked, and show me the diff. ``` The agent finds the rest in the docs: consent (`enabled: false`), first-party mode, webhooks and sealed results. ## Agents as visitors Browser agents (computer-use assistants, headless automation) are bots by definition and the `bot`, `automatedInput` and `antiDetect` signals are designed to see them. If you want to admit some, decide on your backend: for example allow a known agent's requests by your own authentication, and use the signals only for anonymous traffic. --- # JavaScript Source: /docs/javascript # JavaScript This quickstart adds Trace to any web page with the framework-free browser SDK. You will identify the visitor when they submit a form and send the resulting `eventId` to your backend, where it gets verified. The example protects a sign-up form, but the steps are the same for login, checkout or any other action.

Before you start

You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your page. The [quick start guide](quickstart.md) gets you both in about five minutes. Using [embedded mode](embedded.md)? Your endpoint is the route you mounted, for example `https://api.yourapp.com/trace`.
## 1. Install the SDK ::: code-group ```sh [npm] npm install @trace-id/sdk-js ``` ```sh [pnpm] pnpm add @trace-id/sdk-js ``` ```sh [yarn] yarn add @trace-id/sdk-js ``` ```sh [bun] bun add @trace-id/sdk-js ``` ::: No bundler? The Trace server hosts the same SDK as one file at `/sdk/sdk.esm.js`: ```html ``` ## 2. Create a client Create one client when the page loads. It starts collecting device signals in the background, so the call you make later is fast. ```ts import { createClient } from '@trace-id/sdk-js'; const trace = createClient({ apiKey: 'pk_...', // public key; never a secret key endpoint: 'https://id.example.com', // your Trace server }); ``` ## 3. Identify on the action you protect Call `get()` when the user submits, and pass your own user id as `linkedId` when you have one. Send the `eventId` along with the form. ```ts const form = document.querySelector('#signup'); form.addEventListener('submit', async (e) => { e.preventDefault(); let eventId = null; try { ({ eventId } = await trace.get({ tags: { action: 'signup' } })); } catch (err) { console.warn('Trace unavailable', err.code); // fail open: keep going without it } await fetch('/api/signup', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ...Object.fromEntries(new FormData(form)), eventId }), }); }); ``` `get()` resolves with: ```json { "eventId": "01934f6e-8b7a-7c2e-9f51-3a0d5e2b9c41", "visitorId": "Xk3pQ9vLmT2aR7sBn4Wc", "deviceId": "Xk3pQ9vLmT2aR7sBn4Wc", "confidence": 0.98, "suspectScore": 0 } ```

Do not decide in the browser

Anything the browser returns can be changed by the person using it. Use the `eventId` only as a reference and read the real result on your server.
## 4. Verify on your server Your backend fetches the event with a secret key and decides. Pick your language: ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent from @trace-id/sdk-node - [Python](python.md) brand:python: Client.get_event from trace-device - [PHP](php.md) brand:php: Client::getEvent from trace/trace - [Java](java.md) brand:openjdk: getEvent from dev.trace:trace ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a sign-up decision - [Browser SDK reference](browser-sdk.md): Every option, the result and error codes - [Consent](integration.md#consent): Start disabled and enable after consent ::: --- # React Source: /docs/react # React This quickstart adds Trace to a React app with `@trace-id/sdk-react`. You wrap the app in a provider, identify the visitor when they submit a form, and send the `eventId` to your backend for verification.

Before you start

You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app's URL (for example `http://localhost:5173`). The [quick start guide](quickstart.md) covers both.
## 1. Install the SDK ::: code-group ```sh [npm] npm install @trace-id/sdk-react ``` ```sh [pnpm] pnpm add @trace-id/sdk-react ``` ```sh [yarn] yarn add @trace-id/sdk-react ``` ```sh [bun] bun add @trace-id/sdk-react ``` ::: ## 2. Add the provider Wrap your app once, near the root. The provider creates a single client for every component below it. ```tsx // main.tsx import { createRoot } from 'react-dom/client'; import { IdentifyProvider } from '@trace-id/sdk-react'; import App from './App'; createRoot(document.getElementById('root')!).render( , ); ``` ```dotenv VITE_TRACE_PUBLIC_KEY=pk_... VITE_TRACE_ENDPOINT=https://id.example.com ``` ## 3. Identify on submit `useVisitorData` returns `{ data, error, isLoading, getData }`. With `immediate: false` nothing runs until you call `getData`, which is what you want for a form. ```tsx // SignupForm.tsx import { useVisitorData } from '@trace-id/sdk-react'; export function SignupForm() { const { getData, isLoading } = useVisitorData({ immediate: false }); async function onSubmit(e: React.FormEvent) { e.preventDefault(); const form = new FormData(e.currentTarget); const result = await getData({ tags: { action: 'signup' } }); // null if Trace is unavailable await fetch('/api/signup', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ...Object.fromEntries(form), eventId: result?.eventId }), }); } return (
); } ``` `getData` never throws. On failure it resolves `null` and sets `error`, an `IdentifyError` with a `code` such as `timeout` or `origin_not_allowed`.

Show the visitor id while you build

Leave `immediate` at its default (`true`) on a test page and render `data?.visitorId`. Open the page in a private window: the id stays the same.
## 4. Verify on your server Never act on what the browser sends. Your backend fetches the event with a secret key: ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent from @trace-id/sdk-node - [Python](python.md) brand:python: Client.get_event from trace-device - [PHP](php.md) brand:php: Client::getEvent from trace/trace - [Java](java.md) brand:openjdk: getEvent from dev.trace:trace ::: ## Next steps ::: cards - [Next.js](nextjs.md) brand:nextdotjs: The same flow with a route handler for verification - [Browser SDK reference](browser-sdk.md): Options, the result and every error code - [Consent](integration.md#consent): Start disabled with useIdentifyClient().enable() ::: --- # Next.js Source: /docs/nextjs # Next.js This quickstart adds Trace to a Next.js App Router project. A client component identifies the visitor, and a route handler verifies the event with your secret key before deciding.

Before you start

You need a running Trace server, a **public key** (`pk_...`) that allows your site's origin, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both. Prefer no separate server? Mount Trace inside this app with [embedded mode](embedded.md) and verify with `trace.verify()` instead.
## 1. Install the SDKs `@trace-id/sdk-next` bundles both halves: `/client` runs in the browser and `/server` verifies on the server. ::: code-group ```sh [npm] npm install @trace-id/sdk-next ``` ```sh [pnpm] pnpm add @trace-id/sdk-next ``` ```sh [yarn] yarn add @trace-id/sdk-next ``` ```sh [bun] bun add @trace-id/sdk-next ``` ::: ```dotenv # .env.local NEXT_PUBLIC_TRACE_PUBLIC_KEY=pk_... NEXT_PUBLIC_TRACE_ENDPOINT=https://id.example.com TRACE_SECRET_KEY=sk_... TRACE_ENDPOINT=https://id.example.com ``` Only the `NEXT_PUBLIC_` values reach the browser. Keep the secret key without that prefix. ## 2. Add the provider The provider is a client component, so give it its own file and use it in the root layout. ```tsx // app/providers.tsx 'use client'; import { IdentifyProvider } from '@trace-id/sdk-next/client'; export function Providers({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` ```tsx // app/layout.tsx import { Providers } from './providers'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` Nothing runs during server rendering; collection starts in the browser. ## 3. Identify on submit ```tsx // app/signup/signup-form.tsx 'use client'; import { useVisitorData } from '@trace-id/sdk-next/client'; export function SignupForm() { const { getData, isLoading } = useVisitorData({ immediate: false }); async function onSubmit(e: React.FormEvent) { e.preventDefault(); const form = new FormData(e.currentTarget); const result = await getData({ tags: { action: 'signup' } }); const res = await fetch('/api/signup', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: form.get('email'), eventId: result?.eventId }), }); // handle res: 200 created, 202 needs verification, 403 blocked } return (
); } ``` ## 4. Verify in a route handler `withTrace` reads the event id from the `x-trace-event-id` header or the JSON body, verifies it with `TRACE_SECRET_KEY` and `TRACE_ENDPOINT`, and runs your handler only if the event is valid. You decide with the verified event. ```ts // app/api/signup/route.ts import { withTrace } from '@trace-id/sdk-next/server'; export const POST = withTrace( async (req, { event }) => { const { email } = await req.json(); if (event && event.suspectScore >= 60) { return Response.json({ error: 'blocked' }, { status: 403 }); } if (event?.signals.multiAccount.detected) { // many accounts from this device: ask for email or phone verification first return Response.json({ next: 'verify-email' }, { status: 202 }); } // create the account, and store event?.visitorId with it for later lookups return Response.json({ ok: true }); }, { failOpen: true, timeoutMs: 1500 }, ); ``` Without `failOpen`, requests get a 503 when Trace cannot be reached; with it they continue and `event` is `null`. A wrong secret key never fails open. To decide inside the guard instead, pass `reject: (event) => event.suspectScore >= 60` and `withTrace` answers 403 for you. For server actions or custom flows, call `verifyEvent` from `@trace-id/sdk-next/server` directly.

Start in shadow mode

For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick your thresholds. The numbers above are a starting point, not defaults.
## Next steps ::: cards - [New account fraud](new-account-fraud.md): The full sign-up decision, step by step - [Server SDKs reference](server-sdks.md): verifyEvent options and error codes - [First-party mode](integration.md#first-party-mode): Serve Trace from your own domain ::: --- # Vue Source: /docs/vue # Vue This quickstart adds Trace to a Vue 3 app with `@trace-id/sdk-vue`. You install a plugin once, identify the visitor in a component, and send the `eventId` to your backend for verification. It works the same in Nuxt.

Before you start

You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app. The [quick start guide](quickstart.md) covers both.
## 1. Install the SDK ::: code-group ```sh [npm] npm install @trace-id/sdk-vue ``` ```sh [pnpm] pnpm add @trace-id/sdk-vue ``` ```sh [yarn] yarn add @trace-id/sdk-vue ``` ```sh [bun] bun add @trace-id/sdk-vue ``` ::: ## 2. Install the plugin ```ts // main.ts import { createApp } from 'vue'; import { createIdentify } from '@trace-id/sdk-vue'; import App from './App.vue'; createApp(App) .use(createIdentify({ apiKey: import.meta.env.VITE_TRACE_PUBLIC_KEY, endpoint: import.meta.env.VITE_TRACE_ENDPOINT })) .mount('#app'); ``` In Nuxt, do the same in a client-only plugin (`plugins/trace.client.ts`) with `nuxtApp.vueApp.use(createIdentify({ ... }))`. ## 3. Identify on submit `useVisitorData` returns refs: `data`, `error`, `isLoading`, and a `getData` function. ```vue ``` `getData` never throws. On failure it resolves `null` and sets `error` to an `IdentifyError` with a `code`. ## 4. Verify on your server ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent from @trace-id/sdk-node - [Python](python.md) brand:python: Client.get_event from trace-device - [PHP](php.md) brand:php: Client::getEvent from trace/trace - [Java](java.md) brand:openjdk: getEvent from dev.trace:trace ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a decision - [Browser SDK reference](browser-sdk.md): Options, the result and every error code - [Consent](integration.md#consent): useIdentifyClient().enable() after consent ::: --- # Svelte Source: /docs/svelte # Svelte This quickstart adds Trace to a Svelte or SvelteKit app with `@trace-id/sdk-svelte`. The SDK is a Svelte store: create it once, read it with `$`, and call `getData` when the user acts.

Before you start

You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app. The [quick start guide](quickstart.md) covers both.
## 1. Install the SDK ::: code-group ```sh [npm] npm install @trace-id/sdk-svelte ``` ```sh [pnpm] pnpm add @trace-id/sdk-svelte ``` ```sh [yarn] yarn add @trace-id/sdk-svelte ``` ```sh [bun] bun add @trace-id/sdk-svelte ``` ::: ## 2. Create the store Create it in a shared module so every component uses the same client. ```ts // src/lib/trace.ts import { createVisitorData } from '@trace-id/sdk-svelte'; import { PUBLIC_TRACE_ENDPOINT, PUBLIC_TRACE_KEY } from '$env/static/public'; export const visitor = createVisitorData({ apiKey: PUBLIC_TRACE_KEY, endpoint: PUBLIC_TRACE_ENDPOINT }, { immediate: false }); ``` Outside SvelteKit, pass the values directly instead of importing them from `$env`. ## 3. Identify on submit ```svelte
``` The store holds `{ data, error, isLoading }`. Collection only runs in the browser, never during server rendering. ## 4. Verify on your server In SvelteKit, verify in a `+server.ts` endpoint or a form action with [`@trace-id/sdk-node`](node.md). Other backends: ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent from @trace-id/sdk-node - [Python](python.md) brand:python: Client.get_event from trace-device - [PHP](php.md) brand:php: Client::getEvent from trace/trace - [Java](java.md) brand:openjdk: getEvent from dev.trace:trace ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a decision - [Browser SDK reference](browser-sdk.md): Options, the result and every error code ::: --- # SvelteKit Source: /docs/sveltekit # SvelteKit This quickstart adds Trace to a SvelteKit app. A store from `@trace-id/sdk-svelte` identifies the visitor in the browser, and a `+server.ts` endpoint verifies the event with your secret key.

Before you start

You need a running Trace server, a **public key** (`pk_...`) whose allowed origins include your site, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both.
## 1. Install the SDKs ::: code-group ```sh [npm] npm install @trace-id/sdk-svelte @trace-id/sdk-node ``` ```sh [pnpm] pnpm add @trace-id/sdk-svelte @trace-id/sdk-node ``` ```sh [yarn] yarn add @trace-id/sdk-svelte @trace-id/sdk-node ``` ```sh [bun] bun add @trace-id/sdk-svelte @trace-id/sdk-node ``` ::: ```dotenv # .env PUBLIC_TRACE_KEY=pk_... PUBLIC_TRACE_ENDPOINT=https://id.example.com TRACE_SECRET_KEY=sk_... ``` Only `PUBLIC_` values reach the browser. ## 2. Create the store ```ts // src/lib/trace.ts import { createVisitorData } from '@trace-id/sdk-svelte'; import { PUBLIC_TRACE_ENDPOINT, PUBLIC_TRACE_KEY } from '$env/static/public'; export const visitor = createVisitorData({ apiKey: PUBLIC_TRACE_KEY, endpoint: PUBLIC_TRACE_ENDPOINT }, { immediate: false }); ``` Collection only runs in the browser, never during server rendering. ## 3. Identify on submit ```svelte
``` ## 4. Verify in an endpoint ```ts // src/routes/api/signup/+server.ts import { PUBLIC_TRACE_ENDPOINT } from '$env/static/public'; import { TRACE_SECRET_KEY } from '$env/static/private'; import { guardRequest } from '@trace-id/sdk-node/web'; import { json } from '@sveltejs/kit'; export async function POST({ request }) { const guard = await guardRequest(request, { secretKey: TRACE_SECRET_KEY, endpoint: PUBLIC_TRACE_ENDPOINT, failOpen: true, reject: (event) => event.suspectScore >= 60, }); if (guard.response) return guard.response; // 400, 403, 503 or 500, with a JSON error body const { email } = await request.json(); // create the account, and store guard.event?.visitorId with it for later lookups return json({ ok: true }); } ``` For a form action instead, read the id from the form data and call `verifyEvent` from `@trace-id/sdk-node` directly, then return `fail(400)` or `fail(403)` as needed.

Start in shadow mode

For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick thresholds you trust.
## 5. Other backends ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent and Express/Fastify guards - [Python](python.md) brand:python: Client.get_event and framework guards - [PHP](php.md) brand:php: Client::getEvent and a Laravel middleware - [Go](go.md) brand:go: GetEvent and a net/http guard ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a decision - [Browser SDK reference](browser-sdk.md): Options, the result and every error code ::: --- # Nuxt Source: /docs/nuxt # Nuxt This quickstart adds Trace to a Nuxt 3 app with the `@trace-id/sdk-nuxt` module. It sets up the client, a composable identifies the visitor, and a Nitro server route verifies the event with your secret key.

Before you start

You need a running Trace server, a **public key** (`pk_...`) whose allowed origins include your site, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both.
## 1. Install the module ::: code-group ```sh [npm] npm install @trace-id/sdk-nuxt @trace-id/sdk-node ``` ```sh [pnpm] pnpm add @trace-id/sdk-nuxt @trace-id/sdk-node ``` ```sh [yarn] yarn add @trace-id/sdk-nuxt @trace-id/sdk-node ``` ```sh [bun] bun add @trace-id/sdk-nuxt @trace-id/sdk-node ``` ::: ## 2. Register it ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: ['@trace-id/sdk-nuxt'], trace: { apiKey: 'pk_...', endpoint: 'https://id.example.com' }, runtimeConfig: { traceSecretKey: '', // NUXT_TRACE_SECRET_KEY, server only }, }); ``` You can leave `apiKey` and `endpoint` out and set `NUXT_PUBLIC_TRACE_KEY` and `NUXT_PUBLIC_TRACE_ENDPOINT` instead. The module adds a client-only plugin, so collection only runs in the browser, and auto-imports `useVisitorData()` and `useIdentifyClient()`. Never put a secret key under `trace`; it is public config.

Already using @trace-id/sdk-vue directly?

That still works: install the plugin yourself in a `plugins/trace.client.ts` with `createIdentify(...)`. The module is the shorter path.
## 3. Identify on submit ```vue ``` ## 4. Verify in a server route ```ts // server/api/signup.post.ts import { verifyEvent } from '@trace-id/sdk-node'; export default defineEventHandler(async (event) => { const config = useRuntimeConfig(event); const eventId = getHeader(event, 'x-trace-event-id'); let verified = null; if (eventId) { try { verified = await verifyEvent(eventId, { secretKey: config.traceSecretKey, endpoint: config.public.traceEndpoint, timeoutMs: 1500, }); } catch (err) { console.warn('Trace check skipped', (err as { code?: string }).code); // fail open } } if (verified && verified.suspectScore >= 60) { throw createError({ statusCode: 403, statusMessage: 'blocked' }); } const { email } = await readBody(event); // create the account, and store verified?.visitorId with it for later lookups return { ok: true }; }); ```

Start in shadow mode

For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick thresholds you trust.
## 5. Other backends ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent and Express/Fastify guards - [Python](python.md) brand:python: Client.get_event and framework guards - [PHP](php.md) brand:php: Client::getEvent and a Laravel middleware - [Go](go.md) brand:go: GetEvent and a net/http guard ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a decision - [Browser SDK reference](browser-sdk.md): Options, the result and every error code ::: --- # Remix and React Router Source: /docs/remix # Remix and React Router This quickstart adds Trace to a Remix or React Router (framework mode) app. A provider and hook identify the visitor in the browser, and the route `action` verifies the event with your secret key.

Before you start

You need a running Trace server, a **public key** (`pk_...`) whose allowed origins include your site, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both.
## 1. Install the SDKs ::: code-group ```sh [npm] npm install @trace-id/sdk-react @trace-id/sdk-node ``` ```sh [pnpm] pnpm add @trace-id/sdk-react @trace-id/sdk-node ``` ```sh [yarn] yarn add @trace-id/sdk-react @trace-id/sdk-node ``` ```sh [bun] bun add @trace-id/sdk-react @trace-id/sdk-node ``` ::: ```dotenv # .env TRACE_PUBLIC_KEY=pk_... TRACE_ENDPOINT=https://id.example.com TRACE_SECRET_KEY=sk_... ``` ## 2. Add the provider Pass the public values from a loader so the browser gets them. Nothing runs during server rendering; collection starts in the browser. ```tsx // app/root.tsx import { IdentifyProvider } from '@trace-id/sdk-react'; import { Outlet, useLoaderData } from 'react-router'; // or '@remix-run/react' export function loader() { return { traceKey: process.env.TRACE_PUBLIC_KEY!, traceEndpoint: process.env.TRACE_ENDPOINT! }; } export default function App() { const { traceKey, traceEndpoint } = useLoaderData(); return ( ); } ``` ## 3. Identify on submit Identify first, then put the `eventId` into the form data you post. ```tsx // app/routes/signup.tsx import { useVisitorData } from '@trace-id/sdk-react'; import { useFetcher } from 'react-router'; export default function Signup() { const fetcher = useFetcher(); const { getData, isLoading } = useVisitorData({ immediate: false }); async function onSubmit(e: React.FormEvent) { e.preventDefault(); const form = new FormData(e.currentTarget); const result = await getData({ tags: { action: 'signup' } }); // null if Trace is unavailable form.set('eventId', result?.eventId ?? ''); fetcher.submit(form, { method: 'post' }); } return ( ); } ``` ## 4. Verify in the action `guardRequest` reads the event id from the form body (or a header or JSON body), verifies it, and leaves the request body readable for `formData()`. ```ts // app/routes/signup.tsx import { guardRequest } from '@trace-id/sdk-node/web'; export async function action({ request }: { request: Request }) { const guard = await guardRequest(request, { secretKey: process.env.TRACE_SECRET_KEY!, endpoint: process.env.TRACE_ENDPOINT!, failOpen: true, reject: (event) => event.suspectScore >= 60, }); if (guard.response) return guard.response; // 400, 403, 503 or 500, with a JSON error body const form = await request.formData(); // create the account for form.get('email'), and store guard.event?.visitorId with it return { ok: true }; } ```

Start in shadow mode

For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick thresholds you trust.
## 5. Other backends ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent and Express/Fastify guards - [Python](python.md) brand:python: Client.get_event and framework guards - [PHP](php.md) brand:php: Client::getEvent and a Laravel middleware - [Go](go.md) brand:go: GetEvent and a net/http guard ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a decision - [Browser SDK reference](browser-sdk.md): Options, the result and every error code ::: --- # Astro Source: /docs/astro # Astro This quickstart adds Trace to an Astro site. A script in the page identifies the visitor, and an API endpoint verifies the event with your secret key before deciding.

Before you start

You need a running Trace server, a **public key** (`pk_...`) whose allowed origins include your site, and a **secret key** (`sk_...`) for the server. The [quick start guide](quickstart.md) creates both.
## 1. Install the SDKs `@trace-id/sdk-js` runs in the browser; `@trace-id/sdk-node` verifies on the server. ::: code-group ```sh [npm] npm install @trace-id/sdk-js @trace-id/sdk-node ``` ```sh [pnpm] pnpm add @trace-id/sdk-js @trace-id/sdk-node ``` ```sh [yarn] yarn add @trace-id/sdk-js @trace-id/sdk-node ``` ```sh [bun] bun add @trace-id/sdk-js @trace-id/sdk-node ``` ::: ```dotenv # .env PUBLIC_TRACE_KEY=pk_... PUBLIC_TRACE_ENDPOINT=https://id.example.com TRACE_SECRET_KEY=sk_... ``` Only `PUBLIC_` values reach the browser. Keep the secret key without that prefix. API endpoints need an on-demand rendering adapter (for example `@astrojs/node`). ## 2. Identify on submit ```astro --- // src/pages/signup.astro ---
``` ## 3. Verify in an endpoint `guardRequest` reads the event id from the `x-trace-event-id` header, a JSON body or a form body, verifies it, and hands you the verified event or a ready response. The request body stays readable afterwards. ```ts // src/pages/api/signup.ts import type { APIRoute } from 'astro'; import { guardRequest } from '@trace-id/sdk-node/web'; export const prerender = false; export const POST: APIRoute = async ({ request }) => { const guard = await guardRequest(request, { secretKey: import.meta.env.TRACE_SECRET_KEY, endpoint: import.meta.env.PUBLIC_TRACE_ENDPOINT, failOpen: true, reject: (event) => event.suspectScore >= 60, }); if (guard.response) return guard.response; // 400, 403, 503 or 500, with a JSON error body const { email } = await request.json(); // create the account, and store guard.event?.visitorId with it for later lookups return Response.json({ ok: true }); }; ```

Start in shadow mode

For the first week, log `event.suspectScore` and `event.reasons` instead of blocking. Look at who would have been blocked, then pick thresholds you trust.
## 4. Other backends ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent and Express/Fastify guards - [Python](python.md) brand:python: Client.get_event and framework guards - [PHP](php.md) brand:php: Client::getEvent and a Laravel middleware - [Go](go.md) brand:go: GetEvent and a net/http guard ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a decision - [Browser SDK reference](browser-sdk.md): Options, the result and every error code ::: --- # Solid Source: /docs/solid # Solid This quickstart adds Trace to a SolidJS or SolidStart app with `@trace-id/sdk-solid`. You wrap the app in a provider once, read signals in a component, and send the `eventId` to your backend for verification.

Before you start

You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app. The [quick start guide](quickstart.md) covers both.
## 1. Install the SDK ::: code-group ```sh [npm] npm install @trace-id/sdk-solid ``` ```sh [pnpm] pnpm add @trace-id/sdk-solid ``` ```sh [yarn] yarn add @trace-id/sdk-solid ``` ```sh [bun] bun add @trace-id/sdk-solid ``` ::: ## 2. Add the provider ```tsx // src/index.tsx import { render } from 'solid-js/web'; import { IdentifyProvider } from '@trace-id/sdk-solid'; import App from './App'; render( () => ( ), document.getElementById('root')!, ); ``` In SolidStart, put the provider in `app.tsx`. Nothing runs during server rendering; collection starts in the browser. ## 3. Identify on submit `createVisitorData` returns `data`, `error` and `isLoading` as signals, and `getData()` to identify on demand. Call it in a component body. ```tsx // SignupForm.tsx import { createSignal } from 'solid-js'; import { createVisitorData } from '@trace-id/sdk-solid'; export function SignupForm() { const [email, setEmail] = createSignal(''); const visitor = createVisitorData({ immediate: false }); async function submit(e: SubmitEvent) { e.preventDefault(); const result = await visitor.getData({ tags: { action: 'signup' } }); // null if Trace is unavailable await fetch('/api/signup', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: email(), eventId: result?.eventId }), }); } return (
setEmail(e.currentTarget.value)} />
); } ``` `getData` never throws. On failure it resolves `null` and `error()` holds an `IdentifyError` with a `code`. Use `useIdentifyClient()` for consent toggles (`enable()`, `disable(true)`). ## 4. Verify on your server ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent and Express/Fastify guards - [Python](python.md) brand:python: Client.get_event from trace-device - [PHP](php.md) brand:php: Client::getEvent from trace/trace - [Go](go.md) brand:go: GetEvent and a net/http guard ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a decision - [Browser SDK reference](browser-sdk.md): Options, the result and every error code ::: --- # Angular Source: /docs/angular # Angular This quickstart adds Trace to an Angular 17+ app with `@trace-id/sdk-angular`. You register it once, read signals in a component, and send the `eventId` to your backend for verification. There is no zone.js dependency and no decorators.

Before you start

You need a running Trace server and a **public key** (`pk_...`) whose allowed origins include your app (for example `http://localhost:4200`). The [quick start guide](quickstart.md) covers both.
## 1. Install the SDK ::: code-group ```sh [npm] npm install @trace-id/sdk-angular ``` ```sh [pnpm] pnpm add @trace-id/sdk-angular ``` ```sh [yarn] yarn add @trace-id/sdk-angular ``` ::: ## 2. Register it ```ts // app.config.ts import { ApplicationConfig } from '@angular/core'; import { provideTrace } from '@trace-id/sdk-angular'; import { environment } from '../environments/environment'; export const appConfig: ApplicationConfig = { providers: [provideTrace({ apiKey: environment.tracePublicKey, endpoint: environment.traceEndpoint })], }; ``` ## 3. Identify on submit `injectVisitorData` returns `data`, `error` and `isLoading` as signals, and `getData()` to identify on demand. Call it in a field initialiser or constructor. ```ts // signup.component.ts import { HttpClient } from '@angular/common/http'; import { Component, inject } from '@angular/core'; import { FormsModule } from '@angular/forms'; import { firstValueFrom } from 'rxjs'; import { injectVisitorData } from '@trace-id/sdk-angular'; @Component({ selector: 'app-signup', standalone: true, imports: [FormsModule], template: `
`, }) export class SignupComponent { readonly visitor = injectVisitorData({ immediate: false }); private readonly http = inject(HttpClient); email = ''; async submit() { const result = await this.visitor.getData({ tags: { action: 'signup' } }); // null if Trace is unavailable await firstValueFrom(this.http.post('/api/signup', { email: this.email, eventId: result?.eventId })); } } ``` With server-side rendering, collection only starts in the browser, after the first render. Use `injectTraceClient()` for consent toggles (`enable()`, `disable(true)`). ## 4. Verify on your server ::: cards - [Node.js](node.md) brand:nodedotjs: verifyEvent and Express/Fastify guards - [Python](python.md) brand:python: Client.get_event from trace-device - [PHP](php.md) brand:php: Client::getEvent from trace/trace - [Java](java.md) brand:openjdk: getEvent from dev.trace:trace ::: ## Next steps ::: cards - [New account fraud](new-account-fraud.md): Turn the verified event into a decision - [Browser SDK reference](browser-sdk.md): Options, the result and every error code ::: --- # React Native & Expo Source: /docs/react-native # React Native & Expo This quickstart adds Trace to a React Native app with `@trace-id/sdk-react-native`. You allow your app on a public key, wrap the app in a provider, identify the device before a sensitive action, and send the `eventId` to your backend for verification.

Before you start

You need a running Trace server and a **public key** (`pk_...`). The [quick start guide](quickstart.md) covers both. The SDK works in Expo Go, in development builds and in bare React Native apps with Expo modules installed. It has no config plugin and no native code of its own.
## 1. Install the SDK `npx expo install` picks the versions of the Expo modules that match your SDK: ::: code-group ```sh [Expo] npx expo install @trace-id/sdk-react-native expo-application expo-crypto expo-device expo-localization expo-secure-store ``` ```sh [Bare React Native] npx install-expo-modules@latest npx expo install @trace-id/sdk-react-native expo-application expo-crypto expo-device expo-localization expo-secure-store ``` ::: ## 2. Allow your app on the key A native app sends no `Origin` header, so list the app itself among the key's allowed origins, next to your web origins: `app:` followed by the iOS bundle identifier or the Android application id. ``` https://shop.example.com app:com.example.shop ``` The SDK names its app in an `X-Trace-App` header. Like the web origin check, this decides which apps may use the key; it does not prove the request came from your app. That proof comes from verifying on your server (step 5). ## 3. Add the provider ```tsx // App.tsx import { IdentifyProvider } from '@trace-id/sdk-react-native'; export default function App() { return ( ); } ``` ```dotenv EXPO_PUBLIC_TRACE_PUBLIC_KEY=pk_... EXPO_PUBLIC_TRACE_ENDPOINT=https://id.example.com ``` ## 4. Identify before the action `useVisitorData` is the same hook as in the React SDK: `{ data, error, isLoading, getData }`. With `immediate: false` nothing runs until you call `getData`. ```tsx // CheckoutScreen.tsx import { useVisitorData } from '@trace-id/sdk-react-native'; export function CheckoutScreen({ order, user }: Props) { const { getData, isLoading } = useVisitorData({ immediate: false }); async function pay() { const result = await getData({ linkedId: user.id, tags: { screen: 'checkout' } }); // null if Trace is unavailable await api.post('/orders/pay', { orderId: order.id, eventId: result?.eventId }); } return