Integrate DeviceDNA with your website

01 / DEPLOYMENT OVERVIEW

Understand the security model

There is no public browser API key. Your backend uses a long-lived private credential only to request a short-lived session token. The browser receives only that temporary token and its binding.

02 / CONSOLE SETUP

Create the workspace

1. Register or sign in at the DeviceDNA console.
2. Create or select the workspace that represents the website or product you want to protect.
3. Use a clear workspace name so operators can identify it later.
4. Confirm the displayed tenant key. It is a public workspace identifier, not a secret; use it only in integrations for that workspace.
5. Use the console's language switcher to read this guide in English or Simplified Chinese.

Important: the workspace is tenant-scoped. Device IDs, signatures, clusters, observations, quota, and credentials must never be treated as global identifiers across customers.

03 / TRUSTED ORIGINS

Configure the browser page's exact origin

Open Trusted origins in the workspace sidebar and add the exact origin of every page where the SDK will run. An origin consists of the scheme, hostname, and port; it never includes a path.

Do not append a path, use a wildcard, or assume that one port covers another. Add each port as a separate origin. Remove origins your team no longer controls.

04 / PRIVATE KEY

Create and protect the server credential

1. Open API keys in the workspace sidebar.
2. Click Create private key. Keep only one active private key for the workspace.
3. Copy the full value immediately. DeviceDNA shows the secret only once.
4. Store it in an environment variable or secret manager on your backend.
5. Do not commit it, write it to request logs, place it in browser bundles, or paste it into support tickets.
6. If exposure is suspected, revoke it, create a replacement, update the backend secret, and redeploy.

DEVICEDNA_PRIVATE_KEY=ddna_private_live_replace_me

06 / SERVER: ISSUE A SESSION

Call the DeviceDNA API from your backend

Generate a fresh random binding for your application's authenticated user session. Send the private key in the Authorization header. This request must be made by your backend, never directly from browser JavaScript.

import crypto from "node:crypto";

const binding = crypto.randomBytes(32).toString("base64url");
const session = await fetch("https://www.devicedna.site/v1/session", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "authorization": `Bearer ${process.env.DEVICEDNA_PRIVATE_KEY}`
  },
  body: JSON.stringify({
    tenantKey: process.env.DEVICEDNA_TENANT_KEY,
    origin: "https://shop.example.com",
    binding
  })
}).then(async (response) => {
  const body = await response.json();
  if (!response.ok) throw new Error(body.message || body.error || "Session issuance failed");
  return body;
});

// Return only session.token and session.binding to the authenticated page.

The origin must exactly match the origin of the page that will run the SDK. Associate the binding with the same authenticated user session in your application.

Session response

{
  "token": "ddna_sess_...",
  "binding": "the-same-random-binding",
  "expiresAt": "2026-08-22T12:00:00.000Z",
  "tenantKey": "tenant_...",
  "origin": "https://shop.example.com"
}

07 / BROWSER: RUN ONE CHECK

Pass only the temporary token and binding

Host the built SDK on your own website and load it in the visitor's browser. The browser does not need the workspace's private key. Pass only the session token and binding returned by your backend.

import { identifyDevice } from "/device.js";

const identity = await identifyDevice(
  "https://www.devicedna.site",
  "tenant_your_workspace_key",
  sessionToken,
  sessionBinding
);

await fetch("/your-server/device-check", {
  method: "POST",
  headers: { "content-type": "application/json" },
  credentials: "include",
  body: JSON.stringify({ assertion: identity.assertion })
});

Run it only after satisfying your website's consent requirements and, where applicable, visitor-authentication requirements. Do not put a long-lived DeviceDNA credential in localStorage, cookies accessible to JavaScript, or a public configuration file.

09 / FINALIZE ON YOUR SERVER

Verify the assertion and apply policy

Send the assertion to your backend through the same authenticated application session. Associate it with the session that requested the DeviceDNA token, then call the server-side session-status flow or an equivalent verification endpoint.

// Pseudocode: do not trust identity fields copied from the browser.
const decision = await verifyWithDeviceDNA({
  tenantKey: process.env.DEVICEDNA_TENANT_KEY,
  privateKey: process.env.DEVICEDNA_PRIVATE_KEY,
  assertion: request.body.assertion,
  expectedCustomerSession: request.session.id
});

if (decision.recommendation === "challenge") {
  // Require a passkey, password, email code, or other step-up check.
}
// Keep irreversible bans behind corroborating evidence and review.

Recommended policy: use DeviceDNA as supporting evidence. Before an irreversible action, combine it with account history, payment signals, verified account ownership, anti-cheat telemetry, and behavioral evidence.

Identity fields to retain

Use deviceId or deviceClusterId as the device-cluster reference within the current workspace. browserProfileId identifies one browser profile. Use confidence, status, integrity, and reasonCodes to understand why the decision was returned. None of these fields is a hardware serial number.

10 / TEST THE INSTALLATION

Use the authenticated test lab

1. Sign in to the DeviceDNA console.
2. Open Test lab. The current browser integration does not use a public key, so the lab does not ask for one.
3. The dashboard creates a short-lived test session on the server and runs the same SDK and matcher used in production.
4. Run the test in Chrome or Edge, then repeat it in another ordinary browser on the same computer.
5. Compare the device cluster, status, confidence, and integrity together. A new browser profile is expected to have a different browserProfileId.

An exact result usually means the persisted browser identifier matched. probable means cross-browser evidence supports the relationship. uncertain means the service will not force a cluster merge.