Java 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

cd sdks/java && mvn install     # from a checkout, until the first release

<dependency>
  <groupId>com.revokegpt</groupId>
  <artifactId>revokegpt</artifactId>
  <version>0.1.0</version>
</dependency>

No runtime dependencies (it uses java.net.http). The client is immutable and thread safe: create it once. verify never throws: gate on outcome.ok(). In a Spring MVC controller, call SignupCheck.allowSignup(token, request.getRemoteAddr()) (or read the address from your trusted proxy). For the Spring servlet filter see Spring.

import com.revokegpt.RevokeGPT;
import com.revokegpt.VerifyOptions;
import com.revokegpt.VerifyOutcome;

public final class SignupCheck {
    // Create the client once and share it (it is immutable and thread safe).
    private static final RevokeGPT REVOKEGPT = RevokeGPT.builder()
            .secret(System.getenv("REVOKEGPT_SECRET")) // rgsk_..., never in client code
            .endpoint("https://api.revokegpt.com/v1/siteverify")
            .build();

    public static boolean allowSignup(String token, String clientIp) {
        VerifyOutcome outcome = REVOKEGPT.verify(token, VerifyOptions.builder()
                .expectedHostname("shop.example") // the hostname your page is served from, lowercase
                .expectedAction("signup")          // the action your page passed to the widget
                .minScore(0.5)                     // required: a start, tune it later
                .remoteip(clientIp)                // the end user's address from your trusted proxy
                .build());
        if (!outcome.ok()) {
            System.err.println("revokegpt refused: " + outcome.reason() + " " + outcome.result().errorCodes());
            return false;
        }
        System.out.println("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).