Node.js 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. It produces the token that this page verifies.

3. Verify the token on your server

Not published yet

@revokegpt/node 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.

npm install @revokegpt/node     # after the first release; Node.js 26 or later

verify never throws: every failure is an outcome. Gate on outcome.ok alone. It checks that success is the boolean true, the hostname and action match exactly, and the score meets minScore. minScore is required: without it every verification fails with threshold-missing. Behind a proxy, pass the client address from your trusted proxy as remoteip, not req.socket.remoteAddress.

verify.ts

import { createClient } from '@revokegpt/node';

// Create the client once, at start-up.
const revokegpt = createClient({
  secret: process.env.REVOKEGPT_SECRET ?? '', // rgsk_..., never in client code
  endpoint: 'https://api.revokegpt.com/v1/siteverify',
});

export async function allowSignup(token: string, clientIp: string): Promise<boolean> {
  const outcome = await revokegpt.verify(token, {
    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
  });
  if (!outcome.ok) {
    console.warn('revokegpt refused', outcome.reason, outcome.result.errorCodes);
    return false;
  }
  console.info('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).