Quick start

This guide adds HumanPass to an HTML form and verifies the response with the official server SDK.

1. Create a HumanPass site

Select Create site.
Enter a name and choose Test while developing locally.
Add your exact domain. Use localhost only with a test site.
Copy the secret key immediately. It is shown only once.

You will receive:

a public sitekey for browser code;
a private secret key for your backend.

Load an immutable widget version and place the component inside your form:

<script
  src="https://humanpass.valgix.com/widget/0.1.0/humanpass.min.js"
  defer
></script>

<form method="post" action="/signup">
  <input name="email" type="email" required />

  <humanpass-widget
    data-humanpass-sitekey="hp_site_test_REPLACE_ME"
    data-humanpass-action="signup"
    required
  ></humanpass-widget>

  <button type="submit">Create account</button>
</form>

The widget adds a hidden humanpass-token field to the form. The configured mode comes from the Valgix dashboard; browser markup cannot override it.

3. Install the server SDK

npm install @valgix/humanpass

The package supports Node.js 20 or later and Bun.

4. Configure your backend

Store the secret in a server-only environment variable:

HUMANPASS_SECRET_KEY=hp_secret_test_REPLACE_ME

Never prefix this variable with NEXT_PUBLIC_, PUBLIC_, or another framework convention that exposes it to browsers.

5. Verify every submitted response

import { HumanPass } from "@valgix/humanpass";

const humanpass = new HumanPass({
  baseUrl: "https://humanpass.valgix.com",
  secret: process.env.HUMANPASS_SECRET_KEY!,
});

const result = await humanpass.verify({
  response: formData.get("humanpass-token")?.toString() ?? "",
  expectedAction: "signup",
  expectedHostname: "app.example.com",
});

if (!result.success) {
  return new Response("Human verification failed", { status: 400 });
}

// Continue the protected signup only after successful verification.

Response tokens are short-lived and single-use. Verify immediately before the operation you want to protect.

6. Move to live

Before production:

Create a live site or live credentials.
Add every production hostname you use.
Replace the test sitekey and secret with their live equivalents.
Confirm your backend expects the production hostname and action.
Exercise both successful and rejected requests.

Test and live credentials cannot be mixed.