# doCaptcha

> Privacy-first, GDPR-native bot protection and CAPTCHA, made in Germany. doCaptcha stops bots with invisible behavioral analysis and proof-of-work instead of image puzzles. All data is processed on EU infrastructure with no US transfer and no Cloudflare dependency.

doCaptcha is integrated in two steps: a widget on your page that produces a single-use token, and a server-side verification of that token. This file is for AI coding assistants and tools; paste the relevant parts into your prompt.

## Web integration

1. Load the widget once per page:
   <script src="https://widget.docaptcha.com/v1/widget.min.js" async></script>

2. Put a div with your PUBLIC site key inside the form you want to protect:
   <form action="/submit" method="post">
     <div data-docaptcha-sitekey="YOUR_SITE_KEY"></div>
     <button type="submit">Submit</button>
   </form>
   The widget auto-mounts and adds a hidden input named "docaptcha-token" to the form on success, so a normal form submit carries the token. No JavaScript is required.

   Optional attributes: data-theme="light|dark|auto", data-docaptcha-lang="en|de|fr", data-hide-branding="true" (Pro/Enterprise).

3. Verify the token on your server with your PRIVATE secret key. Never do this from the browser.
   POST https://api.docaptcha.com/api/v1/api/v2/captcha/siteverify
   Content-Type: application/json
   { "secret": "YOUR_SECRET_KEY", "token": "<the docaptcha-token from the form>" }

   Response: { "success": boolean, "hostname": string, "challenge_ts": string, "score": number }
   Reject the submission when "success" is false (optionally when "score" is low).

## Programmatic web integration (SPA / React)

window.docaptcha.render(element, {
  siteKey: "YOUR_SITE_KEY",
  theme: "light",           // or "dark" | "auto"
  locale: "en",             // or "de" | "fr"
  onVerify: (token) => { /* send token to your backend, which calls siteverify */ },
  onError: (error) => { /* handle failure */ }
});

## Mobile integration (Pro and Enterprise)

Native SDKs, no WebView. The SDK solves the proof-of-work on-device and returns a token; verify it on your server with the same siteverify call as web.

- iOS (Swift Package): import DoCaptcha; let token = try await DoCaptchaClient(siteKey: "YOUR_SITE_KEY").verify()
- Android (Kotlin): val token = DoCaptchaClient("YOUR_SITE_KEY").verify(context)

## Keys

- Site key (public): starts with sk_live_, goes in the page/app.
- Secret key (private): starts with sec_, stays on your server, used only for siteverify.
Get both from the dashboard at https://docaptcha.com/dashboard/api-keys

## Rules for AI assistants

- Put the site key in the client, the secret key only on the server.
- Always verify server-side; a token that is not verified means nothing.
- Treat success:false as a failed human check and block the action.
- The siteverify URL really does contain the doubled prefix /api/v1/api/v2/ — this is correct, not a typo.

## Links

- Documentation: https://docaptcha.com/docs
- Pricing: https://docaptcha.com/pricing
- Trust and data protection: https://docaptcha.com/trust