Policies

A policy decides the claims of every benefit that uses it. Every workspace has three protection levels, Lenient, Balanced and Strict, which AbuseZero defines and maintains. You can use a level as it is, or build a custom policy on one with your own rules.

With an OAuth access token, policies:write also needs the member's Publish policies and benefits permission.

The policy objectCopy Anchor Link

Protection levelsCopy Anchor Link

Protection levels appear in every workspace as managed policies with the keys lenient, balanced and strict. AbuseZero defines and maintains what each level contains. Levels are read-only: to change one, duplicate it and edit the copy.

See Protection levels for how to choose one.

Custom policy definitionCopy Anchor Link

A custom policy is a definition you write. It can build on a protection level.

How a policy decidesCopy Anchor Link

1. Your rules are checked in the order you list them. The first rule that matches decides the result.
2. Your rules take priority over the protection level you build on.
3. When no rule decides, a claim whose AbuseZero Risk Score reaches risk_threshold is denied.
4. Otherwise, default_result applies.

Allow and block list entries decide a matching claim outright, whatever the policy says. Each evaluation's reason tells you what decided it. See Reason codes.

RulesCopy Anchor Link

Conditions and groupsCopy Anchor Link

A condition compares one value with your value:

{ "signal": "network.anonymous", "operator": "eq", "value": true }

Combine conditions with a group. all matches when every item matches. any matches when at least one item matches.

{
  "all": [
    { "signal": "network.anonymous", "operator": "eq", "value": true },
    { "any": [
      { "signal": "email.verified", "operator": "eq", "value": false },
      { "signal": "email.disposable", "operator": "eq", "value": true }
    ] }
  ]
}

• A group holds 1 to 10 items.
• Groups nest at most two levels deep.
• A rule has at most 10 conditions in total.

OperatorsCopy Anchor Link

Comparison operators match only when the condition has a value. Use the status operators to write rules for inputs you didn't send or values that weren't available.

Create a policyCopy Anchor Link

POST /v1/policies · Scope policies:write · Requires Idempotency-Key

Also available as abusezero policies create in the AbuseZero CLI, abusezero_create_policy on the AbuseZero MCP server and createPolicy() in the AbuseZero Node.js SDK.

Creates a custom policy at version 1.

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

import { randomUUID } from "node:crypto";

const policy = await abusezero.createPolicy(
  {
    name: "Trial protection",
    key: "trial_protection",
    definition: {
      base: "balanced",
      default_result: "allow",
      rules: [
        {
          id: "unverified_anonymous",
          name: "Unverified email on an anonymous network",
          result: "deny",
          when: {
            all: [
              { signal: "network.anonymous", operator: "eq", value: true },
              { signal: "email.verified", operator: "eq", value: false },
            ],
          },
        },
      ],
    },
  },
  randomUUID(),
);

ResponseCopy Anchor Link

Returns 201.

{
  "object": "policy",
  "id": "pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35",
  "revision": 1,
  "version": 1
}

To start using the policy, set it as a benefit's policy_key. To see its effect first, run a replay.

ErrorsCopy Anchor Link

List policiesCopy Anchor Link

GET /v1/policies · Scope policies:read

Also available as abusezero policies list in the AbuseZero CLI, abusezero_list_policies on the AbuseZero MCP server and policies() in the AbuseZero Node.js SDK.

Lists the workspace's protection levels and custom policies, newest first.

Query parametersCopy Anchor Link

ExampleCopy Anchor Link

const page = await abusezero.policies({ limit: 50 });

ResponseCopy Anchor Link

A list of policy objects.

ErrorsCopy Anchor Link

Retrieve a policyCopy Anchor Link

GET /v1/policies/{id} · Scope policies:read

Also available as abusezero policies get in the AbuseZero CLI, abusezero_get_policy on the AbuseZero MCP server and getPolicy() in the AbuseZero Node.js SDK.

ExampleCopy Anchor Link

const policy = await abusezero.getPolicy("pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35");

ResponseCopy Anchor Link

{
  "object": "policy",
  "id": "pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35",
  "key": "trial_protection",
  "name": "Trial protection",
  "kind": "custom",
  "active_version": 2,
  "created_at": "2026-10-28T09:15:00.000Z",
  "updated_at": "2026-10-29T11:20:00.000Z"
}

To read the rules, retrieve the active version.

ErrorsCopy Anchor Link

Update a policyCopy Anchor Link

PATCH /v1/policies/{id} · Scope policies:write · Requires Idempotency-Key

Also available as abusezero policies update in the AbuseZero CLI, abusezero_update_policy on the AbuseZero MCP server and updatePolicy() in the AbuseZero Node.js SDK.

Saves a new version of a custom policy. Send the complete definition. Every benefit that uses the policy evaluates with the new version from the moment the update succeeds. Earlier evaluations keep the version they ran under.

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

import { randomUUID } from "node:crypto";

await abusezero.updatePolicy(
  "pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35",
  {
    name: "Trial protection",
    definition: { base: "strict", default_result: "allow", rules: [] },
    revision: 2,
  },
  randomUUID(),
);

