TrustCaptcha – Bot protection

NestJS CAPTCHA Integration

Wire TrustCaptcha into a NestJS controller or guard in just a few lines of TypeScript. Stop bot-driven spam on logins, signups and contact forms — with full DI support, ConfigModule integration and type-safe DTOs. EU-hosted, GDPR-ready, no image puzzles.

Quickstart

How the integration works

1. Create a CAPTCHA

Create a user account or log in with an existing one. Then create a new CAPTCHA or select an existing one. If you’re unsure whether TrustCaptcha is right for you, try our CAPTCHA service risk-free for 14 days at no cost.

On the CAPTCHA overview page, you will find all the important information, such as the site key and licence key, and you can also create your API key. Allow your websites to access your CAPTCHA by simply adding them to the access authorised domain list in the CAPTCHA security rules.

CAPTCHA security rules of a demo CAPTCHA.

2. Add the CAPTCHA widget to your form

Drop the TrustCaptcha widget into the HTML form your NestJS controller serves. The widget runs the CAPTCHA in the background and adds a hidden tc-verification-token field on submit, which arrives on req.body like any other input.

contact.html

HTML

<script type="module" src="https://cdn.trustcomponent.com/trustcaptcha/3.0.x/trustcaptcha.esm.min.js"></script>

<form method="post" action="/contact">
    <input type="email" name="email" required>
    <trustcaptcha-component sitekey="<your_site_key>"></trustcaptcha-component>
    <button type="submit">Send</button>
</form>

The CAPTCHA widget will then be displayed inside your form:

Need detailed information about the CAPTCHA widget integration?
For the full widget reference — including themes, languages, custom design and more — please read our documentation.

Read the documentation

3. Validate the token in your NestJS controller

In your NestJS controller, take the verification token from the request body, look up the result via our Node.js library, and decide whether to accept the request.

First, install our TrustCaptcha Node.js library:

Install

bash

npm i @trustcomponent/trustcaptcha-nodejs

Then validate the token inside your NestJS controller and act on the result:

contact.controller.ts

TypeScript

import { BadRequestException, Body, Controller, Post } from "@nestjs/common";
import { TrustCaptcha } from "@trustcomponent/trustcaptcha-nodejs";

@Controller("contact")
export class ContactController {
  @Post()
  async submit(@Body() body: { "tc-verification-token": string }) {
    const token = body["tc-verification-token"] ?? "";

    try {
      const result = await TrustCaptcha.getVerificationResult("<your_api_key>", token);
      if (!result.verificationPassed || result.score > 0.5) {
        throw new BadRequestException("CAPTCHA verification failed.");
      }
    } catch {
      throw new BadRequestException("CAPTCHA verification failed.");
    }

    // CAPTCHA passed — process the request
    return { status: "ok" };
  }
}

Need detailed information about the NestJS CAPTCHA integration?
For full step-by-step instructions — including a reusable Guard refactor for projects with several protected endpoints — please read our documentation.

Read the documentation

Other backend framework instead of NestJS?
If you use a different framework, pick the matching recipe here. If your framework isn’t listed, your software developers can integrate the verification themselves using our documentation or ask our support team for a pre-built integration.

4. Congratulations 🎉

You are now protected by TrustCaptcha - congratulations!

FAQs

Where in a NestJS app does the CAPTCHA verification go?

Inside the controller method that receives the form submission, or — for a cleaner setup with several protected endpoints — inside a custom NestJS guard. Both have access to the request body, where the CAPTCHA token (default name: "tc-verification-token") arrives like any other field.

Should I use a guard, an interceptor or just call the verification in the controller?

For a single endpoint, calling it directly in the controller is fine. For multiple protected endpoints, a guard (TrustCaptchaGuard) is the most idiomatic NestJS pattern: a single @UseGuards(TrustCaptchaGuard) decorator opts any controller method into CAPTCHA verification.

How do I share the API key across the app?

Use Nest's ConfigModule. Inject ConfigService into the guard or controller and read the API key with config.getOrThrow<string>("TRUSTCAPTCHA_API_KEY"). The key itself lives in your .env file or your hosting provider's secret store.

Does NestJS' ValidationPipe interfere with the CAPTCHA token?

No. ValidationPipe only validates DTO fields you've declared. The CAPTCHA token is read from req.body in the guard (or from a typed DTO with a custom decorator), so it works alongside ValidationPipe without any changes.

Do I need to configure body parsing manually?

No. Nest enables express.json() and express.urlencoded() by default — req.body is parsed before the guard or controller runs, so the CAPTCHA token is available out of the box.

Losing leads to CAPTCHAs?

TrustCaptcha blocks spam and bots, not customers. No puzzles, GDPR-ready, EU-hosted.

Puzzle-free UX

Runs in the background while visitors type — so more people finish your forms and fewer drop off.

GDPR-ready

EU-hosted and privacy-first: no cookies, encrypted transmission, automatic cleanup — with ready-to-use legal resources.

Multi-layer Security

Adaptive protection plus intelligent risk scoring stops abuse early — even when attack traffic spikes.

Full Control

Fine-tune sensitivity, set allow/block lists, and use geoblocking — you decide how strict verification should be.

Protect your NestJS application with TrustCaptcha in just a few steps!

EU-hosted & GDPR-ready
No puzzles
Try free for 14 days

Get started Contact sales