> ## Documentation Index
> Fetch the complete documentation index at: https://verifyngo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CAPTCHA provider configuration for verifyngo (config.json)

> Set up Cap (self-hosted), Cloudflare Turnstile, or hCaptcha as your CAPTCHA provider. Configure multiple providers so visitors can switch between them.

verifyngo supports three CAPTCHA providers: Cap, Cloudflare Turnstile, and hCaptcha. You pick one as the default by setting the `provider` field in your `config.json`, then fill in the matching configuration block. If you configure more than one provider at the same time, visitors will see a "switch provider" link on the challenge page — letting them move to a different provider if the first one isn't working for them.

## Available providers

* **`cap`** — a self-hosted CAPTCHA server; you run it on your own infrastructure.
* **`turnstile`** — Cloudflare Turnstile; requires a Cloudflare account.
* **`hcaptcha`** — hCaptcha; requires an hCaptcha account.

## Choosing your provider

Set the `provider` field to the name of the provider you want to use by default. Then fill in the configuration block that matches that provider name. The sections below show the exact fields for each option.

<Tabs>
  <Tab title="Cap">
    Cap is a self-hosted CAPTCHA server. You install and run it yourself, so
    challenge traffic goes through your own infrastructure.

    ```json theme={null}
    {
      "provider": "cap",
      "cap": {
        "api_url": "https://captcha.example.com",
        "verify_url": "http://127.0.0.1:3000",
        "site_key": "your-cap-site-key",
        "secret_key": "your-cap-secret-key",
        "widget_script_url": ""
      }
    }
    ```

    <ParamField body="cap.api_url" type="string" required>
      The public URL of your Cap instance. The visitor's browser loads the
      widget script and submits the challenge from this address, so it must be
      reachable from the internet.
    </ParamField>

    <ParamField body="cap.verify_url" type="string">
      The URL verifyngo uses internally to verify a submitted token. Because
      this call happens server-side, you can point it at a local or internal
      address (e.g. `"http://127.0.0.1:3000"`) to avoid an extra round-trip
      through the internet. If left empty, verifyngo falls back to `api_url`.
    </ParamField>

    <ParamField body="cap.site_key" type="string" required>
      The site key for your Cap instance. You'll find this in your Cap server's
      admin panel.
    </ParamField>

    <ParamField body="cap.secret_key" type="string" required>
      The secret key for your Cap instance. Keep this value private — it is used
      to verify tokens server-side.
    </ParamField>

    <ParamField body="cap.widget_script_url" type="string">
      An optional URL to load the Cap widget script from. Leave it empty to use
      the default Cap CDN (`https://cdn.jsdelivr.net/npm/@cap.js/widget`). Set
      this if you self-host the widget script alongside your Cap server.
    </ParamField>
  </Tab>

  <Tab title="Turnstile">
    Cloudflare Turnstile is a managed CAPTCHA service. You manage your keys
    from the Cloudflare dashboard.

    ```json theme={null}
    {
      "provider": "turnstile",
      "turnstile": {
        "site_key": "your-turnstile-site-key",
        "secret_key": "your-turnstile-secret-key"
      }
    }
    ```

    <ParamField body="turnstile.site_key" type="string" required>
      Your Turnstile site key. Find this in the Cloudflare dashboard under
      **Turnstile** → your site → **Site Key**.
    </ParamField>

    <ParamField body="turnstile.secret_key" type="string" required>
      Your Turnstile secret key. Find this in the Cloudflare dashboard under
      **Turnstile** → your site → **Secret Key**. Keep this value private.
    </ParamField>
  </Tab>

  <Tab title="hCaptcha">
    hCaptcha is a managed CAPTCHA service. You manage your keys from the
    hCaptcha dashboard.

    ```json theme={null}
    {
      "provider": "hcaptcha",
      "hcaptcha": {
        "site_key": "your-hcaptcha-site-key",
        "secret_key": "your-hcaptcha-secret-key"
      }
    }
    ```

    <ParamField body="hcaptcha.site_key" type="string" required>
      Your hCaptcha site key. You can find this on your hCaptcha dashboard at
      [hcaptcha.com](https://www.hcaptcha.com) under **Sites**.
    </ParamField>

    <ParamField body="hcaptcha.secret_key" type="string" required>
      Your hCaptcha secret key. You can find this in your hCaptcha account
      settings. Keep this value private.
    </ParamField>
  </Tab>
</Tabs>

## Configuring multiple providers

You can fill in more than one provider block in the same `config.json`. The `provider` field controls which one is shown first — the others act as alternatives. When verifyngo detects that more than one provider is fully configured, it displays a "switch provider" link on the challenge page. Visitors can click it to switch to a different provider if the current one is unavailable or blocked for them.

```json theme={null}
{
  "provider": "cap",
  "cap": {
    "api_url": "https://captcha.example.com",
    "verify_url": "http://127.0.0.1:3000",
    "site_key": "your-cap-site-key",
    "secret_key": "your-cap-secret-key",
    "widget_script_url": ""
  },
  "turnstile": {
    "site_key": "your-turnstile-site-key",
    "secret_key": "your-turnstile-secret-key"
  }
}
```