Modes and thresholds

A site has one mode, set by you in the dashboard. A page cannot ask for another one: the challenge request has no mode field, and the server reads the mode from the site’s configuration.

When to use which mode

Mode	What the visitor sees	Use it for
score	Nothing. The token is issued whatever the score; your server decides.	Login, signup, checkout, reCAPTCHA v3 and Enterprise score integrations
invisible	Nothing, unless the score is below the site’s puzzleThreshold: then a puzzle in a modal overlay.	reCAPTCHA v2 invisible integrations
checkbox	An explicit “I am not a robot” control; a puzzle if the score is below puzzleThreshold.	reCAPTCHA v2 checkbox integrations

If you are not sure, start with score. It never interrupts a person, and you choose per action what to do with a low score (allow, ask for email confirmation, block). Pick invisible or checkbox when you want RevokeGPT to ask a suspicious visitor to solve a puzzle for you.

How it works

1. The widget (or mobile SDK) asks for a challenge, solves a small proof of work and sends browser signals.
2. The service scores the visit. The score is from 0.0 (bot) to 1.0 (human), in steps of 0.1.
3. Depending on the mode and puzzleThreshold, the visitor gets a response token straight away or has to solve a puzzle first.
4. Your server sends the token to siteverify and applies its own threshold (see siteverify).

• A score site never shows a puzzle. A mobile app never shows a puzzle either.
• puzzleThreshold is from 0 to 1 in steps of 0.1 and defaults to 0.3.
• A site can set a supportUrl (an https page). It is shown after a first failed puzzle group.

Set it up

1. In the dashboard, open your site, choose the mode and (for invisible and checkbox) the puzzle threshold.
2. Add the client for your platform from the quickstarts.
3. On your server, pass minScore (and expectedAction, expectedHostname) when you verify.

const outcome = await revokegpt.verify(token, {
  expectedHostname: 'shop.example',
  expectedAction: 'signup',
  minScore: 0.5,
});
if (!outcome.ok) return reject(outcome.reason);

The threshold is yours

The edge issues a token whatever the score. Your server applies the threshold, so it can differ per action: strict for checkout, relaxed for a newsletter form. Pass it as minScore to the SDK.

Where	Starting value
Web token	0.5
Mobile app token	0.6 or higher (0.5 is the cap for an app token with no attestation evidence)
Low-risk form	0.3
Payment or account takeover target	0.7

A token that was earned by passing a puzzle keeps the honest score of the solve that led to it, which is always below puzzleThreshold. With the default of 0.3 that is 0.2 or lower, with success: true. On checkbox and invisible sites rely on success; read the score on score sites.

Errors

You see	Meaning	What to do
score-below-threshold (SDK)	The score is below your minScore.	Block, or ask for more proof (email code, account protection).
timeout-or-duplicate	The token is older than 300 seconds or already used.	Ask the widget for a new token.
site-disabled	The site is switched off in the dashboard.	Switch it on, or use another key.

Limits and security notes

• A token lives 300 seconds and verifies once.
• Never decide the threshold on the client. A client can skip your page code, but it cannot make the server accept a low score.
• See scores and reason codes for what to log.