Nuxt quickstart

• A publishable key (pk_live_…) is read by the browser. It is meant to be public.
• A secret key (sk_live_…) is what scores events. It must never reach the browser.

Both are in your dashboard. The secret key is shown once.

Nuxt is private by default, and that is the opposite of Next. In Next any variable named NEXT_PUBLIC_* is inlined into the browser bundle, so the dangerous thing is one prefix away. In Nuxt, everything in runtimeConfig stays on the server unless you nest it under public, so exposure is something you opt into on purpose. If you came from the Next guide, unlearn the prefix habit.

npm create nuxt@latest kaidn-demo
cd kaidn-demo
npm install @kaidn/nuxt

One package covers both halves. @kaidn/nuxt gives you the composable for the browser, and @kaidn/nuxt/server gives you the scorer. Nothing imports both.

Declare both in runtimeConfig. The empty strings are deliberate: they are placeholders that the environment fills at runtime, and they document which keys exist.

export default defineNuxtConfig({
  runtimeConfig: {
    // Server only. Never move this line inside `public`.
    kaidnApiKey: "",

    public: {
      // Sent to the browser on purpose.
      kaidnPk: "",
    },
  },
});

NUXT_KAIDN_API_KEY=sk_live_your_secret_key
NUXT_PUBLIC_KAIDN_PK=pk_live_your_publishable_key

The env names are not free-form. Nuxt maps NUXT_KAIDN_API_KEY to runtimeConfig.kaidnApiKey and NUXT_PUBLIC_KAIDN_PK to runtimeConfig.public.kaidnPk, by uppercasing and splitting on the nesting. Reading process.env.SOMETHING_ELSE as a default in the config works at build time and then breaks at runtime, which is a bad way to find out.

Wrap the package’s hook in your own composable so the key is read in one place. It collects when you ask it to rather than on mount, which puts the work at the moment somebody acts and keeps fingerprinting off pages that do not need it.

import { useDeviceId } from "@kaidn/nuxt";

export function useKaidn() {
  return useDeviceId(useRuntimeConfig().public.kaidnPk);
}

The key is passed in, not discovered. The package never imports useRuntimeConfigitself. Reaching into Nuxt’s virtual imports would save you this one line and tie the package to an internal that moves between versions, so it takes an argument instead and works the same on Nuxt 3, Nuxt 4 and plain Vue.

<script setup lang="ts">
const { getDeviceId } = useKaidn();
const email = ref("");
const message = ref("");

async function onSubmit() {
  const deviceId = await getDeviceId();
  const res = await $fetch("/api/signup", {
    method: "POST",
    body: { email: email.value, deviceId },
  });
  message.value = res.message;
}
</script>

<template>
  <form @submit.prevent="onSubmit">
    <input v-model="email" type="email" required />
    <button type="submit">Create account</button>
    <p>{{ message }}</p>
  </form>
</template>

This is the half that actually stops anything. Note the import path: @kaidn/nuxt/server, not @kaidn/nuxt.

import { createKaidn } from "@kaidn/nuxt/server";

export default defineEventHandler(async (event) => {
  const { kaidnApiKey } = useRuntimeConfig(event);
  const kaidn = createKaidn({ apiKey: kaidnApiKey });

  const { email, deviceId } = await readBody(event);

  const result = await kaidn.score(event, {
    event: "signup",
    email,
    device_id: deviceId ?? undefined,
  });

  if (result.verdict === "block") {
    throw createError({ statusCode: 403, statusMessage: "Signup refused" });
  }
  if (result.verdict === "review") {
    // Let them in, flag it for a human. Most fraud lives here, not in "block".
    await flagForReview(email, result.reasons);
  }

  await createUser(email);
  return { ok: true, message: "Account created." };
});

A server route is a public endpoint. Anyone can POST /api/signup directly, without ever loading your form. So the verdict has to be enforced here, inside the handler, as above. Hiding the form or branching in the component is not a check.

useRuntimeConfig(event) takes the event on the server. Passing it is what lets Nuxt resolve per-request config correctly, so do not reach for process.env here.

npm run dev

Submit the form, then open your events. A scored signup appears with its verdict and the reasons behind it. Submit twice from the same browser and the second one carries device_reuse.

{
  "score": 15,
  "verdict": "allow",
  "reasons": ["device_reuse"],
  "reason_text": "This device is linked to 2 accounts."
}

reasons holds machine-readable codes to branch on; reason_text is the sentence written for a human. Log the second one, switch on the first.