reCAPTCHA Bot Protection

Before You Begin

You will need:

• A Google account with access to google.com/recaptcha/admin
• A publicly accessible production domain for your Tymeslot instance (e.g., tymeslot.yourdomain.com). reCAPTCHA tokens are bound to a domain and do not work on localhost
• Access to your Tymeslot instance's environment variables

By the end of this guide, invisible reCAPTCHA v3 checks every submission to your signup and booking forms and rejects likely bots.

Should You Enable reCAPTCHA?

Turn reCAPTCHA on if you see either of the following:

You can skip reCAPTCHA on a small or private deployment where you share your scheduling link only with people you know and registration is closed.

1 Create a reCAPTCHA Site

1. Go to google.com/recaptcha/admin and click the [+] button in the top-right corner to create a new site.
2. Set Label to something identifiable, such as Tymeslot Production.
3. Under reCAPTCHA type, select [Score based (v3)]. Do not select v2: it shows users a checkbox challenge, and Tymeslot does not support it.
4. Under Domains, add your production domain exactly as it appears in the browser address bar, for example tymeslot.yourdomain.com. Do not include https:// or a trailing slash.
5. Accept the terms of service and click [Submit].
6. You are shown a [Site Key] and a [Secret Key]. Copy both for the next step. The site key is public and embedded in your pages; the secret key is private and stays on your server.

2 Configure Environment Variables

Add the following environment variables to your Tymeslot instance, then restart it. Both minimum scores default to 0.3 and the actions default to the values shown, so you can leave those lines out unless you want different values. Each of these lines you set fixes that setting, and the admin panel's Authentication tab shows it greyed out. Leave a line out to switch that check, or change that score, from the Authentication tab with no restart.

# reCAPTCHA v3 keys from google.com/recaptcha/admin
RECAPTCHA_SITE_KEY=6Le...your-site-key
RECAPTCHA_SECRET_KEY=6Le...your-secret-key

# Accepted hostname — only tokens generated on this domain are accepted.
# Prevents token replay attacks (see explanation below).
RECAPTCHA_EXPECTED_HOSTNAMES=tymeslot.yourdomain.com

# Protect the signup form
RECAPTCHA_SIGNUP_ENABLED=true
RECAPTCHA_SIGNUP_MIN_SCORE=0.5
RECAPTCHA_SIGNUP_ACTION=signup_form

# Protect the booking form
RECAPTCHA_BOOKING_ENABLED=true
RECAPTCHA_BOOKING_MIN_SCORE=0.3
RECAPTCHA_BOOKING_ACTION=booking_form

Score Thresholds

Google scores each interaction from 0.0 to 1.0, and Tymeslot blocks submissions that score below your minimum. Use this scale as a guide:

Why different thresholds for signup and booking? People often reach a booking form straight from a scheduling link someone sent them. They are real, but Google may score them lower because they have no history with your site, so a lower minimum (0.3) avoids turning them away. Signup forms attract more determined bots and can use a higher minimum (0.5): a false positive only means the person tries again.

Development Environment

reCAPTCHA stays off unless you set its enabled flags and both keys, so leave the variables out of your local .env file and every form accepts submissions as normal. If you do set them locally, Google rejects tokens from localhost unless you add it to your site's domains.

Monitoring Score Distributions

Once reCAPTCHA is live, use Google's admin console to see how your real visitors score and decide whether to adjust your minimum scores:

1. Go to google.com/recaptcha/admin and select your site.
2. Click the [Analytics] tab.
3. Review the score distribution. If most of your traffic scores above 0.7, your minimums are well set. If many submissions cluster just around your minimum, check whether real users are being blocked.

Troubleshooting

❓ Frequently Asked Questions

Verification Checklist

• reCAPTCHA site created in Google admin console with type Score based (v3)
• Your production domain is listed under Domains in the Google console (no https:// prefix)
• Both RECAPTCHA_SITE_KEY and RECAPTCHA_SECRET_KEY are set in environment variables
• RECAPTCHA_EXPECTED_HOSTNAMES is set to your exact production domain
• Tymeslot restarted after environment variable changes
• A real booking was submitted from a browser in staging and the score appeared in the reCAPTCHA [Analytics] tab
• The booking went through (so the minimum score is not too strict)