Captcha protection

Last updated November 11th at 11:22am

DTC API: Captcha protection#

The DTC API now supports captcha integration to enhance security and prevent malicious activity, such as bot attacks, during user interactions. This feature is particularly useful for endpoints that handle sensitive operations, such as user registration, checkout, voucher application, or other transactional workflows.

How captcha is handled in DTC API responses#

In every GraphQL response, captcha details are included in the extensions section of the response payload. This allows the client to determine when captcha verification is required and what type of captcha to render on the front-end. Here’s an example of how the response structure looks when captcha is enabled:

{
  "data": { ... }
  "extensions": {
    "captcha": {
      "type": "reCAPTCHA_v3",
      "key": "[public site key]",
      "script": "<script src=\"https://www.google.com/recaptcha/api.js?onload=...</script>",
      "verified": false
    },
    "token": "91432ea5-4ddc-cb68-98ad-aa423e9405d6",
    "traceId": "2c77d4eb34f9a5d7c022b7f35f6533b7"
  }
}

Understanding the captcha fields#

The captcha object contains several fields that instruct the frontend how to proceed with captcha verification:

type: Specifies the type of captcha being used. In the example above, it's reCAPTCHA_v3, which provides frictionless, score-based captcha verification.
key: This is the public site key associated with the reCAPTCHA instance.
script: This contains the HTML <script> tags needed to load the captcha providers JavaScript on the client side. The script is necessary for executing the captcha challenge, and contains a callback to the verifyCaptcha mutation.
verified: This boolean flag indicates whether the captcha verification has been successfully completed. If false, it means the client must display the captcha and send the response token back to the server.

Example Usage in Front-End#

To handle captcha in the front-end, follow these steps:

Inject the captcha script provided in the captcha.script field. The execution will happen immediately.
The callback defined in a script sends the collected data (a.k.a captcha token) for verification.
The session is now verified, which is visible as verified: true in the captcha section. Alternatively, you can include the provider’s script and complete the challenge on your own, using provided details (type and key), and then send the result to the verifyCaptcha mutation.

    async function sendMutationBack(captchaToken) {
	    const response = await fetch(API_URL, {
	        method: 'POST',
	        headers: {
	            'Content-Type': 'application/json',
	            'Authorization': 'Bearer ' + SESSION_ID
	        },
	        body: JSON.stringify({
	            query: 'mutation verifyCaptcha($captchaData: String!) {
	                verifyCaptcha(captchaData: $captchaData) {
		              verified
		              userErrors { message, path }
	                }
	            }',
	            variables: {captchaData: captchaToken}
	        })
	    });
	    const body = await response.text();
	    document.dispatchEvent(
	        new CustomEvent('centra_captcha_result', {detail: JSON.parse(body)})
	    );
	}

This is exactly what the captcha.script does. Note the custom event centra_captcha_result triggered when the response is fetched. You can listen to it like this:

document.addEventListener("centra_captcha_result", handler);

Restricted mutations#

When a captcha-protected mutation is attempted, the stored verification result is checked before any other logic is executed. Missing or failed validation causes a response with a "captcha required" error, and the same captcha section with the script to execute.

{
  "errors": [
    {
      "message": "captcha error: captcha required",
      "path": [
        "paymentInstructions"
      ]
    }
  ],
  "data": null,
  "extensions": {
    "captcha": {
      "type": "reCAPTCHA_v3",
      "key": "[public site key]",
      "script": "<script src=\"https://www.google.com/recaptcha/api.js?onload=...</script>",
      "verified": false
    },
    "token": "91432ea5-61dc-cb68-98ad-aa429e9405d6",
    "traceId": "9d5cd285573a0fdce60e3f330733b365"
  }
}

Conclusion#

The captcha integration in the DTC API adds an extra layer of protection against automated threats. By including captcha in the extensions section of the response, the API provides a ready-to-use, non-intrusive mechanism for captcha verification, ensuring a balance between security and user experience. Be sure to handle the run the captcha script to ensure smooth interactions.