How AbuseZero works
The lifecycle of a claim, from benefit to evaluation, result, outcome and history.
Every protected claim follows the same lifecycle. You define the benefit once. Your server evaluates each claim, acts on the result and, when you choose, reports what happened. Every outcome becomes history that later evaluations are checked against.
Benefits
A benefit is anything you give out on a limited basis: a free trial, a free plan, sign-up credits or a promotional offer. Create benefits in the dashboard, with POST /v1/benefits, with abusezero benefits create in the AbuseZero CLI, or with abusezero_create_benefit on the AbuseZero MCP server. Each benefit has its own settings:
- Eligibility: once per user, once per calendar day, week or month, or once per rolling number of days.
- Policy: an AbuseZero protection level, or your own custom rules built on one.
- Mode: protect, where results are applied, or observe, where AbuseZero records what it would have decided while every claim is allowed.
- Outcome tracking: count allowed claims as granted automatically, or report each outcome yourself. See tracking models.
- Automation and AI agents: how automated traffic is treated, and which recognized agents may claim the benefit.
See Benefits.
Evaluations
When someone claims a benefit, your server calls POST /v1/evaluations, or evaluate() in the AbuseZero Node.js SDK, with the benefit key, a claim ID, the user, and the identifiers you have: IP address, device token, phone, payment method and your own custom identifiers.
Within that one call, AbuseZero checks every identifier against your workspace's full claim history, assesses five signal families (identity, device, network, automation and benefit history), recognizes AI agents that can prove who they are, and applies your protection level, rules and lists. Evidence that is slow or unavailable doesn't hold the evaluation up. It finishes within the time limit with everything it has, and reports which inputs it received.
The response is one final result:
| Field | What it tells you |
|---|---|
result | allow or deny. Your application acts on this. |
risk | The AbuseZero Risk Score from 0 to 100, or null when no score was produced, and its band. |
reason | A stable code and a readable message explaining the result. See Reason codes. |
outcome | The claim's outcome state, when one applies. |
Every evaluation is stored with the exact policy version it ran under. Open any past evaluation and you see the decision exactly as it was made, even after your rules have changed. See Evaluations.
Outcomes and history
A result is a decision. An outcome is what actually happened: the benefit was granted, wasn't granted, or was granted and later reversed.
Outcomes are what later evaluations are checked against. A claim that was granted makes the same user, email, device, phone or payment method visible to every future evaluation of that benefit. Report outcomes with POST /v1/evaluations/{id}/outcome or outcome() in the AbuseZero Node.js SDK. You can also import your existing outcome history, so protection starts with everything you already know on day one. See Report outcomes.
What you control
| Control | What it does |
|---|---|
| Protection levels | Lenient, Balanced or Strict. AbuseZero defines and maintains each level. |
| Custom rules | Your own conditions, added to a protection level. |
| Allow and block lists | Always allow or always deny specific emails, domains, IP addresses, users or devices. |
| Observe mode | See what AbuseZero would decide, without affecting any user. |
| Previews, simulations and replays | Test a change against a single request, a sequence of claims or your recent traffic before it goes live. |
Previews run the full evaluation without recording a claim. Simulations and replays apply a policy with the same evaluation engine as your live traffic, using what your past evaluations recorded.
Integration options: REST API, Node.js SDK, CLI and MCP server
Every action is available through the AbuseZero REST API, the AbuseZero Node.js SDK, the AbuseZero CLI and the AbuseZero MCP server, with the same inputs and the same results. The coverage table lists each action and where to find it. Browser data is the one exception: it comes only from the AbuseZero browser SDK on your pages.
Next steps
How is this guide?
Last updated on