Skip to content
Home PricingFree forever, paid adds live intelligence Akismet alternative reCAPTCHA alternative All comparisons IntegrationsAll 33, and how each one is protected WooCommerce protection Contact Form 7 Elementor Documentation Sign in

Documentation

Developer reference

For: developers integrating Gatekeep, protecting custom forms, or extending it. Assumes: PHP and the WordPress plugin API.

Requires PHP 7.4+, WordPress 5.8+. Tested to WordPress 7.1, on MySQL and SQLite, single site and multisite, with and without a persistent object cache.


Contents

  1. Protecting a custom form
  2. The public API
  3. REST endpoints
  4. Filters
  5. Actions
  6. Architecture
  7. Writing an integration
  8. Behind a proxy or CDN
  9. Testing

1. Protecting a custom form

Two calls.

// Inside your <form> markup.
gatekeep_field();

// When handling the submission.
$check = gatekeep_verify();

if ( is_wp_error( $check ) ) {
    wp_die( $check->get_error_message() );
}

Or drop [gatekeep] into any builder.

For a form you cannot edit, enable the universal form guard: it injects into rendered markup and intercepts the matching POST. Restrict it with selectors (#signup, .newsletter) or exclude URLs.


2. The public API

gatekeep_field( string $context = 'custom', bool $echo = true ): string

Renders the hidden fields and any configured challenge. Returns '' in Safe mode.

gatekeep_verify( string $context = 'custom', array $post = null ): true|WP_Error

Assesses the current request. Returns true when allowed. Never blocks in Safe mode.

gatekeep_assess( string $context, array $args = [] ): array

The full result:

[
    'verdict'  => 'allow'|'challenge'|'block',
    'score'    => 0-100,
    'signals'  => [ [ 'slug' => …, 'risk' => 0-100, 'label' => … ], … ],
    'enforced' => bool,   // false while Monitor Mode holds a borderline case
    'certain'  => bool,   // present when a conclusive signal forced enforcement
    'passed'   => bool,   // what to act on
    'message'  => string,
    'context'  => string,
]

Accepted $args: post (unslashed array), email (skip address detection), skip_rate (bypass the rate limiter — use for synthetic checks).

Act on passed, not verdict. A block verdict that is not enforced must be let through.

gatekeep_is_safe_mode(): bool


3. REST endpoints

GET /wp-json/gatekeep/v1/challenge

Issues a token for a headless front end. Returns the token, the field name to post it under, the current honeypot field name, and proof-of-work parameters if configured.

The honeypot field name is derived per site from its salts, so it must be read from here rather than hardcoded.

POST /wp-json/gatekeep/v1/siteverify

reCAPTCHA-compatible. Accepts secret and response, returns Google's response shape — anything already written against siteverify works by changing one URL.

{ "success": true, "score": 1.0, "action": "contact",
  "challenge_ts": "2026-07-29T09:14:00+00:00", "hostname": "example.com" }

GET /wp-json/gatekeep/v1/captcha?c=…

Renders an image challenge. Requires a signed payload; rate limited to 30 requests per address per minute. The signature is verified before any rendering work.

Both public endpoints can be switched off.


4. Filters

Scoring

Filter Signature Purpose
gatekeep_signals array $signals, string $context, array $post Add or modify signals before scoring
gatekeep_assessment array $result, string $context Change the final verdict
gatekeep_block_message string $message, array $result Message shown when blocked
gatekeep_disposable_domains array $map Extend the bundled domain map
gatekeep_autofill_contexts array $contexts Where fast submission is normal
add_filter( 'gatekeep_signals', function ( $signals, $context, $post ) {
    if ( 'my_form' === $context && empty( $post['referrer'] ) ) {
        $signals[] = [
            'slug'  => 'no_referrer',
            'risk'  => 30,
            'label' => __( 'No referrer supplied', 'my-plugin' ),
        ];
    }
    return $signals;
}, 10, 3 );

Risk is 0–100. Anything at or above certain_threshold (default 90) is enforced even during Monitor Mode — reserve that for signals a real visitor cannot trigger.

Rendering and integration

Filter Purpose
gatekeep_fields_html Markup injected into forms
gatekeep_form_shortcodes Shortcodes whose output should be protected
gatekeep_fingerprints Submission fingerprints for breakage detection
gatekeep_request_bufferable Whether the current request may be buffered
gatekeep_overlapping_plugins Competing plugins reported to the user

Infrastructure

Filter Purpose
gatekeep_client_ip Supply the client IP
gatekeep_can_use Override Pro gating
gatekeep_license_endpoint Licence API URL
gatekeep_feed_endpoint Threat feed URL
gatekeep_captcha_lifetime How long a challenge stays valid
gatekeep_captcha_fonts Font candidates for image challenges
gatekeep_captcha_image_limit Image requests allowed per minute
gatekeep_watched_options Options treated as security-critical
gatekeep_watched_network_options The same, network-wide
gatekeep_audit_findings Add or remove audit checks
gatekeep_diagnostics Add or remove self-test checks
gatekeep_profiles Add a protection profile
gatekeep_trusted_capability string $capability Which capability marks a user as trusted enough to skip every check. Defaults to edit_posts. Lower it and you widen the bypass — a subscriber created by open registration is not the same as somebody you gave standing to.
gatekeep_login_exempt bool $exempt Exempt a recovery login from scoring.
gatekeep_challenge_limit int $per_minute How many challenges one address may request each minute from the public API. Default 60.
gatekeep_challenge_limit_global int $per_minute Site-wide ceiling on the same endpoint. Default 600. The per-address limit above is the one a rotating proxy pool never meets; this is the one it cannot route around.
gatekeep_guard_admin_endpoints array $endpoints Admin-post and AJAX endpoints the universal guard covers.
gatekeep_existing_captchas array $map Which other plugins count as an existing captcha, for the coexistence report.
gatekeep_profile_licence_bypass bool $bypass Allow a protection profile to apply licensed settings.
gatekeep_friendly_widget_url string $url Where the Friendly Captcha widget script is loaded from.

5. Actions

Action Fires when
gatekeep_loaded The plugin is ready — hook here before using the API
gatekeep_safe_mode Loaded in Safe mode
gatekeep_adapter_degraded An integration was judged broken by an upstream change
gatekeep_security_event A security event was recorded
gatekeep_contained_failure A callback of ours failed and was contained
gatekeep_profile_applied A protection profile was applied
gatekeep_onboarding_complete Guided setup finished
gatekeep_recorded array $result Fires after a verdict is written to the activity log. The reputation store listens here; anything else that wants the final result can too.
gatekeep_page_uncacheable string $context Fires when a page has been given per-request Gatekeep fields. Hook this from a caching layer that does not honour DONOTCACHEPAGE — a cached challenge is the same token and the same answer served to every visitor until the copy expires.
gatekeep_render_guard string $context Emit Gatekeep’s fields inside a template you control.

6. Architecture

Classes are autoloaded; a front-end page view parses about 111 KB of the 298 KB total. Nothing admin-only, licence-related or hardening-related loads for a visitor.

Class Responsibility
GK_Engine Collects signals, scores, decides
GK_Signals Individual checks
GK_Token HMAC-signed stateless tokens. GK_Token::sign_payload() is the only correct way to sign one
GK_Captcha Self-hosted challenges
GK_Providers Third-party verification
GK_Guard Universal form protection
GK_Integrations / GK_Builders Per-plugin adapters
GK_Compat Detects adapters that stopped firing
GK_Isolation Buffering safety and failure containment
GK_Log / GK_Events Verdict and security-event storage
GK_Feed Threat feed, in an indexed table. The engine asks GK_Feed::has_domain() - one indexed lookup, returning a confidence rather than a bare yes. domains() reads the same table if you need the map. A refresh that returns dramatically fewer domains than currently held is refused as truncated rather than imported
GK_License Licensing

Two design rules worth knowing

Signals combine by noisy-OR, not addition. Three weak signals cannot stack into a block. One conclusive signal decides alone.

Failures are contained, never propagated. Adapters run inside third-party code, where an exception takes their form down and gets blamed on Gatekeep. GK_Isolation::safely() wraps callbacks; a failure lets the submission through and is recorded. An unprotected form is recoverable; a broken page is not.


7. Writing an integration

add_action( 'gatekeep_loaded', function () {
    add_filter( 'myforms_validate', function ( $errors, $submission ) {
        $result = gatekeep_assess( 'myforms', [
            'email' => $submission['email'] ?? '',
        ] );

        if ( empty( $result['passed'] ) ) {
            $errors[] = $result['message'];
        }

        return $errors;
    }, 10, 2 );
} );

Guidelines:

  • Use the target plugin's own error channel so the rejection appears in its normal UI.
  • Never fatal. Guard every call into third-party code with method_exists() or class_exists().
  • Bind several candidate hook names. Hooks that no longer exist never fire, so listing historical names is free insurance. GK_Compat::bind_any() does this.
  • Register a fingerprint via gatekeep_fingerprints so breakage detection can spot missed submissions.
  • Do not version-sniff. Inspect what the submission actually carries. Divi 5 changed its format entirely; a version check would only know about versions that existed when it was written.

8. Behind a proxy or CDN

X-Forwarded-For is not trusted by default — doing so lets anyone spoof past a rate limit. Supply the address explicitly:

add_filter( 'gatekeep_client_ip', function () {
    return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $_SERVER['REMOTE_ADDR'];
} );

Only do this where the header genuinely comes from your proxy.


9. Testing

Twenty-one suites ship separately, runnable from a WordPress root. Run reset.php between them. As of 1.43.1 the whole battery passes with zero failures - roughly 1,200 assertions on WordPress 7.0.1 against MySQL and the SQLite integration layer, with WooCommerce 10.9.4, Elementor, Contact Form 7, Formidable, bbPress and Fluent Forms live.

Three suites have preconditions:

  • licence-e2e needs the licence server running locally. PHP's built-in server does not route /v1/* from a docroot; start it in router mode: php -S 127.0.0.1:9099 index.php.
  • license-fortify expects the Fortify module bound at boot, so set fortify on and store a licence before running the suite in a fresh process. Clear that licence afterwards - a live licence routes email checks through the feed table, which skews the timing suites.
  • pentest budgets 5 ms per blocked submission on MySQL and allows 12 ms on the SQLite layer, where each log write costs a couple of milliseconds more.

Two that matter if you are extending Gatekeep:

  • suite-16-settings-matrix flips all 81 switches and asserts each changes observable behaviour. Add a setting without wiring it and this fails.
  • suite-19-diagnostics deliberately breaks things and asserts each is caught — including a case that would otherwise pass for the wrong reason.

Verified on WordPress 6.8 (SQLite), 7.0 with nine page builders, and 6.8 on MariaDB as a three-site multisite network with Redis. browser/accessibility-axe.js checks WCAG 2.1 AA.

Signing tokens in tests: use GK_Token::sign_payload(). Signatures are truncated to 32 characters; eight suites once hand-rolled 64-character ones and passed for the wrong reasons.

← All documentation Still stuck? Open a ticket