Python quickstart

1. Create a site

In the dashboard, create a site and add the hostnames it will run on. Copy the site key (rgpk_..., public) and the secret key (rgsk_..., shown once, server only). Choose the mode: invisible, checkbox or score (modes and thresholds).

2. Add the client

Add a client first: JavaScript, React or Vue.

3. Verify the token on your server

Not published yet

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

pip install ./sdks/python      # from a checkout, until the first release
pip install revokegpt          # after the first release

One runtime dependency (httpx). AsyncClient is the same API for asyncio. verify never raises: gate on outcome.ok. Behind a proxy, take remoteip from your trusted proxy (for FastAPI, run uvicorn with --forwarded-allow-ips set to your proxy so request.client is the client). For Django, Flask and FastAPI firewall middleware see Django, Flask and FastAPI.

verify.py

import os

from revokegpt import Client

# Create the client once. The secret (rgsk_...) never appears in repr(), pickling or an error.
client = Client(os.environ["REVOKEGPT_SECRET"], "https://api.revokegpt.com/v1/siteverify")


def allow_signup(token: str, client_ip: str) -> bool:
    outcome = client.verify(
        token,
        expected_hostname="shop.example",  # the hostname your page is served from, lowercase
        expected_action="signup",  # the action your page passed to the widget
        min_score=0.5,  # required: a start, tune it later
        remoteip=client_ip,  # the end user's address from your trusted proxy
    )
    if not outcome.ok:
        print("revokegpt refused", outcome.reason, outcome.result.error_codes)
        return False
    print("revokegpt score", outcome.result.score, outcome.result.reasons)
    return True

4. Read the score and the reasons

siteverify returns success, a score from 0.0 (bot) to 1.0 (human) in steps of 0.1, the action and hostname (or app) the token was issued for, and reasons, a list such as AUTOMATION or DATACENTER_IP. Always check success, the action and the hostname, then compare the score with a threshold you choose. 0.5 is a sensible start. See scores and reason codes and modes and thresholds.

5. Go live

• The secret key is in your server’s secret store, not in source control, a page or an app.
• The server checks success, the expected action, the expected hostname (or app) and a minScore.
• A refused or failed verification blocks the action. Treat every failure as “do not accept”.
• The token is sent over HTTPS and used once; a retry needs a new token.
• Your site’s allowed domains (or apps) in the dashboard list the real production hostnames.
• Your Content Security Policy allows the widget origin if you have one (see session tokens and cookies).