AbuseZero Python SDK
Use the AbuseZero Python SDK to evaluate claims and manage your workspace from your server. AbuseZero is an abuse prevention API for SaaS.
Install
python -m pip install abusezero
The SDK supports Python 3.11 to 3.15. It requires HTTPX, which pip installs with it.
The package includes its SDK license as LICENSE. HTTPX and its dependencies are installed separately and keep their own licenses. API.md, the Django and FastAPI examples and an example script are in the GitHub repository.
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.
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 evaluation calls can return source: local_outage; other operations raise an error. Rate limits always remain errors. Skipped responses remain skips, including unknown skip reasons.
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 lists every method; 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.
Frameworks and browser protection
The Django and FastAPI examples are in examples/frameworks.md; no framework dependency is required.
For 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, evaluation results and webhooks.
Metadata
Release files for abusezero 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| abusezero-0.1.0.tar.gz | 83.9 kB | With provenance | Details for abusezero-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| abusezero-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for abusezero-0.1.0-py3-none-any.whl |
Total release size: 165.2 kB
Release files / abusezero-0.1.0.tar.gz
| Download URL | abusezero-0.1.0.tar.gz |
|---|---|
| Size | 83.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3c26e20df04bbbe6a615391ea20b7d22a5426c03e21e4c6f04cf684a0b04c9b8
|
|
BLAKE2b-256 checksum How to use checksums |
089523c572f56e66800ebec423717d8e7ed09163dc4cf36637234a180b62e5a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / abusezero-0.1.0-py3-none-any.whl
| Download URL | abusezero-0.1.0-py3-none-any.whl |
|---|---|
| Size | 81.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4ee456701471f17e36cdc21c0a1065f7c7b0b0d7d9f2987084c401d1b36f096e
|
|
BLAKE2b-256 checksum How to use checksums |
04d49fb9ab4126b39b1a7181debbc3e934cdc08b3fc7121c5ec4caa354741832
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for abusezero 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for abusezero-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.