AbuseZeroAbuseZero

AbuseZero Go SDK

Use the AbuseZero Go SDK, github.com/abusezero/abusezero-go, to evaluate claims, report outcomes and manage your workspace from your Go server.

The AbuseZero Go SDK, github.com/abusezero/abusezero-go, is the Go client for the AbuseZero REST API. It has a method for every public server operation, retries transient failures within a fixed request budget, and lets you choose in advance what happens if AbuseZero can't be reached.

Install the Go SDK

In your Go module, run:

go get github.com/abusezero/abusezero-go

Import it as abusezero:

import abusezero "github.com/abusezero/abusezero-go"

The SDK supports Go 1.26 and 1.27 and uses only the Go standard library. It's proprietary, and its license ships with it as LICENSE.

Create a Go SDK client

Store your secret key or restricted key in ABUSEZERO_SECRET_KEY on your server. Create one client when your server starts, reuse it for every request, and call Close at shutdown.

func NewClient() (*abusezero.Client, error) {
	return abusezero.New(abusezero.Options{Key: os.Getenv("ABUSEZERO_SECRET_KEY"), Outage: "throw"})
}

Client options

FieldTypeRequiredDescription
KeystringOne of Key or AccessTokenA secret key (sk_…) or restricted key (rk_…). Publishable keys are rejected.
AccessTokenstringOne of Key or AccessTokenAn OAuth access token. Requires Workspace.
WorkspacestringWith AccessTokenThe ID of the workspace this OAuth connection works in.
Outage"throw", "allow" or "deny"NoWhat Evaluate returns when AbuseZero can't be reached. The default is "throw". See Outages.
BaseURLstringNoThe API origin. The default is https://api.abusezero.com. A custom origin must use HTTPS; HTTP is accepted only on loopback, for local testing.
Transporthttp.RoundTripperNoSends every request through your own transport, for example through a proxy. It must honor context cancellation and verify TLS.
AgentstringNoThe AbuseZero-Agent value your agent reports on each request.

New returns CREDENTIAL_REQUIRED for neither or both of Key and AccessToken, INVALID_KEY for a key that isn't a secret or restricted key, and WORKSPACE_REQUIRED for an access token without a workspace. See Go SDK errors.

Evaluate a claim and report the outcome

Use a stable claim ID, and keep the same idempotency key when you retry the same action.

package examples

import (
	"context"
	"errors"
	"os"

	abusezero "github.com/abusezero/abusezero-go"
)

func NewClient() (*abusezero.Client, error) {
	return abusezero.New(abusezero.Options{Key: os.Getenv("ABUSEZERO_SECRET_KEY"), Outage: "throw"})
}

func EvaluateAndGrant(ctx context.Context, client *abusezero.Client, claimID, email string,
	grant func(context.Context, string) error) (any, error) {
	if grant == nil {
		return nil, errors.New("provide a grant function")
	}
	result, err := client.Evaluate(ctx, abusezero.EvaluationsCreateInput{
		Benefit: "pro_trial", ClaimID: claimID,
		Subject: abusezero.EvaluationsCreateInputSubject{Email: email},
	}, &abusezero.CallOptions{IdempotencyKey: "evaluate:" + claimID})
	if err != nil {
		return nil, err
	}
	evaluation := result.(map[string]any)
	if evaluation["status"] == "skipped" || evaluation["source"] == "local_outage" || evaluation["result"] != "allow" {
		return result, nil
	}
	// Your transaction must finish successfully before returning.
	if err := grant(ctx, claimID); err != nil {
		return result, err
	}
	_, err = client.Outcome(ctx, abusezero.OutcomesReportInput{Outcome: "granted"},
		&abusezero.CallOptions{Path: map[string]any{"id": evaluation["id"]}, IdempotencyKey: "grant:" + claimID})
	return result, err
}

Call this helper from your authenticated handler with your own stored claim ID, the authenticated user's email and a transactional grant function. The grant function must be idempotent for that claim ID. The helper reports the outcome granted only after the grant function succeeds. If reporting fails afterward, retry with the same claim ID and idempotency keys. On deny, don't grant the benefit.

Results

