AbuseZeroAbuseZero

AbuseZero Python SDK

Use the AbuseZero Python SDK, abusezero, to evaluate claims, report outcomes and manage your workspace from your Python server.

The AbuseZero Python SDK, abusezero, is the typed Python client for the AbuseZero REST API. It has a synchronous and an async client, retries transient failures within a fixed request budget, and lets you set in advance what happens if AbuseZero can't be reached.

Install the Python SDK

python -m pip install abusezero

The Python SDK supports Python 3.11 to 3.15. It requires HTTPX, which pip installs with it. Keep the SDK, and your secret key, on your server. The package is on PyPI.

Evaluate and report a grant

Store your secret key or restricted key in ABUSEZERO_SECRET_KEY on the server. Use a stable claim ID and keep the same idempotency key when retrying the same action.

import os
from collections.abc import Callable
from abusezero import AbuseZero


def create_client() -> AbuseZero:
    return AbuseZero(key=os.environ["ABUSEZERO_SECRET_KEY"], outage="throw")


def evaluate_and_grant(client: AbuseZero, claim_id: str, email: str,
                       grant: Callable[[str], None]):
    result = client.evaluate({
        "benefit": "pro_trial", "claim_id": claim_id,
        "subject": {"email": email},
    }, idempotency_key="evaluate:" + claim_id)
    if "status" in result:
        return result  # No decision was made.
    if result["source"] == "local_outage" or result["result"] != "allow":
        return result
    grant(claim_id)  # Your transaction must finish successfully before returning.
    client.outcome({"outcome": "granted"}, path={"id": result["id"]},
                   idempotency_key="grant:" + claim_id)
    return result

Create the client once at worker startup, reuse it across requests and close it at shutdown. Call this helper from your authenticated handler with your own stored claim ID, authenticated user email and transactional grant function. The grant function must be idempotent for that claim ID. The helper reports granted only after the grant function succeeds; if reporting fails afterward, retry with the same claim ID and keys. On deny, don't grant the benefit. A skipped result is neither allow nor deny, including when its reason is new to your application.

Clients and credentials

import os
from abusezero import AbuseZero, AbuseZeroPublic, AsyncAbuseZero

# An OAuth access token, from a sign-in or a machine client, acts in the selected workspace.
oauth = AbuseZero(access_token=os.environ["ABUSEZERO_ACCESS_TOKEN"],
                  workspace=os.environ["ABUSEZERO_WORKSPACE"], outage="throw")
keys = oauth.api_keys({"limit": 20})

# The public client reads public information and sends no credentials.
with AbuseZeroPublic() as public:
    pricing = public.pricing()


async def list_benefits(client: AsyncAbuseZero):
    # Create the async client once for your event loop and reuse it, like the synchronous client.
    return await client.benefits({"limit": 20})

Management operations need an OAuth access token, from a sign-in or a machine client. An API key alone can't perform them. The selected workspace and the approving member's permissions still apply. Some actions act for one member or follow what that member may do, such as notifications, support tickets and changes to members, and need that member's own sign-in; API keys and machine clients get MEMBER_SIGN_IN_REQUIRED for them. See Actions that need a member's own sign-in.

Async methods support task cancellation. The synchronous client also works inside an async application, but use AsyncAbuseZero to avoid blocking its event loop. Pass an HTTPX transport with transport= to configure a proxy or a test service. The client owns and closes it. Custom synchronous transports must honor the request timeout; the built-in transport cancels requests when the total budget ends.

Webhooks

from abusezero import WebhookVerificationError, verify_webhook


def receive(raw_body: bytes, headers: dict[str, str], current_secret: str, previous_secret: str | None):
    try:
        # Use the original request bytes. Keep both secrets during rotation.
        event = verify_webhook(payload=raw_body, headers=headers,
                               secret=[current_secret, previous_secret])
    except WebhookVerificationError:
        return 400
    ...  # Deduplicate by event["id"], then handle the event.
    return 200

verify_webhook(payload=, headers=, secret=, tolerance_seconds=300) checks the signature over the original request bytes and the timestamp within tolerance_seconds, accepts rotating secrets and rejects a modified body. It returns the event, or raises WebhookVerificationError when the signature or event body can't be verified. Deduplicate accepted events by their event ID in your application. See Receive webhooks.

Errors, retries and results

Catch AbuseZeroError. Its fields are code, status, request_id, retryable and docs_url. status is the HTTP status, or 0 for TRANSPORT_ERROR and DEADLINE_EXCEEDED, which have no response. The SDK raises these before sending a request, each with a 4xx status: CREDENTIAL_REQUIRED, INVALID_KEY, INVALID_TOKEN, WORKSPACE_REQUIRED, INVALID_WORKSPACE, OAUTH_REQUIRED, INVALID_IDEMPOTENCY_KEY and INVALID_REQUEST. INVALID_RESPONSE means a response couldn't be read.

