RecaptchaEnterpriseProvider

Package: @nauth-toolkit/recaptcha Type: Provider Class

Enterprise-grade reCAPTCHA provider with advanced fraud detection and analytics.

NestJS

import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

Express

import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

Fastify

import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

Constructor

new RecaptchaEnterpriseProvider(config: RecaptchaEnterpriseConfig)

RecaptchaEnterpriseConfig

Property	Type	Required	Description
apiKey	string	Yes	API key from Google Cloud Console with reCAPTCHA Enterprise API enabled.
apiEndpoint	string	No	Custom API endpoint for regional deployments. Default: https://recaptchaenterprise.googleapis.com/v1.
projectId	string	Yes	Google Cloud project ID.
siteKey	string	Yes	Site key from reCAPTCHA Enterprise console.
timeout	number	No	Request timeout in milliseconds. Default: 10000.

Methods

verify()

Verify reCAPTCHA Enterprise token with Google's API.

async verify(token: string, remoteIp?: string, action?: string): Promise<RecaptchaVerificationResult>

Parameters

• token - reCAPTCHA token from client
• remoteIp - Client IP address (optional, recommended)
• action - Action name (e.g., 'login', 'signup')

Returns

• RecaptchaVerificationResult - Verification result with score and risk analysis

validateConfig()

Validate provider credentials at startup by sending a probe request to Google's API.

async validateConfig(): Promise<RecaptchaValidationResult>

Returns

• RecaptchaValidationResult - { valid, message, hint?, httpStatus? }

Called automatically during NAuth.create() when validateOnStartup is 'warn' (default) or 'error'. Detects invalid API keys, wrong project IDs, disabled APIs, and bad site keys with actionable error messages.

Example

NestJS

import { NAuthModule } from '@nauth-toolkit/nestjs';
import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

@Module({
  imports: [
    NAuthModule.forRoot({
      recaptcha: {
        enabled: true,
        provider: new RecaptchaEnterpriseProvider({
          projectId: process.env.RECAPTCHA_PROJECT_ID!,
          apiKey: process.env.RECAPTCHA_API_KEY!,
          siteKey: process.env.RECAPTCHA_SITE_KEY!,
        }),
        minimumScore: 0.7,
        actionScores: {
          login: 0.3,   // More permissive for returning users
          signup: 0.7,  // Stricter for new registrations
        },
      },
    }),
  ],
})
export class AppModule {}

Express

import { NAuth } from '@nauth-toolkit/core';
import { ExpressAdapter } from '@nauth-toolkit/express';
import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

const nauth = await NAuth.create({
  config: {
    recaptcha: {
      enabled: true,
      provider: new RecaptchaEnterpriseProvider({
        projectId: process.env.RECAPTCHA_PROJECT_ID!,
        apiKey: process.env.RECAPTCHA_API_KEY!,
        siteKey: process.env.RECAPTCHA_SITE_KEY!,
      }),
      minimumScore: 0.7,
      actionScores: {
        login: 0.3,
        signup: 0.7,
      },
    },
  },
  dataSource,
  adapter: new ExpressAdapter(),
});

Fastify

import { NAuth } from '@nauth-toolkit/core';
import { FastifyAdapter } from '@nauth-toolkit/fastify';
import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

const nauth = await NAuth.create({
  config: {
    recaptcha: {
      enabled: true,
      provider: new RecaptchaEnterpriseProvider({
        projectId: process.env.RECAPTCHA_PROJECT_ID!,
        apiKey: process.env.RECAPTCHA_API_KEY!,
        siteKey: process.env.RECAPTCHA_SITE_KEY!,
      }),
      minimumScore: 0.7,
      actionScores: {
        login: 0.3,
        signup: 0.7,
      },
    },
  },
  dataSource,
  adapter: new FastifyAdapter(),
});

Enterprise Features

• Advanced fraud detection - Machine learning-based bot detection
• Custom rules - Define custom security policies
• Detailed analytics - Real-time dashboards and reporting
• SLA guarantees - 99.9% uptime commitment
• Priority support - Dedicated support team

Setup

1. Enable API

1. Go to Google Cloud Console
2. Select or create a project
3. Navigate to APIs & Services → Library
4. Search for "reCAPTCHA Enterprise API"
5. Click Enable

2. Create Site Key

1. Go to reCAPTCHA Enterprise Console
2. Click Create Key
3. Select "Score-based" type
4. Add your domains (including localhost for development)
5. Copy the site key

3. Create API Key

1. Go to APIs & Services → Credentials
2. Click Create Credentials → API Key
3. Edit the key to restrict it:
   • API restrictions: Select "reCAPTCHA Enterprise API"
   • Application restrictions: Set to "None" for server-to-server calls
4. Copy the API key

4. Configure Backend

RECAPTCHA_PROJECT_ID=your-project-id
RECAPTCHA_API_KEY=AIzaSy...your-api-key
RECAPTCHA_SITE_KEY=6Le...your-site-key

When to Use

• High-traffic production applications
• Advanced security requirements
• Compliance and auditing needs
• SLA guarantees required

Related

• RecaptchaConfig - Configuration interface
• RecaptchaV3Provider - Standard v3 alternative
• reCAPTCHA Guide - Complete implementation guide