> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # authorize # Package: captcha # Namespace: CaptchaService # Method link: https://dev.wix.com/docs/api-reference/business-management/captcha/authorize.md ## Introduction Authorizes a CAPTCHA token. Following CAPTCHA verification on the client side, you must authorize the generated CAPTCHA token in the backend. `Authorize` checks if the token is valid, making sure it was not tampered with or timed out. If you're developing a Wix site or Blocks app, call this method when working with the [Wix reCAPTCHA](https://dev.wix.com/docs/velo/api-reference/$w/captcha/introduction.md) element. If CAPTCHA token authorization fails, the method returns an error message containing a status code. The following table lists the possible HTTP error status codes, based on [RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616#section-10): | Status Code | Name | Description | |---|---|---| | 400 | Bad Request | The request could not be understood by the server. This could occur for a number of reasons, such as: | | 401 | Unauthenticated | No user identity found in passed request. | | 500 | Internal Server Error | The server encountered an unexpected condition, such as a missing or invalid private CAPTCHA key. | | 503 | Unavailable | The service is unavailable due to one of the following: | --- ## REST API ### Schema ``` Method: authorize Description: Authorizes a CAPTCHA token. Following CAPTCHA verification on the client side, you must authorize the generated CAPTCHA token in the backend. `Authorize` checks if the token is valid, making sure it was not tampered with or timed out. If you're developing a Wix site or Blocks app, call this method when working with the [Wix reCAPTCHA](https://dev.wix.com/docs/velo/api-reference/$w/captcha/introduction.md) element. If CAPTCHA token authorization fails, the method returns an error message containing a status code. The following table lists the possible HTTP error status codes, based on [RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616#section-10): | Status Code | Name | Description | |---|---|---| | 400 | Bad Request | The request could not be understood by the server. This could occur for a number of reasons, such as: | | 401 | Unauthenticated | No user identity found in passed request. | | 500 | Internal Server Error | The server encountered an unexpected condition, such as a missing or invalid private CAPTCHA key. | | 503 | Unavailable | The service is unavailable due to one of the following: | URL: https://www.wixapis.com/captcharator/api/v1/authorize Method: POST Method parameters: param name: token | type: token | description: The CAPTCHA token to authorize. Return type: CaptchaResponse - name: success | type: boolean | description: Value is `true` when authorization is successful. - name: errors | type: Errors | description: Error information. - name: errorId | type: integer | description: GUID of error. ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.captcha.CaptchaService.authorize(token) Description: Authorizes a CAPTCHA token. Following CAPTCHA verification on the client side, you must authorize the generated CAPTCHA token in the backend. `Authorize` checks if the token is valid, making sure it was not tampered with or timed out. If you're developing a Wix site or Blocks app, call this method when working with the [Wix reCAPTCHA](https://dev.wix.com/docs/velo/api-reference/$w/captcha/introduction.md) element. If CAPTCHA token authorization fails, the method returns an error message containing a status code. The following table lists the possible HTTP error status codes, based on [RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616#section-10): | Status Code | Name | Description | |---|---|---| | 400 | Bad Request | The request could not be understood by the server. This could occur for a number of reasons, such as: | | 401 | Unauthenticated | No user identity found in passed request. | | 500 | Internal Server Error | The server encountered an unexpected condition, such as a missing or invalid private CAPTCHA key. | | 503 | Unavailable | The service is unavailable due to one of the following: | # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: token Method parameters: param name: token | type: string | description: The CAPTCHA token to authorize. | required: true Return type: PROMISE - name: success | type: boolean | description: Value is `true` when authorization is successful. - name: errors | type: Errors | description: Error information. - name: errorId | type: integer | description: GUID of error. ``` ### Examples ### Full CAPTCHA lifecycle scenario (with $w) This example demonstrates how to use reCAPTCHA to protect a data insertion. We use a text input for the data, a reCAPTCHA element, and a submit button. The submit button is disabled until the CAPTCHA is verified and a token is generated. Clicking the submit button triggers backend authorization of the token. If authorization is successful, the data is inserted into the collection. ```javascript /****************************************** * Backend code - submitHandler.web.js/ts * *****************************************/ import { Permissions, webMethod } from '@wix/web-methods'; import { captcha } from '@wix/captcha'; import { items } from '@wix/data'; export const processSubmission = webMethod(Permissions.Anyone, (submitRequestData) => { return captcha.authorize(submitRequestData.token) .then((response) => { if (response.success) { return items.insert("MyCollection", submitRequestData.data) .then(() => ({ "type": "success" })) .catch((error) => ({ "type": "insertion error", "message": "Error: collection insertion failed: " + error })); } else { return { "type": "authorization error", "message": "Error: CAPTCHA authorization failed." }; } }) .catch((error) => ({ "type": "authorization error", "message": "Error: CAPTCHA authorization failed: " + error })); }); /******************** * Client-side code * ********************/ import { processSubmission } from 'backend/submitHandler.web'; $w.onReady(function () { // When user clicks submit button $w("#submitDataButton").onClick(() => { let submitRequestData = { token: $w("#myCaptcha").token, data: $w("#myInput").value, } processSubmission(submitRequestData) // Call backend function .then((response) => { // Display a different message depending on response from backend function switch (response.type) { case "success": $w("#messageText").text = "Data successfully submitted"; break; case "authorization error": $w("#messageText").text = "CAPTCHA authorization failed. Redo the CAPTCHA challenge."; break; case "insertion error": $w("#messageText").text = "Database error. Redo the CAPTCHA challenge."; break; } $w("#myCaptcha").reset(); $w("#submitDataButton").disable(); $w("#messageText").show(); }); }); // Error handler $w("#myCaptcha").onError(() => { $w("#messageText").text = "The reCAPTCHA element lost connection with the CAPTCHA provider. Try again later."; $w("#messageText").show() .then(() => { $w("#messageText").hide("fade", { "delay": 10000 }); }); }) // Verification handler $w("#myCaptcha").onVerified(() => { $w("#submitDataButton").enable(); $w("#messageText").hide(); }) // Timeout handler $w("#myCaptcha").onTimeout(() => { $w("#submitDataButton").disable(); $w("#messageText").text = "The CAPTCHA has timed out. Please redo the CAPTCHA challenge."; $w("#messageText").show(); }); }); ``` ### authorize (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { captcha } from '@wix/captcha'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { captcha }, // Include the auth strategy and host as relevant }); async function authorize(token) { const response = await myWixClient.captcha.authorize(token); }; ``` ---