Migrate TrustCaptcha to Version 2.x

This migration guide provides an overview of how to upgrade from CAPTCHA version 1.x to CAPTCHA version 2.0 or higher.

Affected versions

We released version 2.0 of TrustCaptcha in June 2025. This includes both version 2.0 of our CAPTCHA widget for the front end and version 2.0 for our backend libraries. Corresponding updates are available for CMS and platform systems such as WordPress.

The most important changes

Change of namespace
With version 2.0.0, TrustCaptcha was transferred to the TrustComponent platform and the associated namespace. Dependencies have been moved to this namespace accordingly and must be adjusted accordingly. The TrustComponent API is now available at https://api.trustcomponent.com.

CAPTCHA widget features (frontend)
All CAPTCHA widget features remain unchanged and are therefore the same as in version 1.9.x. The syntax is also identical. From version 2.1.x onwards, the CAPTCHA automatically resets when the verification result expires, further improving the user experience.

Backend integrations / API call
The verification token no longer contains an encrypted access token that must be decrypted on the server side using the secret key in order to retrieve the verification result from our servers. In version 2.0, the result can be retrieved directly from our servers with a simple REST API call. The verification token is still Base64 encoded and contains information about the API endpoint and verification ID. The secret key now takes on the role of a simple API key.

Failover compatibility
Version 2.x is compatible with our new failover concept. This can intercept a whole range of possible errors in our technical infrastructure and offers higher availability/reliability.

Time frame

Versions 1.x and 2.x can both be used at the moment. However, we plan to discontinue support for version 1.x in the long term, probably starting in spring 2026.
Regardless of this, we recommend to upgrade to CAPTCHA version 2.0 as soon as possible.

JavaScript

The javascript file is now hosted on: "https://cdn.trustcomponent.com/trustcaptcha/2.1.x/trustcaptcha.umd.min.js" (example for Universal Module Definition). JavaScript bundles for ECMAScript modules or CommonJS are also available.
Go to the JavaScript-Guide

Angular

The dependency can now be found in NPM under @trustcomponent/trustcaptcha-angular.
Please also note that Angular integration is a standalone component for some time.
Go to the Angular-Guide

React

The dependency can now be found in NPM under @trustcomponent/trustcaptcha-react.
Go to the React-Guide

Vue

The dependency can now be found in NPM under @trustcomponent/trustcaptcha-vue.
Go to the Vue-Guide

If you use our prebuilt backend integrations, the main change is the change in the namespace. The syntax of the CaptchaManager and verification result properties usually remains unchanged. If you need further information, please refer directly to the respective guide for the relevant programming language/technology.

Custom API Implementation
You are also welcome to implement the API interface individually. Please note that there is no longer an encrypted access token that you need to decrypt on the server side with the secret key in order to then retrieve the result from our servers. This process has been replaced by a simple Rest API call. You can find the relevant information in the backend details. All source codes for our ready-made libraries can also be found on our Github profile.

Ensure network connection
The API interface is now available at https://api.trustcomponent.com. Please ensure that there are no network restrictions that limit communication with our API.

Go

The dependency is now available at github.com/trustcomponent/trustcaptcha-go/v2
Go to the Go-Guide
View source code on Github

DotNet

The dependency is now available on NuGet under “TrustComponent.TrustCaptcha.”
Go to the DotNet-Guide
View source code on Github

JVM (e.g. Java)

The dependency can now be found on Maven Central under com.trustcomponent:trustcaptcha:2.0.0.
Go to the Java-Guide
View source code on Github

NodeJS

The dependency can now be found in NPM under @trustcomponent/trustcaptcha-nodejs.
Go to the NodeJS-Guide
View source code on Github

PHP

Our library is now available on Packagist at trustcomponent/trustcaptcha-php.
Go to the PHP-Guide
View source code on Github

Python

The new dependency on PyPI is now called “trustcaptcha”.
Go to the Python-Guide
View source code on Github

Ruby

The dependency can be installed with “gem install trustcaptcha”.
Go to the Ruby-Guide
View source code on Github

Rust

The dependency can be installed with “cargo add trustcaptcha”.
Go to the Rust-Guide
View source code on Github

WordPress

Please log in to the admin area of a WordPress website and update the plugin. If you installed the plugin via ZIP archive, you will find a new version available for download in the WordPress guide.
Go to the WordPress-Guide

CraftCMS

Please update the plugin in the CraftCMS Store or update your Packagist dependency. For more information, see the CraftCMS Guide.
Go to the CraftCMS-Guide

Keycloak

Please download the latest plugin version from the Keycloak Guide and install it. You can find more information about this in the Keycloak Guide..
Go to the Keycloak-Guide

Magento 2 / TYPO 3 / Webflow

The plugins for these platforms are new and there are no outdated versions. Therefore, nothing needs to be updated.