Evaluate returns a map[string]any in one of three shapes. Check status first, then source.

ShapeFieldsMeaning
Evaluatedsource: "abusezero", id, result, risk, reason, outcomeAbuseZero evaluated the claim. result is allow or deny.
Skippedsource: "abusezero", status: "skipped", reasonThe workspace couldn't run the evaluation, so there's no result.
Local outagesource: "local_outage", claim_id, result, errorAbuseZero couldn't be reached. result is your Outage setting, and error holds the code, message and status behind it.

A skipped evaluation is neither allow nor deny. Handle it as its own branch, even when its skip reason is new to your application. Your Outage setting never applies to a skip. risk, reason and outcome are described in Evaluations.

Outages

Set Outage to throw, allow or deny. With throw, Evaluate returns the error. With allow or deny, it returns a local outage result with that result when the call fails with a retryable error other than a rate limit. Only Evaluate returns local outage results. DryRunEvaluation and every other method return the error, and rate limits always remain errors.

Retries

Calls make at most three attempts. Network errors, retryable API errors and HTTP 429, 502, 503 and 504 may be retried, and Retry-After sets the minimum wait. Every attempt sends the same serialized input and the same idempotency key.

The whole call, waits included, has one request budget: 1.8 seconds for Evaluate and 5 seconds for every other method, DryRunEvaluation included. An Events long poll adds 5 seconds to its requested wait. AbuseZero's own time limits can be shorter. When the budget runs out, the call returns DEADLINE_EXCEEDED.

Every method takes a context.Context. Cancel it to stop an in-flight call; the method then returns context.Canceled.

Methods and pagination

Every public server operation has a method, and API.md, in the module source that go get downloads, lists them all. Pass the operation's body or query fields in the input value, and its path fields in CallOptions.Path. Mutations require CallOptions.IdempotencyKey.

List methods accept Cursor and Limit where the operation has them. Process each page's Data, then pass its NextCursor to the same method until it's null. Keep IDs and cursors as strings.

func EachEvaluation(ctx context.Context, client *abusezero.Client, handle func(abusezero.EvaluationsListResponseDataItem)) error {
	var cursor abusezero.Optional[string]
	for {
		page, err := client.Evaluations(ctx, abusezero.EvaluationsListInput{Cursor: cursor}, nil)
		if err != nil {
			return err
		}
		for _, item := range page.Data {
			handle(item)
		}
		next, ok := page.NextCursor.(string)
		if !ok {
			return nil
		}
		cursor = abusezero.Some(next)
	}
}

Types

Optional[T] tells omission apart from null. Use Some(value) to send a value and Null[T]() to send null where the schema allows it. Omitting a field leaves it out of the request.

Response structs type the fields whose shape is fixed. Every other field, including some documented ones such as an outcome report's state, stays in Extra as raw JSON. Decode one with encoding/json, for example json.Unmarshal(report.Extra["state"], &state). Evaluate and DryRunEvaluation return map[string]any.

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.

Credentials and public reads

Use AccessToken and Workspace for OAuth. Management operations need an OAuth access token; an API key alone can't run them. The selected workspace and the approving member's permissions still apply.

NewPublic creates a client for the public operations, such as pricing. It sends no credentials.

func ReadPricing(ctx context.Context) (abusezero.PublicPricingResponse, error) {
	public, err := abusezero.NewPublic(abusezero.Options{})
	if err != nil {
		return abusezero.PublicPricingResponse{}, err
	}
	defer public.Close()
	return public.Pricing(ctx, map[string]any{}, nil)
}

Verify webhooks

Verify the signature over the original request bytes before you read the event.

// Pass the raw request bytes and the original request headers.
func VerifyEvent(rawBody []byte, header http.Header, currentSecret, previousSecret string) (map[string]any, error) {
	return abusezero.VerifyWebhook(rawBody, header,
		[]string{currentSecret, previousSecret}, 300*time.Second, time.Now())
}

Pass the timestamp tolerance explicitly, as shown with 300*time.Second. Verification accepts the current and previous signing secrets and rejects a modified body. Deduplicate accepted events by their event ID in your application.

Incoming requests and identifiers

