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 domain-bound and do not work on localhost
• Access to your Tymeslot instance's environment variables

By the end of this guide, your signup and booking forms will be protected against bot submissions with invisible reCAPTCHA v3.

Should You Enable reCAPTCHA?

Enable reCAPTCHA if you are experiencing any of the following:

• Bot registrations — a surge of accounts with random email patterns (e.g., xk3m9@mailinator.com)
• Spam bookings — meetings booked with fake names or throwaway email addresses
• Credential stuffing — repeated failed login attempts against your users' accounts

You can safely skip reCAPTCHA for small or private deployments where your scheduling link is shared only with known contacts. There is no security benefit in adding friction to a closed deployment.

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 presents a checkbox challenge to users and is not what Tymeslot integrates with.
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 — you will need them in the next step. The site key is embedded in your pages (public); the secret key stays server-side (private).

2 Configure Environment Variables

Add the following environment variables to your Tymeslot instance. Restart the application after making changes.

# 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. Tymeslot blocks submissions whose score falls below your configured minimum. Use this table as a reference:

Why different thresholds for signup and booking? Booking forms are often the first touch point for people who just received a scheduling link from a colleague — they are real humans, but Google may score them lower because they have no prior interaction history with your site. A more permissive threshold (0.3) prevents blocking these legitimate users. Signup forms attract more determined bots and can safely use a higher threshold (0.5) — a false positive just means the user tries again.

Development Environment

reCAPTCHA is automatically disabled in the development environment regardless of how your environment variables are set. You do not need to add any variables to your local .env file, and no code changes are required for local testing. All forms accept submissions normally in dev.

Monitoring Score Distributions

Once reCAPTCHA is live, use the admin console to understand how your real users are scoring and decide whether your thresholds need adjusting:

1. Go to google.com/recaptcha/admin and select your site.
2. Click the [Analytics] tab.
3. Review the score distribution histogram. If the bulk of your traffic is scoring above 0.7, your thresholds are well-calibrated. If you see a large cluster near your threshold boundary, consider whether those users are being incorrectly 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 successfully (confirming the threshold is not too aggressive)