Search.../

authorize( )

Authorizes the CAPTCHA token.

Description

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.

The authorize() function returns a Promise that resolves to a Success object when the token is authorized and to an Error object when authorization fails.

To understand how authorize() is used in a typical CAPTCHA validation lifecycle, click here.

If CAPTCHA token authorization fails, an error message containing a status code is returned. The following table lists the possible HTTP error status codes, based on RFC 2616:

Status CodeNameDescription
400Bad RequestThe request could not be understood by the server. This could occur for a number of reasons, such as:
  • The request was sent without a token.
  • The token is invalid.
  • The token has timed out.
401UnauthenticatedNo user identity found in passed request.
500Internal Server ErrorThe server encountered an unexpected condition, such as a missing or invalid private CAPTCHA key.
503UnavailableThe service is unavailable due to one of the following:
  • Throttled error: Server overload due to more than the allowed requests in a given time frame.
  • Request failed: No response following 10 retries with a 1-second interval.

Syntax

function authorize(token: string): Promise<SuccessReport>

authorize Parameters

NAME
TYPE
DESCRIPTION
token

string

The CAPTCHA token to authorize.

Returns

Fulfilled - A success message. Rejected - An error message.

Return Type:

Promise<SuccessReport>
NAME
TYPE
DESCRIPTION
success

boolean

Value is true when authorization is successful.

Related Content:

Was this helpful?

Full CAPTCHA lifecycle scenario

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.

Code Example

Copy Code
1/************************************
2 * Backend code - submitHandler.jsw *
3 ************************************/
4
5import wixCaptchaBackend from 'wix-captcha-backend';
6import wixData from 'wix-data';
7
8// Authorize token and insert data
9export function processSubmission(submitRequestData) {
10 return wixCaptchaBackend.authorize(submitRequestData.token)
11 .then(() => {
12 return wixData.insert("MyCollection", submitRequestData.data)
13 .then(() => ({ "type": "success" }))
14 .catch((error) => ({ "type": "insertion error", "message": "Error: collection insertion failed: " + error }));
15 })
16 .catch((error) => ({ "type": "authorization error", "message": "Error: CAPTCHA authorization failed: " + error }));
17}
18
19
20/********************
21 * Client-side code *
22 ********************/
23
24import { processSubmission } from 'backend/submitHandler';
25
26$w.onReady(function () {
27 // When user clicks submit button
28 $w("#submitDataButton").onClick(() => {
29 let submitRequestData = {
30 token: $w("#myCaptcha").token,
31 data: $w("#myInput").value,
32 }
33 processSubmission(submitRequestData) // Call backend function
34 .then((response) => {
35 // Display a different message depending on response from backend function
36 switch (response.type) {
37 case "success":
38 $w("#messageText").text = "Data successfully submitted";
39 break;
40 case "authorization error":
41 $w("#messageText").text = "CAPTCHA authorization failed. Redo the CAPTCHA challenge.";
42 break;
43 case "insertion error":
44 $w("#messageText").text = "Database error. Redo the CAPTCHA challenge.";
45 break;
46 }
47 $w("#myCaptcha").reset();
48 $w("#submitDataButton").disable();
49 $w("#messageText").show();
50 });
51 });
52
53 // Error handler
54 $w("#myCaptcha").onError(() => {
55 $w("#messageText").text = "The reCAPTCHA element lost connection with the CAPTCHA provider. Try again later.";
56 $w("#messageText").show()
57 .then(() => {
58 $w("#messageText").hide("fade", { "delay": 10000 });
59 });
60 })
61
62 // Verification handler
63 $w("#myCaptcha").onVerified(() => {
64 $w("#submitDataButton").enable();
65 $w("#messageText").hide();
66 })
67
68 // Timeout handler
69 $w("#myCaptcha").onTimeout(() => {
70 $w("#submitDataButton").disable();
71 $w("#messageText").text = "The CAPTCHA has timed out. Please redo the CAPTCHA challenge.";
72 $w("#messageText").show();
73 });
74});
75