Nuxt
BotBye! integration for Nuxt applications.
Install
1
npm i @botbye/nuxt
1
yarn add @botbye/nuxt
Requires nuxt >= 3 as a peer dependency.
Package exports
The package exposes three entry points:
- @botbye/nuxt/server — server-side SDK: init, evaluate, dev, factory
- @botbye/nuxt/client — client-side utilities: initChallenges, runChallenge, setUserId
- @botbye/nuxt/module — Nuxt module for automatic client-side initialization
Client-side Configuration
The @botbye/nuxt/client entry point provides utilities for initializing the BotBye client-side SDK and running challenge flows in the browser.
Using the Nuxt module (recommended)
Add the module to nuxt.config.ts to enable automatic client initialization and TypeScript support for useRuntimeConfig().public.botbye:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// nuxt.config.ts
export default defineNuxtConfig({
modules: ["@botbye/nuxt/module"],
botbyeModule: {
inject: true,
},
runtimeConfig: {
public: {
botbye: {
// Use your client key
clientKey: "00000000-0000-0000-0000-000000000000",
},
},
},
});
When inject: true, the module registers a client plugin that calls initChallenges automatically using runtimeConfig.public.botbye.
Manual initialization
If you prefer not to use inject: true, call initChallenges directly in a client-side Nuxt plugin:
1
2
3
4
5
6
7
8
9
// plugins/botbye.client.ts
import { initChallenges } from "@botbye/nuxt/client";
export default defineNuxtPlugin(() => {
initChallenges({
// Use your client key
clientKey: "00000000-0000-0000-0000-000000000000",
});
});
Client-side Usage
Once the SDK is initialized, call runChallenge() anywhere in client-side code to acquire a token and pass it to your API:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { runChallenge } from "@botbye/nuxt/client";
const onLoginClick = async () => {
const token = await runChallenge();
await $fetch("/api/login", {
method: "POST",
headers: {
// "x-botbye-token" is an example — pass the token from wherever you store it
"x-botbye-token": token,
},
body: { email, password },
});
};
User identification
Call setUserId after a successful authentication to associate the current session with a user. This helps BotBye detect multi-account abuse.
1
2
3
4
5
6
7
import { setUserId } from "@botbye/nuxt/client";
const response = await login({ username, password });
if (response.userId) {
setUserId(response.userId);
}
Server-side Configuration
Call init once at server startup with your server key. The recommended place in Nuxt is a Nitro server plugin:
1
2
3
4
5
6
7
8
9
// server/plugins/botbye.ts
import { init } from "@botbye/nuxt/server";
export default defineNitroPlugin(() => {
init({
// Use your project server-key
serverKey: "00000000-0000-0000-0000-000000000000",
});
});
init options
| Option | Type | Required | Description |
|---|---|---|---|
| serverKey | string | Yes | Server key from your BotBye project |
| url | string | No | Override BotBye API endpoint (default: https://verify.botbye.com) |
| logger.level | "error" "warn" "info" "debug" "log" | No | Log level (default: "info") |
| logger.logger | TLogger | No | Custom logger instance implementing { error, warn, info, debug, log } |
| timeouts.evaluate | number | No | Timeout in milliseconds for each evaluate call |
Server-side Usage
Call evaluate in API handlers or server middleware where bot protection is needed. It accepts an event object describing what you know about the request and the context around it, and returns a promise that resolves to a decision.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { evaluate } from "@botbye/nuxt/server";
export default defineEventHandler(async (event) => {
const result = await evaluate({
type: "validate",
request: {
request: event,
// "x-botbye-token" is an example — pass the token from wherever you store it
token: getRequestHeader(event, "x-botbye-token"),
},
});
if (result.decision === "BLOCK") {
throw createError({ statusCode: 403, message: "Forbidden" });
}
// proceed normally
});
There are three event types — validate, risk, and full — each suited for a different layer of your application.
validate — edge-level bot check
Use at the outermost layer — server middleware or API handler — when you just want to know: was this request made by a bot? No user or domain context needed.
Event fields:
1
2
3
4
5
6
7
8
9
10
11
12
{
type: "validate";
request:
// Option A: pass the H3Event object directly — SDK extracts everything automatically
| { request: H3Event; token?: string | null }
// Option B: construct request info manually
| { ip: string; headers: Record<string, string>; requestMethod?: string | null; requestUri?: string | null; token?: string | null };
customFields?: Record<string, string>;
}
The SDK extracts IP, headers, method, and URI from the H3Event object automatically. You can also pass request info manually — see Option B above. The token is a one-time token generated by the BotBye client-side SDK that contains information about the user's device. Pass whatever the client sent; if no token is received, the decision will be "BLOCK".
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { evaluate } from "@botbye/nuxt/server";
export default defineEventHandler(async (event) => {
const result = await evaluate({
type: "validate",
request: {
request: event,
// "x-botbye-token" is an example — pass the token from wherever you store it
token: getRequestHeader(event, "x-botbye-token"),
},
});
if (result.decision === "BLOCK") {
throw createError({ statusCode: 403, message: "Forbidden" });
}
// proceed normally
});
risk — domain-level risk scoring
Use inside API handlers that already know the user: auth, payments, account management, etc. The purpose shifts from "is this a bot?" to "is something suspicious happening for this user?" — credential stuffing, account takeover, account sharing, logins from a new geo.
Event fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
type: "risk";
request:
// Only ip is needed at this level
| { ip: string; headers?: Record<string, string>; requestMethod?: string | null; requestUri?: string | null; token?: string | null }
// H3Event also accepted if convenient
| { request: H3Event };
event: {
type: string; // e.g. "login", "password_change", "checkout"
status: "ATTEMPTED" | "SUCCESSFUL" | "FAILED" | "UNKNOWN";
};
user: {
accountId: string;
username?: string | null;
email?: string | null;
phone?: string | null;
};
customFields?: Record<string, string>;
botbyeResult?: string; // if a validate call was made earlier, pass its result.botbyeResult here to link the requests; omit if there was no prior validate
}
event and user are the key fields here — they define what action is being performed and who is performing it, which is what drives the risk score. ip is equally important: BotBye tracks which IPs access the account to detect patterns like account sharing, credential stuffing, and suspicious geo logins. Pass it directly as { ip }, or pass the H3Event object if that's more convenient.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { evaluate } from "@botbye/nuxt/server";
// Inside an API handler, after a login attempt
async function onLoginAttempt({ ip, userId, email, loginSucceeded }) {
const result = await evaluate({
type: "risk",
request: {
ip,
},
event: {
type: "login",
status: loginSucceeded ? "SUCCESSFUL" : "FAILED",
},
user: {
accountId: userId,
email,
},
});
if (result.decision === "BLOCK") {
// Lock account, trigger MFA, send alert, etc.
}
}
Linking validate and risk events
When the same request is evaluated at two layers — for example, once at the edge in server middleware (type: "validate") and then again inside an API handler (type: "risk") — BotBye can link both events and display them as a single event in the dashboard.
Step 1 — server middleware (edge layer): run validate and capture botbye_result:
1
2
3
4
5
6
7
8
9
10
11
12
13
// server/middleware/botbye.js
export default defineEventHandler(async (event) => {
const edgeResult = await evaluate({
type: "validate",
request: {
request: event,
// "x-botbye-token" is an example — pass the token from wherever you store it
token: getRequestHeader(event, "x-botbye-token"),
},
});
const edgeBotbyeResult = edgeResult.botbye_result;
// Pass edgeBotbyeResult downstream — event context, shared state, a forwarded header, etc.
});
Step 2 — API handler (domain layer): pass it as botbyeResult in the risk call:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// server/api/auth/login.post.js
const riskResult = await evaluate({
type: "risk",
request: { ip },
event: {
type: "login",
status: loginSucceeded ? "SUCCESSFUL" : "FAILED",
},
user: {
accountId: userId,
email,
},
botbyeResult: edgeBotbyeResult,
});
botbye_result is optional in the response — if it is absent, omit botbyeResult and the events will be recorded independently.
full — edge check and domain scoring in one call
Use when you have all context at once: raw request, token, user, and event. A login API handler is a typical example — it receives the request and immediately knows the user and outcome.
Event fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
type: "full";
request:
| { request: H3Event; token?: string | null }
| { ip: string; headers: Record<string, string>; requestMethod?: string | null; requestUri?: string | null; token?: string | null };
event: {
type: string;
status: "ATTEMPTED" | "SUCCESSFUL" | "FAILED" | "UNKNOWN";
};
user: {
accountId: string;
username?: string | null;
email?: string | null;
phone?: string | null;
};
customFields?: Record<string, string>;
}
Equivalent to running validate and risk in a single call.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import { evaluate } from "@botbye/nuxt/server";
// server/api/auth/login.post.js
export default defineEventHandler(async (event) => {
const { email, password } = await readBody(event);
const user = await findUser(email);
const loginSucceeded = user && (await checkPassword(user, password));
const result = await evaluate({
type: "full",
request: {
request: event,
// "x-botbye-token" is an example — pass the token from wherever you store it
token: getRequestHeader(event, "x-botbye-token"),
},
event: {
type: "login",
status: loginSucceeded ? "SUCCESSFUL" : "FAILED",
},
user: {
accountId: user?.id ?? "unknown",
email,
},
});
if (result.decision === "BLOCK") {
throw createError({ statusCode: 403, message: "Forbidden" });
}
// proceed normally
});
Response
evaluate always returns a Promise<TEvaluationResult>:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
type TEvaluationResult =
| {
decision: "ALLOW" | "BLOCK" | "CHALLENGE";
request_id: string;
risk_score: number;
scores: Record<string, number>;
signals: string[];
// Present when `decision` is "CHALLENGE": the kind of additional verification to put in
// front of the visitor.
challenge?: { type: "CAPTCHA" | "MFA" };
botbye_result?: string;
// Present when BotBye received the request but could not fully evaluate it. An integration
// error (malformed payload, a key resolving to no project) is "BLOCK" with "evaluation_error"
// in signals; a failure on the BotBye side is "ALLOW".
error?: { message: string };
}
| {
decision: "ALLOW";
botbye_result?: string;
// SDK fail-open: no decision was ever received — request timeout, connection error, or an
// unparseable response. There is no request_id in this case.
error: { message: string };
};
Check result.decision to decide how to handle the request:
- "ALLOW" — request appears legitimate, proceed normally
- "BLOCK" — bot or suspicious activity detected, block the request
- "CHALLENGE" — uncertain, consider issuing a CAPTCHA, MFA, or additional verification step
When the response contains an error field, the request was not fully evaluated:
- An integration error fails closed with decision: "BLOCK" and signals: ["evaluation_error"]: a malformed payload or invalid JSON, or a key that resolves to no project. error.message names the cause — the offending field, Invalid server key, or Invalid site key for a visit-call. These are surfaced rather than passed silently, so a misconfigured integration cannot sit behind a stream of ALLOW with protection effectively off. Keys are UUIDs, so a wrong one parses cleanly and only fails project lookup — pasting a site key into server-key reaches this case.
- A BotBye-side failure fails open with decision: "ALLOW": the request was accepted but evaluation could not be completed, and our own fault must not block real users.
- The SDK fails open with decision: "ALLOW" and no request_id when it never received a decision at all — request timeout, connection error, or an unparseable response.
In every case error.message describes the underlying problem — monitor it and fix the root cause.
Examples of BotBye API responses
Blocked (bot detected):
1
2
3
4
5
6
7
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "BLOCK",
"risk_score": 0.95,
"scores": { "bot": 0.95 },
"signals": ["AutomationTool"]
}
Allowed:
1
2
3
4
5
6
7
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "ALLOW",
"risk_score": 0.05,
"scores": { "bot": 0.05, "ato": 0.02 },
"signals": []
}
Challenge:
1
2
3
4
5
6
7
8
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "CHALLENGE",
"risk_score": 0.65,
"scores": { "bot": 0.65 },
"signals": ["SuspiciousFingerprint"],
"challenge": { "type": "CAPTCHA" }
}
Invalid server-key — not a known project (fail-closed):
1
2
3
4
5
6
7
8
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "BLOCK",
"risk_score": 1.0,
"scores": {},
"signals": ["evaluation_error"],
"error": { "message": "Invalid server key" }
}
Evaluation error — request could not be processed (fail-closed):
1
2
3
4
5
6
7
8
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "BLOCK",
"risk_score": 1.0,
"scores": {},
"signals": ["evaluation_error"],
"error": { "message": "Invalid request body: missing or invalid field 'user.account_id'" }
}
SDK never received a decision (fail-open):
1
2
3
4
{
"decision": "ALLOW",
"error": { "message": "connection error" }
}
Middleware usage
Nitro server middleware (server/middleware/) runs before every matched request and is the best place to apply edge-level bot protection globally:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// server/middleware/botbye.js
import { evaluate } from "@botbye/nuxt/server";
export default defineEventHandler(async (event) => {
const result = await evaluate({
type: "validate",
request: {
request: event,
// "x-botbye-token" is an example — pass the token from wherever you store it
token: getRequestHeader(event, "x-botbye-token"),
},
});
if (result.decision === "BLOCK") {
throw createError({ statusCode: 403, message: "Forbidden" });
}
});
Advanced: multiple instances
Use factory to create independent SDK instances (useful when protecting multiple projects from one service):
1
2
3
4
5
6
7
8
9
10
11
12
13
import { factory } from "@botbye/nuxt/server";
const sdk = factory();
sdk.init({
// Use your project server-key
serverKey: "00000000-0000-0000-0000-000000000000",
});
const result = await sdk.evaluate({
type: "validate",
request: { request: event, token },
});
Dev utilities
1
2
3
import { dev } from "@botbye/nuxt/server";
dev.setLoggerLevel("debug"); // "error" | "warn" | "info" | "debug" | "log"