Skip to main content

CAPTCHA and Self-Registration

Overview​

Hypervisor supports public customer self-registration protected by a CAPTCHA challenge of your choosing. Once you enable self-registration, anyone can visit your /register page, complete a CAPTCHA, submit their details, click an email-verification link, and land on their dashboard. CAPTCHA can also be applied to the /login page independently.

Three CAPTCHA providers are supported out of the box:

ProviderStyleSite / Secret Key Source
Cloudflare TurnstilePrivacy-friendly invisible / managed challengedash.cloudflare.com > Turnstile
Google reCAPTCHA v2Classic "I'm not a robot" checkboxgoogle.com/recaptcha/admin
Google reCAPTCHA v3Invisible, score-based (no user interaction)google.com/recaptcha/admin

Pick one. You cannot mix providers across different forms; the same provider protects everything that has CAPTCHA turned on.

Configuring CAPTCHA​

  1. As an admin, navigate to Settings > Security.
  2. In the CAPTCHA card:
    • Enable CAPTCHA. Master toggle. While off, every form submits without a challenge.
    • Provider. Pick Cloudflare Turnstile, reCAPTCHA v2, or reCAPTCHA v3.
    • Site key. Paste the public key the provider issued you. This is shown on the customer-facing widget.
    • Secret key. Paste the matching private key. Used server-side to validate the challenge response. Never exposed to the browser.
    • reCAPTCHA v3 threshold (only when v3 is the chosen provider). The minimum score (0.0 to 1.0) Hypervisor will accept. Submissions below the threshold are rejected with a generic "verification failed" error. Default is 0.5. Tighten toward 0.7+ if you're seeing bot traffic, loosen toward 0.3 if real users get blocked. v3 never shows a challenge, so dialing this in matters.
    • Protect Login. Apply CAPTCHA to the /login form.
    • Protect Register. Apply CAPTCHA to the /register form.
  3. Click Save.

Testing the configuration​

