Python SDK reference

The revokegpt package is the RevokeGPT server SDK for Python 3.9 or later. It sends a response token to siteverify and applies every relying-party check: success must be true, the hostname (or app) and the action must match exactly, and the score must meet your threshold. It also wraps assessments, account protection, password and credential pair checks, payments and erase. One runtime dependency: httpx. For a walkthrough, see the Python quickstart.

Install

Not published yet

The revokegpt Python package is not on its registry yet, so install it from a checkout of the repository as in the quickstart. After the first release the registry command applies.

pip install ./sdks/python               # from a checkout, until the first release
pip install "./sdks/python[pair]"       # plus the credential pair check
pip install revokegpt                   # after the first release

Exports

Client, AsyncClient, ExpectedApp, VerifyOutcome, SiteverifyResult, RevokeGPTError, RevokeGPTUnavailable, card_fields, Assessment, PasswordCheckResult, CredentialPairResult, and the request and response dataclasses (UserInfo, UserId, AccountVerification, AccountVerificationEndpoint, TransactionData, TransactionEvent, TransactionItem, TransactionUser, Address, GatewayInfo, TokenProperties, RiskAnalysis, and others). __version__ is also exported.

Options

Client(secret, endpoint, *, timeout_ms=5000, http_client=None)
AsyncClient(secret, endpoint, *, timeout_ms=5000, http_client=None)

Option	Type	Default	Meaning
secret	str	required	Your site’s secret key (rgsk_...). A management key (rgmk_...) is refused with ValueError.
endpoint	str	required	The full siteverify URL. https:, or http: only on localhost or 127.0.0.1; no username, password, query or fragment. Must end in /siteverify for the assessment and password calls.
timeout_ms	int	5000	1 to 60000. A total deadline for one call, from connecting to the last body byte. Nothing is retried.
http_client	httpx.Client (httpx.AsyncClient for AsyncClient)	created by the SDK	Your own client, for a proxy or custom CA. The SDK never closes it.

Both clients are context managers (with or async with); close() and await aclose() close the httpx client the SDK created.

Methods

Every method below exists on Client. On AsyncClient it is a coroutine (await client.verify(...)).

verify

verify(token, *, expected_hostname=None, expected_app=None, expected_action=None,
       min_score=None, remoteip=None, sitekey=None) -> VerifyOutcome

Parameter	Meaning
expected_hostname	Canonical: lowercase, no trailing dot, no port.
expected_app	ExpectedApp("android" | "ios", id), for tokens from the mobile SDKs.
expected_action	Omit only if you use no actions; then a token that carries an action is refused.
min_score	A number in [0, 1]. Always pass it, or the outcome is threshold-missing.
remoteip, sitekey	Sent only when given and not empty; a given value is checked first.

Give exactly one of expected_hostname and expected_app. Returns VerifyOutcome(ok, reason, result): reason is None when ok is true, and result is a SiteverifyResult (verified, score, action, hostname, error_codes, reasons, apk_package_name, ios_bundle_id). Gate on outcome.ok alone.

import os
from revokegpt import Client

client = Client(os.environ["REVOKEGPT_SECRET"], "https://<api host>/v1/siteverify")

outcome = client.verify(
    token,
    expected_hostname="shop.example",
    expected_action="signup",
    min_score=0.5,
    remoteip=client_ip,
)
if not outcome.ok:
    ...  # refuse; outcome.reason says why

create_assessment

create_assessment(*, token=None, expected_action=None, express=False, user_ip_address=None,
                  user_agent=None, headers=None, user_info=None, account_verification=None,
                  transaction_data=None, fraud_prevention=None) -> Assessment

Scores a token (or, with express=True, an IP address alone). An invalid token is still a 200 with token_properties.valid == False and score 0, so check valid. Assessment.raw holds every field of the answer.

annotate

annotate(name_or_aid, *, annotation=None, reasons=None, account_id=None,
         hashed_account_id=None, transaction_event=None) -> None

Reports what happened after an assessment. annotation is LEGITIMATE or FRAUDULENT. A call with nothing to report is sent and the service refuses it (bad-request).

erase_account

erase_account(*, account_id=None, hashed_account_id=None) -> None

Pass exactly one, in the same form you used when you assessed the account.

is_password_leaked

is_password_leaked(password) -> PasswordCheckResult   # leaked, count

Hashes with SHA-1 locally and sends only the first 5 hex characters. A RevokeGPTError means the password was not checked: never read it as “not leaked”. See password check.

check_credential_pair

check_credential_pair(username, password) -> CredentialPairResult   # leaked

Beta. Needs the pair extra (rbcl 1.1.2); without it the call raises RevokeGPTError('feature-unavailable', 0) and sends nothing. While the beta is off the service answers feature-disabled (403). A username with an unassigned Unicode code point raises ValueError with no request.

card_fields

card_fields(*, bin=None, last4=None) -> dict[str, str]

Builds the only card fields a payment assessment accepts. Raises RevokeGPTError('bad-request', 0) for anything else. Pass the result into TransactionData(**card_fields(bin="424242", last4="4242"), currency_code="USD", value=59.9).

Errors and failure model

verify never raises: every failure is an outcome. reason is one of invalid-expectation, invalid-options, invalid-token-format, network-error, http-error, not-verified, hostname-mismatch, app-mismatch, action-mismatch, score-missing, threshold-missing, score-below-threshold, score-invalid. Treat every reason as “do not accept”. A token is single use: after network-error or http-error it may already be spent, so a retry needs a new token. The full list is in errors.

A bad argument raises TypeError or ValueError before any request (the message never shows the value). Other calls raise RevokeGPTError:

Field	Meaning
code	For example unauthorized, feature-disabled, not-found, expired, rate-limited, bad-request, payload-too-large, unsupported-media-type, service-unavailable, network-error, invalid-response, feature-unavailable. Treat the set as open.
status	The HTTP status; 0 when nothing was answered or no request was made.
request_id	The service’s request id, when sent.
retry_after_seconds	Set for a 429 that carried Retry-After.

RevokeGPTUnavailable is the subclass for HTTP 503: “could not check”, never “clean”.

Configuration

The SDK reads no environment variables. The client it creates ignores HTTP_PROXY, SSL_CERT_FILE and the other environment settings (trust_env=False), so the environment cannot redirect the secret. To use a proxy or custom CA, pass your own httpx.Client as http_client; the SDK sends each request without redirects and without that client’s auth. AsyncClient is asyncio only; do not share one between event loops.

Security notes

• The secret goes only in the POST body (siteverify) or the Authorization header, never in a URL, an exception, a log line, repr() or a pickle.
• Behind a proxy, pass the real end-user address as remoteip, taken from your trusted proxy and never from a header an end user can set.
• No retries, redirects are never followed, and at most 64 KiB of a JSON answer is read.
• Never choose between the hostname and the app expectation from anything the client controls.