Skip to main content

CAPTCHA and Self-Registration

Overview​

This page explains two related panel features:

  • Self-registration: visitors that are not logged in can open /register and create their own customer account, instead of waiting for an admin to create it for them.
  • CAPTCHA: a "prove you are a human" challenge shown on the registration and login forms, used to block automated sign-up scripts (bots). "CAPTCHA" stands for Completely Automated Public Turing test to tell Computers and Humans Apart.

Both features are off by default. An admin enables them from the panel-wide Settings area.

Concepts​

CAPTCHA provider: a third-party service that runs the human-check. Hypervisor supports three providers; pick one.

ProviderWhat the visitor seesWhere you get the keys
Cloudflare TurnstileA small "verifying you are human" pill that usually resolves on its owndash.cloudflare.com -> Turnstile
Google reCAPTCHA v2The classic "I'm not a robot" checkbox, sometimes followed by an image gridgoogle.com/recaptcha/admin
Google reCAPTCHA v3Nothing visible; the provider scores the visitor silently from 0.0 (bot) to 1.0 (human)google.com/recaptcha/admin

You cannot mix providers. The provider you pick protects every form where CAPTCHA is turned on.

Site key and secret key: every provider issues a pair of keys. The site key is public and is embedded in the page shown to the visitor. The secret key is private and is used by the server to ask the provider "did this visitor really pass?". Never paste the secret key into the site-key field, or the other way around.

Email verification: after a self-registered visitor submits the form, the panel emails them a signed link. They must click that link before they can deploy anything. The link expires after 60 minutes. This is mandatory and cannot be turned off; it raises the cost of throw-away sign-ups.

Top-up link: an optional URL the visitor is offered the first time they log in after verification, so they can add account credit before they try to deploy.

Admin steps​

Configuring CAPTCHA​

  1. Sign in as admin and open Settings -> Users.
  2. In the CAPTCHA section:
    • Enable CAPTCHA: the master toggle. While it is off, no form shows a challenge.
    • Provider: pick Cloudflare Turnstile, reCAPTCHA v2, or reCAPTCHA v3.
    • Site key: paste the public key from the provider.
    • Secret key: paste the matching private key. The browser never sees this value.
    • reCAPTCHA v3 threshold (only visible when v3 is the chosen provider): the minimum score the panel will accept. Submissions below the threshold are rejected with a generic "verification failed" error. Default is 0.5. Raise toward 0.7 if you see bot traffic; lower toward 0.3 if real users are being blocked. v3 never shows a visible challenge, so this number is the only knob you have.
    • Protect Login: also show CAPTCHA on /login.
    • Protect Register: also show CAPTCHA on /register.
  3. Click Save.

Testing the configuration​

Use the Test CAPTCHA button at the bottom of the section. It runs a one-shot server-side check against your secret key and shows the provider's reply. Two common outcomes:

  • "Configured correctly": your secret key works and the server can reach the provider over the internet. Real visitors that pass the challenge will be accepted.
  • An explicit provider error, usually invalid-input-secret (wrong or mistyped secret key) or connection-refused (the server cannot reach the provider; check outbound firewall and DNS).

The test never blocks real visitors. It is a sanity check only.

Enabling self-registration​

  1. Still in Settings -> Users, find the Registration section.
  2. Turn on Allow Self-Registration.
  3. Click Save.

While self-registration is off, visitors that open /register are redirected away. You can still create users yourself from Users -> Create. While it is on, the public form is reachable. We recommend you also turn on Protect Register.

Two related fields:

  • Terms of Service link: shown as "By registering you accept the Terms" under the form. Leave blank to hide.
  • Top-up link: the URL offered in the welcome modal a brand-new customer sees on their first dashboard load. Point this at the platform's own Payments & Account Credit page, or at any external billing portal. Leave blank to skip the welcome modal entirely.

What end users see​

Sign-up form​

A visitor that opens /register is shown a card with:

  • First and last name
  • Email address
  • Country (a searchable dropdown with flag emoji)
  • Phone number
  • Password and confirmation
  • The CAPTCHA widget (when enabled and Protect Register is on)
  • The Terms of Service link, if you configured one

