Getting started

Quick start

Protect a form with ProofVal in four steps: create a site, drop the widget into your form, verify the token on your server, and test it. Most integrations take under ten minutes.

How it fits together. The widget runs a proof-of-work in the visitor's browser and places a one-time token into your form. Your backend exchanges that token for a yes/no answer before accepting the submission. Nothing is stored about the visitor and no cookies are set.

1 Create a site

Sign in to the dashboard and create a site. Each site gets two keys:

KeyWhere it goesVisibility
Site key The site-key attribute on the widget Public. Safe to put in HTML.
Secret key The X-Secret-Key header when your server calls /v1/verify Private. Keep it in server configuration, never in the browser.

A site represents one domain or project, and how many you can create depends on your plan. Existing sites keep working if your plan changes; you only lose the ability to add more.

PlanSitesVerifications per month
Free15
Starter11,000
Basic55,000
GrowthUnlimited50,000

While you are there, add the origins your form will be served from (for example https://example.com). Until at least one origin is added the widget is accepted from any domain, which is fine for a first test but should be locked down before going live.

2 Add the widget to your form

Load the script once per page and place the <proofval-widget> element anywhere inside the <form> you want to protect.

HTML
<!-- Load once per page -->
<script src="https://www.proofval.com/v1/widget.js" async></script>

<form method="post" action="/contact">
    <input type="text" name="name" placeholder="Your name">
    <input type="email" name="email" placeholder="Your email">
    <textarea name="message"></textarea>

    <!-- Place inside the form -->
    <proofval-widget site-key="YOUR_SITE_KEY"></proofval-widget>

    <button type="submit">Send</button>
</form>

The widget renders a small "Click to verify" box. When the visitor clicks it, the browser solves the challenge in a background Web Worker and the widget adds a hidden input named proofval-token to the form. It also blocks the submit until that has happened, so an unverified visitor sees "Please verify first" instead of a failed request.

3 Verify the token on your server

On submit, read proofval-token from the request body and send it to POST https://www.proofval.com/v1/verify with your secret key. Only accept the submission when the response contains "success": true.

PHP
<?php
$token = $_POST['proofval-token'] ?? '';

$ch = curl_init('https://www.proofval.com/v1/verify');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Secret-Key: ' . getenv('PROOFVAL_SECRET_KEY'),
    ],
    CURLOPT_POSTFIELDS     => json_encode(['token' => $token]),
]);
$body = json_decode((string) curl_exec($ch), true);
curl_close($ch);

if (($body['success'] ?? false) !== true) {
    http_response_code(400);
    exit('Please complete the verification step.');
}

// Verified — handle the submission.
Fail closed. Treat a missing token, a network error, or any response other than "success": true as a failed verification. Each token works exactly once and expires 15 minutes after it is issued.

4 Test it

  1. Open your form, click the widget and wait for the green "Verified" state. This normally takes well under a second.
  2. Submit the form. Your server should receive proofval-token and get "success": true back.
  3. Submit the same form again without clicking the widget. The widget should block it with "Please verify first".
  4. Open the site in the dashboard. The integration health badge turns green once verified submissions arrive, and the monthly counter starts moving.

Next steps