Quickstart

Install the packageCopy Anchor Link

npm install abusezero

The package has separate entry points for your server (abusezero/server) and your pages (abusezero/browser). Server code never loads in the browser.

Create a secret keyCopy Anchor Link

In the dashboard, open Developers → API keys and create a secret key. Store it in your server's environment as ABUSEZERO_SECRET_KEY.

ABUSEZERO_SECRET_KEY="sk_…"

Secret keys stay on your server. For keys limited to specific scopes, see restricted keys.

Evaluate the claimCopy Anchor Link

Call AbuseZero from your server before you grant the benefit, with evaluate() or POST /v1/evaluations. claim_id identifies this one award in your system, such as the trial's ID (see Re-evaluating a claim_id). The idempotency key makes the call safe to retry.

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({
  key: process.env.ABUSEZERO_SECRET_KEY!,
  outage: "throw",
});

export async function startTrial(
  user: { id: string; email: string; emailVerified: boolean },
  trialId: string,
  ip: string,
  deviceToken: string,
) {
  const evaluation = await abusezero.evaluate(
    {
      benefit: "pro_trial",
      claim_id: trialId,
      subject: { external_id: user.id, email: user.email, email_verified: user.emailVerified },
      context: { ip },
      identifiers: { device_token: deviceToken },
    },
    `evaluate-${trialId}`,
  );

  if ("status" in evaluation) {
    // Skipped: no allow or deny was decided.
    return { started: false };
  }

  if (evaluation.result === "deny") {
    return { started: false };
  }

  // Grant the trial in your application here.
  return { started: true };
}

Replace the example IP address with your visitor's public address. 203.0.113.42 comes from a range reserved for documentation, and AbuseZero rejects documentation, private and other non-routable addresses with IP_NOT_ROUTABLE.

AbuseZero responds with the result:

{
  "object": "evaluation",
  "id": "eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93",
  "result": "allow",
  "risk": { "score": 10, "band": "low" },
  "reason": { "code": "default_allow", "message": "No rule matched, so the policy's default allowed this claim." },
  "outcome": { "state": "assumed_granted", "due_at": null }
}

Branch on result, and keep the reason for your team. When the workspace can't run an evaluation, for example because it has no credits left, the response is { "object": "evaluation", "status": "skipped", "reason": "…" } with no result. Handle it as its own branch. See skipped evaluations and Handle outages and retries.

Add browser protectionCopy Anchor Link

Browser protection connects your pages to AbuseZero's device and automation intelligence. Load the AbuseZero browser SDK with your publishable key, collect a device token for the claim, and send it to your server with the claim.

import { init, observe } from "abusezero/browser";

init({ key: "pk_…" }); // once, when your app starts

const { deviceToken } = await observe({ key: "pk_…", claimId: trialId });
// Send deviceToken to your server with the claim, then pass it as identifiers.device_token.

• Use the same claim ID in the browser and on your server.
• Always send deviceToken, whatever its status. When there is no browser data, it carries the reason instead. See unavailable reasons.
• Add your site under Your sites in Developers → Browser setup, or with PATCH /v1/browser-collection. AbuseZero accepts browser data only from HTTPS sites in your site list. If your site sets a Content Security Policy, copy the sources shown there into it.

Your publishable key is in Developers → API keys. It only works for browser collection, so it is safe in your pages. For the complete setup, see Set up browser protection.

Report the outcomeCopy Anchor Link

By default, an allowed claim counts as granted automatically (assumed_granted). If your benefit is set to report outcomes, tell AbuseZero what happened after you acted on the result, with outcome() or POST /v1/evaluations/{id}/outcome:

await abusezero.outcome(
  evaluation.id,
  { outcome: "granted" },
  `outcome-${trialId}`,
);

Reported outcomes become the claim history that later evaluations are checked against. See Report outcomes.

Verify your integrationCopy Anchor Link

Open Evaluations in the dashboard, or retrieve the evaluation by its ID. Your evaluation appears with its result, reason, AbuseZero Risk Score, policy version, the inputs it received and the browser data status.

• inputs.device shows received when the device token reached the evaluation.
• browser_data shows collected when the browser SDK is set up correctly.

If something is missing, see Troubleshooting and the Developer FAQ.