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.
1 Create a site
Sign in to the dashboard and create a site. Each site gets two keys:
| Key | Where it goes | Visibility |
|---|---|---|
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.
| Plan | Sites | Verifications per month |
|---|---|---|
| Free | 1 | 5 |
| Starter | 1 | 1,000 |
| Basic | 5 | 5,000 |
| Growth | Unlimited | 50,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.
<!-- 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
$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.
app.post('/contact', async (req, res) => {
const token = req.body['proofval-token'] || '';
const response = await fetch('https://www.proofval.com/v1/verify', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Secret-Key': process.env.PROOFVAL_SECRET_KEY,
},
body: JSON.stringify({ token }),
});
const result = await response.json().catch(() => ({}));
if (result.success !== true) {
return res.status(400).send('Please complete the verification step.');
}
// Verified — handle the submission.
});
import os
import requests
def verify_proofval(token: str) -> bool:
if not token:
return False
try:
response = requests.post(
"https://www.proofval.com/v1/verify",
json={"token": token},
headers={"X-Secret-Key": os.environ["PROOFVAL_SECRET_KEY"]},
timeout=5,
)
return response.json().get("success") is True
except requests.RequestException:
return False # fail closed
# In your view / handler:
# if not verify_proofval(request.form.get("proofval-token", "")):
# abort(400, "Please complete the verification step.")
curl -X POST https://www.proofval.com/v1/verify \
-H "Content-Type: application/json" \
-H "X-Secret-Key: YOUR_SECRET_KEY" \
-d '{"token": "TOKEN_FROM_FORM"}'
"success": true as a failed verification. Each token works exactly once and expires
15 minutes after it is issued.
4 Test it
- Open your form, click the widget and wait for the green "Verified" state. This normally takes well under a second.
- Submit the form. Your server should receive
proofval-tokenand get"success": trueback. - Submit the same form again without clicking the widget. The widget should block it with "Please verify first".
- Open the site in the dashboard. The integration health badge turns green once verified submissions arrive, and the monthly counter starts moving.
Next steps
- Widget reference — attributes, events, theming and the JavaScript API for fetch-based forms.
- Server verification — the full request and response contract, error codes and rate limits.
- Lock down your origins in the dashboard so the widget only works on your domains.