Backend Release Notes

Here you can see all the modifications and changes of the TrustCaptcha backend libraries (.NET, Go, JVM, Node.js, PHP, Python, Ruby, Rust).

• Renamed: CaptchaManager is now TrustCaptcha across all libraries.
• Renamed: Library exceptions are no longer named SecretKey…. They are now ApiKeyInvalid…. The parameter name secretKey was renamed to apiKey (existing API key values continue to work unchanged).
• Added: Builder / configurable instance for every library, with apiHost, connectTimeoutMs, readTimeoutMs and proxy options. Static shortcut (TrustCaptcha.getVerificationResult(apiKey, token)) remains available for the simple case.
• Added: Proxy support across all 8 libraries (previously available only in PHP).
• Added: New exception VerificationResultExpiredException (HTTP 410 — the result has expired).
• Added: New exception VerificationResultRetrievalLimitReachedException (HTTP 429 — the result has reached its maximum retrieval count).
• Added: Failover exception family — FailoverException (abstract) with two children: ServerUnreachableException (your backend cannot reach our servers — high trust) and ClientReportedServerUnreachableException (HTTP 412 — the widget claims a failover, the gateway has no record of one). See the new Failover behavior page for guidance.
• Added: Widget-side failover token generation — opt-in via the failover-enabled widget attribute. When set, the widget issues a self-built token with clientFailover: true if it cannot reach our servers. Default is off; the widget surfaces a regular communication failure unless the integrator opts in.
• Added: Result field gatewayFailoverActive: boolean — true when the gateway synthesized the result during a captcha-service outage (regular gateway-observed outage and accepted client-failover claim). High-security integrations can filter out failover-derived results with a single check.
• Added: New result fields decisionType, decisionAction, riskScoringEnabled, minimalDataModeEnabled, countryCode, verificationStartedAt, verificationFinishedAt, resultExpiresAt, resultFirstFetchedAt, resultLastFetchedAt.
• Removed: Legacy result fields reason, mode, creationTimestamp, releaseTimestamp, retrievalTimestamp. Replacements documented in the Result Validation overview.
• Changed: API endpoint moved to /v2/verifications/{id}/results and uses the standard Authorization: Bearer <apiKey> header. Inside the library this is fully transparent; only relevant for custom REST integrations.
• Changed: PHP — composer/ca-bundle is no longer a required dependency. The system CA store is used by default; if composer/ca-bundle is installed it is picked up automatically. This makes embedding the library into CMS plugins much easier.
• Changed: Go — module path bumped from /v2 to /v3 (github.com/trustcomponent/trustcaptcha-go/v3).
• Changed: Python — module path now trustcaptcha.trust_captcha (was trustcaptcha.captcha_manager).
• Changed: Ruby — file path now trustcaptcha/trust_captcha (was trustcaptcha/captcha_manager).
• Changed: Rust — module path now trustcaptcha::trust_captcha (was trustcaptcha::captcha_manager).

See the Upgrade to v3 guide for migration steps.

• Fixed: Hard-coded the API endpoint inside the libraries to mitigate a server-side request forgery (SSRF) class issue. Previously the endpoint was read from the apiEndpoint field of the verification token.

• TrustCaptcha is now part of TrustComponent
• Changed: Scopes, namespaces and packages migrated to the TrustComponent namespace. Repositories were re-created on Github under github.com/trustcomponent/.
• Changed: API endpoint moved from api.captcha.trustcaptcha.com to api.trustcomponent.com.
• Changed: Encrypted access token in the verification token is no longer required for the result retrieval. Result retrieval now uses a simple REST API call authenticated with an API key (or, for legacy customers, the deprecated secret key).

Releases of the 1.x line predate the migration to TrustComponent and are no longer actively maintained. We recommend upgrading to the latest 3.x release.