CAPTCHA for developers

When a site has CAPTCHA enabled, every submission to /api/v1/submissions must carry a valid token or Expeed Relay rejects it. Your job is to render the widget, get a token, and put it in captchaToken.

Which provider is in use is a per-site setting your admin controls — see CAPTCHA setup. Ask them for the provider type and the site key. The secret key stays on the server and you never see it.

Supported providers

Expeed Relay implements exactly three:

Provider type	What it is	Visitor sees
recaptcha-v2	Google reCAPTCHA v2	An “I’m not a robot” checkbox
recaptcha-v3	Google reCAPTCHA v3	Nothing — scored invisibly
turnstile	Cloudflare Turnstile	Usually nothing

v2 and v3 keys are not interchangeable

Google issues a different key pair per version, and it is Google — not Expeed Relay — that rejects a mismatched pair. Expeed Relay cannot tell which version a key belongs to, so the failure surfaces as a generic 400 CAPTCHA verification failed rather than a configuration error. Confirm with your admin which version the site is registered for.

reCAPTCHA v2 (checkbox)

<script src="https://www.google.com/recaptcha/api.js" async defer></script>

<form id="contact-form">
  <input name="email" type="email" required />
  <div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
  <button type="submit">Send</button>
</form>

<script>
  document.getElementById('contact-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    const token = grecaptcha.getResponse();

    if (!token) {
      // The visitor hasn't completed the checkbox yet.
      return;
    }

    await fetch('https://api.relay.expeed.com/api/v1/submissions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        siteKey: 'marketing-site-a',
        formKey: 'contact-us',
        captchaToken: token,
        data: Object.fromEntries(new FormData(e.currentTarget)),
      }),
    });

    grecaptcha.reset(); // tokens are single-use
  });
</script>

reCAPTCHA v3 (invisible)

v3 never blocks the visitor. It returns a score, and Expeed Relay rejects anything below the threshold.

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>

<script>
  document.getElementById('contact-form').addEventListener('submit', async (e) => {
    e.preventDefault();

    const token = await grecaptcha.execute('YOUR_SITE_KEY', { action: 'submit' });

    await fetch('https://api.relay.expeed.com/api/v1/submissions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        siteKey: 'marketing-site-a',
        formKey: 'contact-us',
        captchaToken: token,
        data: Object.fromEntries(new FormData(e.currentTarget)),
      }),
    });
  });
</script>

The v3 score threshold is server-wide

Expeed Relay rejects scores below 0.5 by default. That threshold is a server setting (RECAPTCHA_MIN_SCORE) your administrator can change — it is not per-site, so raising it affects every site using v3.

Real visitors on corporate VPNs and privacy browsers can score low. If genuine traffic is being rejected, the fix is usually switching that site to v2 or Turnstile, both of which give the visitor a way to prove themselves.

Cloudflare Turnstile

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<form id="contact-form">
  <input name="email" type="email" required />
  <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
  <button type="submit">Send</button>
</form>

<script>
  document.getElementById('contact-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    const token = turnstile.getResponse();

    await fetch('https://api.relay.expeed.com/api/v1/submissions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        siteKey: 'marketing-site-a',
        formKey: 'contact-us',
        captchaToken: token,
        data: Object.fromEntries(new FormData(e.currentTarget)),
      }),
    });

    turnstile.reset();
  });
</script>

Tokens are single-use and short-lived

Every provider issues a token that verifies once. Reusing one — for instance retrying a failed request with the same token — fails with 400 CAPTCHA verification failed. Call grecaptcha.reset() or turnstile.reset() and get a fresh token before retrying.

Tokens also expire (about two minutes for reCAPTCHA). A visitor who solves a checkbox and then spends five minutes writing their message will submit an expired token. Fetch the token at submit time, not on page load.

The hostname is cross-checked

Expeed Relay compares the hostname the provider reports against the hostnames in your site’s Allowed origins. A token solved on a domain not in that list is rejected even though the provider considered it valid.

This bites when a form moves to a new domain, or when a staging domain is registered with the CAPTCHA provider but not with Expeed Relay. Both lists need the domain.

Content Security Policy

CAPTCHA scripts and frames need explicit entries. Combine with the connect-src from frontend integration.

reCAPTCHA v2 and v3:

script-src  'self' https://www.google.com https://www.gstatic.com;
frame-src   https://www.google.com;
connect-src 'self' https://api.relay.expeed.com;

Turnstile:

script-src  'self' https://challenges.cloudflare.com;
frame-src   https://challenges.cloudflare.com;
connect-src 'self' https://api.relay.expeed.com;

A blocked script means the widget never renders and grecaptcha or turnstile is undefined. The browser console names the violated directive.

Why there's no integrity hash on these scripts

Subresource Integrity is normally right for a third-party script, and a security review will ask about it. Neither provider supports it here: both loaders are mutable by design — Google’s api.js and Cloudflare’s api.js change content to ship new challenge logic — so a pinned integrity hash breaks the widget the next time they deploy.

The mitigation is the CSP above, which restricts loading to those two origins.

Provider test keys

Both providers publish keys that always pass, for local development. They are the providers’ test keys, not Expeed Relay’s, and your admin has to store the matching secret against the site for them to work end to end.

reCAPTCHA v2 — always passes:

site key:   6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
secret key: 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

Turnstile — always passes:

site key:   1x00000000000000000000AA
secret key: 1x0000000000000000000000000000000AA

Turnstile also publishes 2x00000000000000000000AB (always blocks) and 3x00000000000000000000FF (forces an interactive challenge), which are useful for testing your failure path.

Never ship test keys

They pass for everyone, including bots. Confirm the live site uses real keys before launch.

Errors you will actually see

Status	Message	What it means
400	CAPTCHA token is required for this site	The site has CAPTCHA on and you sent no captchaToken
400	CAPTCHA verification failed	Token invalid, expired, already used, key pair mismatched, v3 score too low, or hostname not allowed
503	CAPTCHA is misconfigured for this site	A provider is selected but no secret is stored — an admin fix, not yours
503	CAPTCHA verification temporarily unavailable. Please try again.	Expeed Relay could not reach Google or Cloudflare. Usually transient; safe to retry with a fresh token

Misconfiguration fails closed, on purpose

If a site names a provider but has no secret stored, Expeed Relay refuses every submission rather than skipping verification. Skipping would be worse: the widget still renders, the visitor still solves it, and no token is ever checked — so every bot passes with nothing in the logs to show it.

Checking whether a site needs CAPTCHA

If you don’t know, send a submission without captchaToken. If the site requires one you’ll get 400 CAPTCHA token is required for this site; if it doesn’t, the submission succeeds.

Related

• CAPTCHA setup — the admin side: choosing a provider and storing keys
• Frontend integration — the submission call itself
• API reference — every field and every error