ResponseCopy Anchor Link

Returns 200.

{
  "object": "policy",
  "id": "pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35",
  "revision": 3,
  "version": 3
}

ErrorsCopy Anchor Link

Duplicate a policyCopy Anchor Link

POST /v1/policies/{id}/duplicate · Scope policies:write · Requires Idempotency-Key

Also available as abusezero policies duplicate in the AbuseZero CLI, abusezero_duplicate_policy on the AbuseZero MCP server and duplicatePolicy() in the AbuseZero Node.js SDK.

Creates a new custom policy from the active version of an existing one. Duplicating a protection level creates a custom policy built on that level, ready for your own rules.

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

import { randomUUID } from "node:crypto";

const copy = await abusezero.duplicatePolicy(
  "pol_0e6b4d82-7a3c-4f19-8b5e-1d9c7a3f5e60",
  { name: "Balanced with my rules", key: "balanced_custom" },
  randomUUID(),
);

ResponseCopy Anchor Link

Returns 201.

{
  "object": "policy",
  "id": "pol_b3f7d1a9-2c6e-4d85-9a0b-6e4c2f8d1b39",
  "revision": 1,
  "version": 1
}

ErrorsCopy Anchor Link

Delete a policyCopy Anchor Link

DELETE /v1/policies/{id} · Scope policies:write · Requires Idempotency-Key

Also available as abusezero policies delete in the AbuseZero CLI, abusezero_delete_policy on the AbuseZero MCP server and deletePolicy() in the AbuseZero Node.js SDK.

ExampleCopy Anchor Link

import { randomUUID } from "node:crypto";

await abusezero.deletePolicy("pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35", randomUUID());

ResponseCopy Anchor Link

Returns 200.

{
  "object": "deleted",
  "id": "pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35",
  "deleted": true
}

ErrorsCopy Anchor Link

List policy versionsCopy Anchor Link

GET /v1/policies/{id}/versions · Scope policies:read

Also available as abusezero policies versions in the AbuseZero CLI, abusezero_list_policy_versions on the AbuseZero MCP server and call() in the AbuseZero Node.js SDK.

Lists every version of a policy, newest first, in one page.

ExampleCopy Anchor Link

const versions = await abusezero.call(
  "/v1/policies/pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35/versions",
);

ResponseCopy Anchor Link

{
  "object": "list",
  "data": [
    { "object": "policy_version", "version": 2, "created_at": "2026-10-29T11:20:00.000Z" },
    { "object": "policy_version", "version": 1, "created_at": "2026-10-28T09:15:00.000Z" }
  ],
  "next_cursor": null
}

Retrieve a policy versionCopy Anchor Link

GET /v1/policies/{id}/versions/{version} · Scope policies:read

Also available as abusezero policies version in the AbuseZero CLI, abusezero_get_policy_version on the AbuseZero MCP server and call() in the AbuseZero Node.js SDK.

Returns one version. For a custom policy, the version includes the definition you saved. For a protection level, it names the level only: AbuseZero keeps each level's contents private.

ExampleCopy Anchor Link

const version = await abusezero.call(
  "/v1/policies/pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35/versions/2",
);

ResponseCopy Anchor Link

{
  "object": "policy_version",
  "version": 2,
  "managed": false,
  "definition": {
    "base": "balanced",
    "risk_threshold": 75,
    "default_result": "allow",
    "rules": [
      {
        "id": "unverified_anonymous",
        "name": "Unverified email on an anonymous network",
        "result": "deny",
        "when": {
          "all": [
            { "signal": "network.anonymous", "operator": "eq", "value": true },
            { "signal": "email.verified", "operator": "eq", "value": false }
          ]
        }
      }
    ]
  },
  "created_at": "2026-10-29T11:20:00.000Z"
}

{
  "object": "policy_version",
  "version": 1,
  "managed": true,
  "level": "balanced",
  "created_at": "2026-10-01T08:00:00.000Z"
}

ErrorsCopy Anchor Link

List conditionsCopy Anchor Link

GET /v1/policy-signals · Scope policies:read

Also available as abusezero policies signals in the AbuseZero CLI, abusezero_list_policy_signals on the AbuseZero MCP server and call() in the AbuseZero Node.js SDK.

Lists every condition your custom rules can use, in one page. Takes no parameters.

ExampleCopy Anchor Link

const conditions = await abusezero.call("/v1/policy-signals");

ResponseCopy Anchor Link

{
  "object": "list",
  "data": [
    { "object": "condition", "key": "email.verified", "label": "Email verified by your app", "type": "boolean" },
    { "object": "condition", "key": "user.prior_claims", "label": "Earlier claims by this user", "type": "number", "min": 0 },
    { "object": "condition", "key": "network.risk", "label": "Network risk", "type": "string", "values": ["low", "elevated", "high"] }
  ],
  "next_cursor": null
}

The example shows three of the conditions.

Available conditionsCopy Anchor Link

For a custom identifier condition, replace <key> with the key of a registered custom identifier, such as custom.license_id.prior_outcomes. A custom identifier that a policy uses can't be deleted. New conditions can be added within v1.