Allowed Domains

How domain allowlists work, local development setup, and common mismatch troubleshooting.

Updated 2/22/2026

Allowed Domains

NeoCaptcha validates where widgets are allowed to run.

Why this matters

Allowed domains prevent unauthorized third parties from embedding your widget and abusing your site configuration.

Configuration guidelines

Local development

There is a toggle in the captcha creation form that allows you to toggle "localhost" on or off. If this is on, it can be tested locally.

Production

Add exact hostnames for each environment:

• app.example.com
• checkout.example.com
• admin.example.com

If your platform uses preview URLs, either:

• add the preview domain pattern if supported, or
• route preview testing through a fixed staging hostname.

Troubleshooting origin mismatch

Symptoms:

• Widget fails to load or always fails verification.
• Verify endpoint returns origin/hostname mismatch errors.

Checklist:

1. Confirm browser origin exactly matches configured allowed domain.
2. Confirm protocol and host are what your app actually serves.
3. Verify token was created on same site key/site pair as verification call.
4. Ensure frontend and backend use keys from same NeoCaptcha project/site.