IncomingRequest takes the HTTP method, absolute URL and headers of the request your server received. It removes credential headers and returns the value for the evaluation's Request. It doesn't infer a trusted client IP. Send the IP your trusted proxy configuration reports in the evaluation's Context, as abusezero.Some[any](map[string]any{"ip": ip}).

CreatePhoneHash requires an E.164 phone number. CreateCustomIdentifier requires a custom identifier's registered key and its value. Keep the hash secret and key_version the same across applications that should recognize the same identifier. CreatePhoneHash returns the value for Identifiers.PhoneHash; send Identifiers.PhoneVerified with it. CreateCustomIdentifier returns an item for Identifiers.Custom.

The helpers return the types Evaluate takes. For DryRunEvaluation, convert the request and phone hash, such as abusezero.EvaluationsDryRunInputRequest(request), and build each custom identifier from its Key and its converted ValueHash.

Browser protection

Load the standalone browser script on your page and pass its device token to your server. Send the token unchanged as Identifiers.DeviceToken in the evaluation input. The Go SDK is the only package to install. In the module source, examples/frameworks.md shows a Go HTTP handler that sends the incoming request, the client IP and the device token.

Transport and TLS

The client never follows redirects. The default transport verifies TLS, and a custom one must too. Never log credentials or raw authenticated requests.

Go SDK errors

Failed calls return an error. Use errors.As with *abusezero.Error to read its fields.

FieldDescription
CodeThe error code, such as CURSOR_INVALID.
MessageWhat to do next, written for a developer.
StatusThe HTTP status. Errors the SDK raises before sending use 422, or 403 for OAUTH_REQUIRED. INVALID_RESPONSE uses 502, and 0 means no response arrived.
RequestIDThe X-Request-ID of the failed request, when there is one. Include it when you contact support.
Retryabletrue when the same call, with the same idempotency key, can succeed.
DocsURLThe error code reference's section for this error, when AbuseZero sent one.
func CreateBenefit(ctx context.Context, client *abusezero.Client, input abusezero.BenefitsCreateInput) error {
	_, err := client.CreateBenefit(ctx, input, &abusezero.CallOptions{IdempotencyKey: "benefit:" + input.Key})
	var apiError *abusezero.Error
	if errors.As(err, &apiError) && apiError.Retryable {
		// Retry later with the same idempotency key.
	}
	return err
}

A canceled context returns context.Canceled, and VerifyWebhook returns a plain error. REST API error codes are listed in REST API errors, and how to fix the common ones in Troubleshooting. The SDK adds these, raised before a request is sent or when a response can't be used:

CodeMeaning
CREDENTIAL_REQUIREDPass exactly one of Key and AccessToken.
INVALID_KEYUse a secret key (sk_…) or restricted key (rk_…).
INVALID_TOKENPass the OAuth access token exactly as issued.
WORKSPACE_REQUIREDSet Workspace with an OAuth access token.
INVALID_WORKSPACEUse the workspace's ID.
OUTAGE_BEHAVIOR_REQUIREDSet Outage to "throw", "allow" or "deny".
INVALID_URLUse an HTTPS origin for BaseURL, or HTTP on loopback for local testing.
OAUTH_REQUIREDThis operation needs an OAuth access token.
INVALID_IDEMPOTENCY_KEYPass an idempotency key of 1 to 128 printable characters with no spaces. Mutations require one.
INVALID_PATHPass the operation's path fields in CallOptions.Path.
INVALID_REQUESTThe input doesn't match the API contract.
INVALID_PHONENormalize the phone number to E.164 before hashing it.
INVALID_IDENTIFIERUse a lowercase identifier key that starts with a letter, and a non-empty value.
INVALID_KEY_VERSIONUse a printable key version with no spaces.
DEADLINE_EXCEEDEDThe request budget ran out. Retry with the same idempotency key.
TRANSPORT_ERRORAbuseZero couldn't be reached, or the response didn't arrive complete. Retry with the same idempotency key.
INVALID_RESPONSEAbuseZero's response couldn't be used. Retry with the same idempotency key before acting on the claim.
HTTP_ERRORAbuseZero answered with an HTTP error or a redirect that has no error code. Check Status.

How is this guide?

Last updated on