Use the Test CAPTCHA button at the bottom of the Security card. It runs a server-side validation against your secret key with a fake token, and surfaces the provider's response. Two outcomes you might see:

  • "Configured correctly". Your secret key works and Hypervisor can talk to the provider's verification endpoint outbound. CAPTCHA challenges from real users will succeed when valid.
  • An explicit provider error. Typically invalid-input-secret (wrong / mistyped secret key) or connection-refused (your server can't reach the provider; check egress firewall / DNS).

The test endpoint never blocks users; it's purely a sanity check.

Enabling Self-Registration​

  1. Settings > Security, find the Registration card.
  2. Toggle Allow Self-Registration.
  3. Save.

When self-registration is OFF, visitors hitting /register are redirected away. Admin-only user creation continues to work as before via Users > Create. When ON, the public registration form is reachable. CAPTCHA on Register is recommended.

You can also configure:

  • Terms of Service link. Appears as a "By registering you accept the Terms" link beneath the form. Leave blank to hide.
  • Top-up link. The URL the post-verification onboarding modal points new customers at (Stripe Checkout, your billing portal, a payment landing page). Leave blank to skip the modal entirely.

What the Customer Sees​

Sign-up form​

Visiting /register shows a glassmorphism card with:

  • First and last name
  • Email address
  • Country (a searchable dropdown with flag emoji and full country names)
  • Phone number
  • Password and confirmation
  • The CAPTCHA widget (when enabled and Protect Register is on)
  • Optional Terms of Service link

Submitting either creates the account and dispatches a verification email, or returns inline validation errors (CAPTCHA failure, weak password, duplicate email). No full-page reload.

Email verification​

Hypervisor sends a signed verification link valid for 60 minutes. Until the user clicks it, they land on a Verify your email page with:

  • The email address the link was sent to
  • A Resend verification email button (rate-limited to once per minute)
  • A live status pill that flips from "Pending" to "Verified" the instant the user clicks the link in another tab. No page refresh needed; the page subscribes to a private WebSocket channel for that user.

Post-verification onboarding​

If you've configured a Top-up link, the first dashboard load after verification opens a one-time modal:

Welcome modal

Welcome! Add credits to start deploying. Customers can either click Add Credits to head to the configured top-up link, or Skip for now to dismiss the modal.

The modal does not reappear on subsequent logins (the trigger is the ?onboarding=topup URL parameter Hypervisor adds to the post-verification redirect; navigating to the dashboard normally never opens it).

Login form​

If Protect Login is on, the login page renders the CAPTCHA widget under the password field. Failed CAPTCHA validation is treated like a wrong password: a generic error is shown without disclosing whether the email exists.

If Allow Self-Registration is on, a "Don't have an account? Sign up" link appears under the login button. With registration off, the link is hidden so the form looks identical to admin-only deployments.

What the Admin Sees​

Identifying self-registered users​

The admin Users list shows the same rows as before, plus the new Country and Phone columns. Self-registered accounts that have not yet completed email verification appear with a yellow "Unverified email" badge. Until they click the link, they cannot deploy resources.

Manually verifying a user​

If a customer can't find the verification email, you can:

  • Click Resend verification email on the user's edit page, or
  • Click Mark as verified to flip the status manually.

Disabling a user​

Suspended users can no longer log in regardless of email-verification state. Self-registration creates a regular user. You can suspend / delete them at any time.

Provider-Specific Notes​

Cloudflare Turnstile​

  • Privacy-friendly. No third-party cookies, no Google dependency.
  • The widget renders as a small "I'm verifying you're human..." pill that resolves automatically for most users without interaction.
  • Site keys starting with 0x4AAAAAAA... are production keys. Cloudflare also offers test keys (1x00000000...) that always pass; useful for staging environments where you don't want a real challenge.
  • No score threshold. Turnstile is pass / fail.

Google reCAPTCHA v2 ("I'm not a robot" checkbox)​

  • Renders the familiar Google checkbox. Some users will get an image grid challenge.
  • Reliable, broadly compatible. Adds one Google script and a third-party cookie.
  • No score threshold. v2 is pass / fail.

Google reCAPTCHA v3 (invisible score)​

  • No user interaction. The page silently runs in the background and assigns each submission a score from 0.0 (bot) to 1.0 (human).
  • Hypervisor compares the score against your reCAPTCHA v3 threshold setting and rejects below it.
  • Tune the threshold in production by watching for false positives (legitimate users getting "verification failed") and false negatives (sustained bot signups). Start at the default 0.5 and adjust by 0.1 at a time.
  • Requires that your domain is registered in the Google reCAPTCHA admin console with v3 selected.

Troubleshooting​

"verification failed" on every signup attempt

  • Check the Test CAPTCHA button output. Most often the secret key was pasted with a leading/trailing space, or the wrong key was used (e.g. v2 secret while v3 is selected as the provider).
  • Confirm the site key is the matching pair to the secret. Mismatched keys produce a generic failure.
  • For Turnstile and reCAPTCHA, confirm the registered domains in the provider console include the domain customers visit (and localhost if you're testing locally).

Verification email never arrives

  • Confirm your mail driver in admin Settings > Email delivers test emails successfully.
  • Check the user's spam folder. Newly-created sender domains are commonly flagged.
  • Have the user click Resend verification email on the verify-email page; the second send often arrives faster because of warm-up.

Verification page never auto-updates after the user clicks the link

  • WebSocket auto-update relies on the same broadcast pipeline used elsewhere in Hypervisor. If WebSockets are blocked between the customer and your server, the page won't auto-redirect, but reloading the page after clicking the link still works.

reCAPTCHA v3 is rejecting real users

  • Lower the threshold by 0.1. v3 scoring is sensitive to user behaviour patterns; a fresh deployment with little traffic history can score legitimate first-time visitors low.

Self-registration is on but /register still redirects away

  • Hard-reload the page; admin settings are cached for 60 seconds after a save. Confirm the Allow Self-Registration toggle reads "On" in admin Settings > Security.

Security Posture Recommendations​

Production hygiene
  • Always enable Protect Register when self-registration is on. Without it, a single bot can create thousands of unverified accounts.
  • Email verification is mandatory for self-registered accounts and cannot be turned off. This is intentional; it raises the cost of disposable signups significantly.
  • Pair self-registration with a meaningful top-up requirement (set a non-zero minimum top-up in your billing flow) before customers can actually deploy. Hypervisor will not stop a verified user from creating a free instance unless the plan they pick has a non-zero credit cost and they have insufficient balance.
  • Consider keeping the admin IP restriction (also in Settings > Security) on so only your operations team can reach /admin even if a self-registered account is somehow promoted to admin.