Get Started with Faable Challenge
Three steps: create a site, add the widget to your form, and verify the token on your server before you act on the submission.
1. Create a site
- Open the Faable Dashboard and pick Challenge in the product menu.
- Create a site. Give it a name (
Contact form) and the domains your form lives on — up to 10 per site. A domain covers its subdomains too:example.comalso allowswww.example.comandshop.example.com. Paste a URL if that is easier; only the hostname is kept. - Copy the two keys:
- the site key (
fcs_pk_…) is public and goes in your page; - the secret key (
fcs_sk_…) stays on your server. It is shown once — Faable keeps only a hash of it. If you lose it, rotate it from the site’s page.
- the site key (
The widget only works on the site’s domains. To try it on your machine, add localhost to the list while you develop.
How many sites a project can have depends on its plan — see Pricing.
2. Add the widget to your form
Put an element with the class faable-challenge and your site key inside the form, and load the script once per page:
<form action="/contact" method="post">
<input name="email" type="email" required />
<textarea name="message" required></textarea>
<div class="faable-challenge" data-sitekey="fcs_pk_…"></div>
<button>Send</button>
</form>
<script src="https://challenge.faable.com/v1/api.js" async defer></script>That is all the page needs:
- The widget starts solving on the first interaction with the form (a focus or a keystroke), so the token is usually ready before the person presses Send.
- If they send earlier, the submit waits for the token and goes on by itself.
- The token travels in a hidden field named
faable-challenge-response, and is renewed on its own while the form stays open.
With a bundler, install @faable/challenge instead of the script tag:
npm install @faable/challengeimport { render } from '@faable/challenge'
render(document.querySelector('#challenge')!, {
sitekey: 'fcs_pk_…',
action: 'contact'
})The Widget covers every option, single-page apps and themes.
3. Verify the token on your server
When the form arrives, send the token to POST https://challenge.faable.com/v1/verify with your secret key, and only go on if success is true:
curl -X POST https://challenge.faable.com/v1/verify \
-H 'content-type: application/json' \
-d '{"secret":"fcs_sk_…","response":"<faable-challenge-response>","remoteip":"<client IP>"}'{
"success": true,
"site_id": "…",
"project_id": "project_…",
"hostname": "www.example.com",
"action": "contact",
"challenge_ts": "2026-11-18T08:24:16.049Z",
"difficulty": 18,
"signals": [],
"remoteip_match": true,
"error-codes": [],
"receipt": "eyJhbGciOiJFUzI1NiIs…"
}In Node.js (18 or later, with the built-in fetch), for an Express handler:
import express from 'express'
const app = express()
app.use(express.urlencoded({ extended: false }))
async function verifyChallenge(token, ip) {
const res = await fetch('https://challenge.faable.com/v1/verify', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
secret: process.env.FAABLE_CHALLENGE_SECRET,
response: token,
remoteip: ip,
action: 'contact'
}),
signal: AbortSignal.timeout(5000)
})
const body = await res.json()
return body.success === true
}
app.post('/contact', async (req, res) => {
const ok = await verifyChallenge(
req.body['faable-challenge-response'],
req.ip
).catch(() => false)
if (!ok) return res.status(400).send('Could not verify the request.')
// …now send the email, store the booking, create the account
res.redirect('/thanks')
})Keep the secret in an environment variable (FAABLE_CHALLENGE_SECRET) — on Faable Deploy, as a secret of the app — never in the page or the repository.
A few things worth knowing from the start:
- One token, one verify. Verifying consumes the token. A second call with the same token answers
timeout-or-duplicate. - Five minutes. A token not verified within 5 minutes of being issued expires.
remoteipis optional and never fails the check:remoteip_matchtells you whether it is the IP that solved the challenge, for you to weigh.actionis optional. Send the label your widget used (contact) and a token from another form of yours fails withaction-mismatch.
The full reference — every field, every error code and the signed receipt — is in Verify API.
Next steps
- The Widget — themes, sizes, languages, events, and SPA usage.
- With Faable Auth — if your form creates Faable Auth users, mark them as verified.
- Pricing — what each plan includes.
Last updated on