This topic describes how to integrate CAPTCHA with a server by making native HTTPS calls.
To make native HTTPS calls, you must manually generate and verify signatures and assemble the request, which includes the URL, body, header, and parameters. If you do not have special business requirements, we recommend that you use a software development kit (SDK) to call CAPTCHA. For more information, see Server-side integration.
Basic information
Endpoint: https://captcha.ap-southeast-1.aliyuncs.com
Request method: POST
Transmission protocol: HTTPS
Request parameters
Request parameters include common parameters and operation-specific parameters. Common parameters include the API version number and authentication information.
Common parameters:
Name
Type
Required
Description
Example
x-acs-action
String
Yes
The name of the API.
The operation to perform. Set the value to VerifyIntelligentCaptcha.
x-acs-version
String
Yes
The version of the API.
The API version number. Use the YYYY-MM-DD format. Set the value to 2023-03-05.
Authorization
String
Required for non-anonymous requests
The authentication information used to verify the validity of the request. Format: Authorization: SignatureAlgorithm Credential=AccessKeyId,SignedHeaders=SignedHeaders,Signature=Signature.
SignatureAlgorithm specifies the signature encryption method. The value is ACS3-HMAC-SHA256.
Credential specifies your AccessKey ID. You can view your AccessKey ID in the Resource Access Management (RAM) console. To create an AccessKey pair, see Create an AccessKey pair.
SignedHeaders specifies the key names of the request headers that are included in the signature. For improved security, include all common request headers except for Authorization in the signature.
Signature is the request signature. For information about the value, see the Signature mechanism section.
ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature=e521358f7776c97df52e6b2891a8bc73026794a071b50c3323388c4e0df64804
x-acs-signature-nonce
String
Yes
A unique random number for the signature. This number prevents replay attacks. Each request must use a different random number.
d410180a5abf7fe235dd9b74aca91fc0
x-acs-date
String
Yes
The time of the request in UTC. The time must follow the ISO 8601 standard and be in the yyyy-MM-ddTHH:mm:ssZ format. Example: 2018-01-01T12:00:00Z. The time must be within 15 minutes before you send the request.
2023-10-26T09:01:01Z
host
String
Yes
The endpoint. For more information, see HTTP request syntax.
captcha.cn-shanghai.aliyuncs.com
x-acs-content-sha256
String
Yes
The hash value of the request body. The hash value is encoded in Base16. The value of this parameter is the same as the value of the HashedRequestPayload parameter.
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-security-token
String
Required if you use Security Token Service (STS) for authentication
The STS token. Set this parameter to the value of the SecurityToken parameter in the response of the AssumeRole operation.
Submit the API request parameters in the request body in the application/x-www-form-urlencoded format:
Name
Type
Required
Description
Example
CaptchaVerifyParam
String
Yes
The verification parameters that are returned by the CAPTCHA script in callback mode. Pass all parameters that are obtained from the business client to the business server.
WarningDo not modify the verification parameters. Otherwise, a service error occurs.
V2 architecture example: {"sceneId":"xxxxxx","certifyId":"xxxxxx","deviceToken":"xxxxxxx==","data":"xxxxxx==","..."}
V3 architecture example: eyJjZXxxxxxxxxxxxxxxnVlfQ==
SceneId
String
No
The scenario ID of the verification request. We recommend that you specify this parameter. This prevents the verification request in this scenario from being confused with that in other scenarios.
Udw***d72
Signature mechanism
CAPTCHA authenticates each API request. You must include a signature (Signature) in your requests.
CAPTCHA verifies the identity of a request sender using symmetric encryption with an AccessKey ID and an AccessKey secret. An AccessKey pair is an identity credential for an Alibaba Cloud account or a RAM user and is similar to a logon password. The AccessKey ID identifies the user, and the AccessKey secret is used to encrypt and verify the signature string. Keep your AccessKey secret strictly confidential. For more information, see V3 signature mechanism.
Return parameters
Name | Type | Description | |||
HTTP Status Code | Integer | The HTTP status code that is returned. For more information, see Response parameter description. | |||
HTTP Body | RequestId | String | The request ID. | ||
Success | Boolean | Indicates whether the request was successful. Valid values:
| |||
Code | String | The return code. For more information, see Response parameter description. | |||
Message | String | The response parameters. For more information, see Response parameter description. | |||
Result | VerifyResult | Boolean | The verification result.
| ||
VerifyCode | String | T001 | The server-side verification is passed. | ||
T005 | The test mode is enabled in the console, and the configuration is verified. If you have questions, log on to the Captcha 2.0 console to view the policy status configuration for the corresponding scenario. For more information, see Access guide. | ||||
F001 | The request may be an attack request and fails the verification of the risk policy. If you have questions, you can submit a ticket for troubleshooting. | ||||
F002 | The | ||||
F003 | The format of the | ||||
F004 | The test mode is enabled in the console, and the configuration is verified. If you have questions, log on to the Captcha 2.0 console to view the policy status configuration for the corresponding scenario. For more information, see Scenario management. | ||||
F005 | The scenario ID specified by the sceneId field of the CaptchaVerifyParam parameter is invalid. The CaptchaVerifyParam parameter is automatically obtained by the frontend and passed to your server. The server directly passes the parameter to Alibaba Cloud without making any changes. For more information, see Server-side integration to check your integration code. | ||||
F006 | The scenario ID specified by the sceneId field of the | ||||
F008 | The verification data already exists. The verification code request can be submitted only once. | ||||
F009 | A virtual device environment is detected. Check whether simulated devices are used. Simulated devices include virtual machines such as VMware, VirtualBox, Hyper-V, Parallels, simulators such as AVD, BlueStacks, VirtualBox, and Hyper-V, and mobile browser simulators. If you do not need to block these devices, log on to the Captcha 2.0 console and disable this feature in the custom policy. For more information, see Configure custom policies. | ||||
F010 | The number of requests from the same IP address exceeds the limit. If you want to customize the frequency threshold, log on to the Captcha 2.0 console and configure the custom policy. For more information, see Configure custom policies. | ||||
F011 | The number of requests from the same device exceeds the limit. If you want to customize the frequency threshold, log on to the Captcha 2.0 console and configure the custom policy. For more information, see Configure custom policies. | ||||
F012 | The value of the sceneID field that you specify during the configuration of server parameters must be consistent with the value of the SceneId parameter that is specified during the frontend configuration. | ||||
F013 | One or more parameters are missing from the | ||||
F014 | No initialization records exist. The following list describes the possible causes:
| ||||
F015 | The verification interaction is not passed. For example, the puzzle is not moved to the correct position. You can refresh the CAPTCHA to complete the interaction again. | ||||
F016 | The URL verification configured in the custom policy in the console causes the verification to fail. Log on to the Captcha 2.0 console and adjust the URL verification policy in the custom policy. For more information, see Configure custom policies. | ||||
F017 | The request may be an attack request. The protocols or parameters are abnormal. | ||||
F018 | In the V3 architecture, the CaptchaVerifyParam parameter in the business signature verification request is reused. | ||||
F019 | In the V3 architecture, the interval between the behavior verification request and the business signature verification request exceeds 90 seconds, or the business signature verification request is initiated without initiating the behavior verification request. | ||||
F020 | In the V3 architecture, the CaptchaVerifyParam parameter in the business signature verification request does not match the scenario ID or user. | ||||
The following table describes the HTTP Status Code, Code, and Message response parameters.
HTTP Status Code | Code | Message |
200 | Success | Success. |
400 | MissingParameter | One or more required parameters are not specified. |
401 | InvalidParameter | The parameter is invalid. |
403 | Forbidden.AccountAccessDenied | You do not have the required permissions. The service may not be activated, or your account may have overdue payments. |
403 | Forbidden.RAMUserAccessDenied | The RAM user does not have the required permissions. Grant the AliyunYundunAFSFullAccess permission to the RAM user. For more information, see Grant permissions to a RAM role. |
500 | InternalError | An internal error has occurred. Try again later. If the error persists, submit a ticket to contact us. |
Sample response:
{
"RequestId": "3F290236-C***B-54F31BD999FF",
"Message": "success",
"Code": "Success",
"Success": true,
"Result": {
"VerifyResult": true,
"VerifyCode": "T001"
}
}Exception handling:
To ensure service availability, if a request fails or a network error occurs when you call this operation, log the event and assume that the verification passed by default. This approach prioritizes your service availability. Then, contact us as soon as possible to investigate the cause of the error.