Developer documentation

JavaScript SDK

Install @abusezero/sdk once. Use its server entry point for trusted API calls and its browser entry point for optional browser evidence.

Node evaluations

Choose throw, allow, or deny for local technical outages. Local outage results are labeled source: local_outage and have no AbuseZero evaluation ID. Invalid credentials and invalid requests still throw. A 429 rate limit always throws: it is traffic protection, not an outage, so it never becomes a local allow or deny. While the 1.8-second budget lasts, the SDK retries 5xx responses and retryable 409 responses such as EVALUATION_PENDING with the same idempotency key. Skipped results have source: abusezero and status: skipped; they never use your outage fallback. Handle this branch before reading result.

import { AbuseZero } from "@abusezero/sdk/server";
const abusezero = new AbuseZero({
  key: process.env.ABUSEZERO_SECRET_KEY!,
  outage: "throw"
});
const result = await abusezero.evaluate({
  "benefit": "signup_credits",
  "claim_id": "signup_customer_123",
  "subject": {
    "external_id": "customer_123",
    "email": "alex@example.com",
    "email_verified": true
  },
  "context": {"ip": "192.0.2.10"}
}, "attempt_customer_123");
if ("status" in result && result.status === "skipped") {
  // Continue signup only if that is your explicit product choice.
  // There is no evaluation ID or policy decision in this branch.
  console.info("Evaluation skipped", result.reason);
} else {
  // Map allow or deny to your own product workflow.
  console.info(result.result);
}

Server-only hashing

createPhoneHash() and createCustomIdentifier() use deterministic, domain-separated HMAC-SHA256. Keep their secret in your backend and separate from AbuseZero API keys.

Bot verification

Use prepareBotObservation from the same browser SDK before evaluating a claim. It requests AbuseZero-managed Google verification and returns a device token when an observation can be created. An available observation does not guarantee usable bot evidence: blocked Google collection can retain ordinary browser recognition, and provider failures remain unavailable evidence. Choose Allow, Assess, or Deny automation per benefit; evidence is optional unless required explicitly. Allow still enforces eligibility, Assess considers automation as supporting evidence, and Deny can affect legitimate browser assistants. Missing evidence is not proof of a bot. Browser preparation has a separate 10-second limit; benefit evaluation keeps its existing deadline.

Install SDK 0.3

Install one package for server calls, browser observations, and the optional abusezero-mcp command. Use @abusezero/sdk/server on your backend and @abusezero/sdk/browser in browser code. Node 22 or later is required for server calls and the command. The package is available from AbuseZero's download URL; it is not published to npm.

npm install https://abusezero.com/sdk/abusezero-sdk-0.3.0.tgz

Upgrade existing integrations

Remove @abusezero/node and @abusezero/browser, install the single archive, and replace their imports with @abusezero/sdk/server and @abusezero/sdk/browser. The AbuseZero client class, API endpoints, credentials, and observation schema v2 remain unchanged. Earlier schema versions still require an upgrade. For script-based integrations, use https://abusezero.com/sdk/abusezero-sdk-browser-0.3.0.js.

Passive device attributes

After collection settings, origin, and consent checks pass, the SDK collects available browser/OS, screen, processor/memory hints, graphics, locale, input, storage, and detector results. Canvas, audio, and font measurements are hashed locally. It does not request permissions or collect MAC addresses, browsing history, page content, or raw rendering buffers. Failed collectors do not discard other observations. The fixed schema is limited to 64 KiB.

Device similarity

Exact browser and fingerprint history remains separate. Similarity compares scoped signatures within one benefit, using graphics 30, platform 20, screen 15, hardware 15, locale 10, and input 10 points. At least 4 comparable groups and 70 points of coverage are required; a candidate needs 85 matched points. This index is not an identity probability. More than 200 candidates produces an ambiguous result. Custom rules can use similarity alongside other evidence.

Verified agents

Call verifyAgentRequest(originalRequest, claimId, configuredPublicOrigin) in your Node backend before rewriting the request. The helper resolves Google-Agent through AbuseZero’s reviewed directory, fetches only its approved HTTPS key location, and verifies the supported Web Bot Auth profile. Pass its result as agent_evidence in evaluate(). Never pass this field from a browser unchanged: AbuseZero trusts your authenticated backend assertion. Signed component names state what was authenticated; an authority signature does not authenticate the path, body, or claim. The claim binding is your backend’s assertion. No Cloudflare account is required.

Agent choices and evidence

Select allowed_agents per benefit; it starts empty. A selected verified Google-Agent bypasses only generic automation restrictions and automation scoring. Browser anomalies, threat matches, rules, and benefit history remain active. Required bot evidence accepts a usable Google assessment or a selected verified agent; BotD alone is supplemental. GET /v1/agents and abusezero_list_agents expose the same reviewed directory with agents:read permission. Unsigned, verified, invalid, unrecognized, and unavailable results remain distinct. Google signs only some requests; unsigned traffic receives no verified-agent exception.

Threat-list facts

IPsum membership uses the supplied address or an explicitly listed CIDR, never the IPv6 activity grouping. Its count is the aggregate’s reported occurrence count, not independently verified sources. Block List Project malware, phishing, ransomware, fraud, and scam entries match the email’s exact normalized domain. AbuseZero does not infer reputation from MX providers or shared hosting IPs. Evaluations use local snapshots only and never validate mailbox deliverability. Sources expire for scoring 72 hours after their last successful check; a positive available match remains usable during another source’s outage, while a negative result needs all relevant sources.

Evidence access and expiry

GET /v1/evaluations/{id}/evidence, abusezero_get_evaluation_evidence, and evaluationEvidence() require evaluation_evidence:read; OAuth users also need reveal permission. Dashboard reveals are audited. Raw attributes expire after 7 days in Test or the organization’s 30/60/90-day Live setting. Normalized Test findings follow 30-day activity retention. Derived signatures follow benefit eligibility history and are removed by the corresponding recipient, organization, or Test cleanup. Exports include raw browser evidence only with include_evidence: true and evidence permission; downloading those exports requires the same permission.

Optional browser observation

The browser SDK runs only when enabled and when your consent callback returns true. It returns a token that is valid for 5 minutes. The browser sends it to your backend, and your backend includes it in the evaluation request as identifiers.device_token. If the token has expired, AbuseZero evaluates without browser evidence unless the benefit requires bot evidence; required evidence returns an error.

When browser scripts are blocked

For optional evidence, continue with the server-side evaluation request and omit the device token. Required bot evidence returns an error until fresh evidence is supplied. Email, IP, payment, phone, custom identifiers, and history remain available when supplied. AbuseZero does not fabricate a browser fingerprint on the server.