When they submit, the panel either creates the account and sends a verification email, or shows inline errors (CAPTCHA failed, weak password, email already in use). The page does not reload.

Email verification​

Until the visitor clicks the link in the email, they sit on a Verify your email page that shows:

  • The 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 moment they click the link in another tab. This works because the page is subscribed to a private WebSocket channel; a WebSocket is a long-lived browser-to-server connection that lets the server push updates without a page refresh.

Welcome modal​

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

Welcome modal

Welcome! Add credits to start deploying. The visitor can click Add Credits to go to your top-up link, or Skip for now to dismiss the modal.

The modal is triggered by an ?onboarding=topup parameter the panel adds to the post-verification redirect, so it does not reappear on later logins.

Login form​

If Protect Login is on, the CAPTCHA widget appears under the password field. A failed CAPTCHA is treated like a wrong password; the visitor gets a generic error so you do not leak which emails exist.

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

Admin views of self-registered users​

In the admin Users list, self-registered customers appear like any other customer, with two extra columns: Country and Phone. Accounts that have not yet clicked the verification link carry a yellow "Unverified email" badge and cannot deploy resources until they verify.

If a customer cannot find the verification email, open their edit page and either:

  • Click Resend verification email, or
  • Click Mark as verified to flip the status by hand.

Suspending or deleting a self-registered user works the same as for any other user.

Provider-specific notes​

Cloudflare Turnstile​

  • Privacy-friendly. No third-party cookies, no Google dependency.
  • The widget is a small pill that usually resolves with no interaction.
  • Site keys starting with 0x4AAAAAAA... are production keys. Cloudflare also offers test keys (1x00000000...) that always pass; useful in staging so you do not see a real challenge.
  • Pass or fail only. No score threshold.

Google reCAPTCHA v2​

  • The familiar Google checkbox. Some visitors get an image grid.
  • Reliable and broadly compatible. Loads one Google script and a third-party cookie.
  • Pass or fail only. No score threshold.

Google reCAPTCHA v3​

  • No visible challenge. The page silently scores the visitor 0.0 (bot) to 1.0 (human).
  • The panel compares the score against your reCAPTCHA v3 threshold and rejects anything below it.
  • In a fresh deployment with little traffic history, legitimate first-time visitors can score low. Start at the default 0.5 and adjust 0.1 at a time.
  • Your domain must be registered in the Google reCAPTCHA admin console with v3 selected.

Troubleshooting​

"Verification failed" on every sign-up

  • Run the Test CAPTCHA button. The most common cause is a secret key pasted with a leading or trailing space, or the wrong key (for example a v2 secret while v3 is the selected provider).
  • Confirm the site key matches the secret. Mismatched pairs produce a generic failure.
  • For Turnstile and reCAPTCHA, confirm your domain is registered with the provider (plus localhost if you are testing locally).

Verification email never arrives

  • Confirm your mail driver in Settings -> Email delivers test mail.
  • Ask the user to check the spam folder. Brand-new sender domains are often flagged.
  • Ask them to click Resend verification email on the verify page; the second attempt often arrives faster as the sender domain warms up.

Verification page never flips to "Verified"

  • Live updates use the same WebSocket pipeline as the rest of the panel. If WebSockets are blocked between the visitor and your server, the page will not auto-update, but reloading it after they click the link still works.

reCAPTCHA v3 rejects real users

  • Lower the threshold by 0.1. v3 is sensitive to visitor behaviour patterns.

Self-registration is on but /register still redirects away

  • Hard-reload the page. Admin settings are cached for 60 seconds after you save. Then confirm Allow Self-Registration reads "On" in Settings -> Users.

Security recommendations​

Production hygiene
  • Always turn on Protect Register when self-registration is on. Without it, a single bot can create thousands of unverified accounts.
  • Email verification cannot be turned off. This is intentional.
  • Pair self-registration with a non-zero minimum top-up in the built-in Payments & Account Credit settings, or in your external billing flow. Otherwise a verified visitor can deploy a free instance if the plan they pick has zero credit cost.
  • Keep the admin IP restriction (also in Settings -> Users) on, so only your operations team can reach /admin even if a self-registered account is somehow promoted to admin.