Set outage to throw, allow or deny. The default is throw. Only evaluate can return source: local_outage; other operations, dry-run evaluations included, raise an error. Rate limits always remain errors. Skipped responses remain skips, including unknown skip reasons. See Evaluations for what each result means.

Within v1, responses can gain new fields and new values for codes and enums. The SDK returns them unchanged, so handle a value your code doesn't recognize as a generic case.

Calls make at most three attempts. Network errors, retryable API errors and HTTP 429, 502, 503 and 504 are retried. Retry-After sets the minimum wait. Every attempt uses identical serialized input and the same idempotency key. The entire call, including waits, has one budget: 1.8 seconds for evaluate and 5 seconds for other calls, dry runs included. An events long poll adds 5 seconds to its requested wait. The server's own operation deadline can be shorter.

Methods and pagination

Every public server operation has a method. Pass input fields in the method's input and path fields separately in path. Mutation methods require an idempotency key. API.md, in the package's source distribution, lists every method with its operation and scope. See the AbuseZero REST API reference for each operation's fields.

List methods accept cursor and limit where documented. Process the returned data, then pass the returned next_cursor to the same method until it is null. Keep IDs and cursors as strings. Send null only when the field allows it; omitting a field leaves it absent.

Incoming requests and identifiers

import os
from abusezero import AbuseZero, create_custom_identifier, create_phone_hash, incoming_request


def evaluate_with_identifiers(client: AbuseZero, claim_id: str, email: str,
                              method: str, url: str, headers: dict[str, str]):
    secret = os.environ["IDENTIFIER_HASH_SECRET"]
    phone_hash = create_phone_hash(secret=secret, key_version="v1", e164="+14155550123")
    team = create_custom_identifier(secret=secret, key_version="v1", key="team_id", value="team_8812")
    return client.evaluate({
        "benefit": "pro_trial", "claim_id": claim_id, "subject": {"email": email},
        "identifiers": {"phone_hash": phone_hash, "phone_verified": True, "custom": [team]},
        "request": incoming_request(method, url, headers),
    }, idempotency_key="evaluate:" + claim_id)

incoming_request(method, url, headers) takes the incoming HTTP method, absolute URL and headers, and removes credential headers before you include the request in an evaluation. It doesn't infer a trusted client IP; use your application's trusted proxy configuration for that.

create_phone_hash(secret=, key_version=, e164=) needs a number in E.164 format. create_custom_identifier(secret=, key_version=, key=, value=) needs a registered identifier key. Both return the public API's hash objects. Use the same secret and key_version everywhere the same value should match. See Send identifiers.

Django and FastAPI

No framework dependency is required. Reuse the client for the application's lifetime, and pass the incoming request helper's result as request in the evaluation input.

Django
import os
from abusezero import AbuseZero, incoming_request

client = AbuseZero(key=os.environ["ABUSEZERO_SECRET_KEY"], outage="throw")  # Once per worker.


def evaluate_claim(request, claim_id: str):
    incoming = incoming_request(request.method, request.build_absolute_uri(), dict(request.headers))
    return client.evaluate({
        "benefit": "pro_trial", "claim_id": claim_id,
        "subject": {"email": request.user.email}, "request": incoming,
    }, idempotency_key="evaluate:" + claim_id)
FastAPI
from contextlib import asynccontextmanager
import os
from fastapi import FastAPI, Request
from abusezero import AsyncAbuseZero, incoming_request

@asynccontextmanager
async def lifespan(app):
    async with AsyncAbuseZero(key=os.environ["ABUSEZERO_SECRET_KEY"], outage="throw") as client:
        app.state.abusezero = client
        yield

app = FastAPI(lifespan=lifespan)

async def evaluate_claim(request: Request, claim_id: str, verified_email: str):
    return await request.app.state.abusezero.evaluate({
        "benefit": "pro_trial", "claim_id": claim_id,
        "subject": {"email": verified_email},
        "request": incoming_request(request.method, str(request.url), dict(request.headers)),
    }, idempotency_key="evaluate:" + claim_id)

Call these from your authenticated routes, and follow the skipped, outage, allow and deny branches above before granting anything. For webhooks, pass await request.body() in FastAPI, or request.body in Django, to verify_webhook before parsing JSON.

Browser protection

Add the standalone browser script to your page and pass its device token to your server. Send the token unchanged in the evaluation input as identifiers.device_token. This SDK is the only package to install. See Set up browser protection.

API origin and TLS

The default API origin is https://api.abusezero.com. Custom origins require HTTPS; HTTP is accepted only for explicit loopback testing. Built-in transports verify TLS and refuse redirects. Custom transports are responsible for equivalent behavior. Never log credentials or raw authenticated requests.

More documentation

See Authentication, Evaluations and Receive webhooks.

How is this guide?

Last updated on