This document shows you how to set up reCAPTCHA express on an application server in an environment where integration of the reCAPTCHA JavaScript or mobile SDK is not feasible, for example, protection for API endpoints.
reCAPTCHA express is a feature that lets you create assessments without the client-side features. reCAPTCHA express uses only backend signals to generate a reCAPTCHA risk score. You can use this risk score to decide whether to serve the request, redirect to a challenge page, or log it for later analysis.
Before you begin
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Record your Google Cloud project ID for later use.Make sure that billing is enabled for your Google Cloud project.
Enable the reCAPTCHA Enterprise API.
Create an API key for authentication:
In the Google Cloud console, go to the Credentials page.
Click
Create credentials, and then select API key.Record the API key for later use.
Create a reCAPTCHA express key
To implement reCAPTCHA express, create a reCAPTCHA express key.
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
gcloud
To create reCAPTCHA keys, use the gcloud recaptcha keys create command.
Before using any of the command data below, make the following replacements:
- DISPLAY_NAME: Name for the key. Typically a site name.
Execute the gcloud recaptcha keys create command:
Linux, macOS, or Cloud Shell
gcloud recaptcha keys create \ --express \ --display-name=DISPLAY_NAME
Windows (PowerShell)
gcloud recaptcha keys create ` --express ` --display-name=DISPLAY_NAME
Windows (cmd.exe)
gcloud recaptcha keys create ^ --express ^ --display-name=DISPLAY_NAME
The response contains the newly created reCAPTCHA key.
REST
For API reference information about key types and integration types, see Key and Integration type.Before using any of the request data, make the following replacements:
- DISPLAY_NAME: Name for the key. Typically a site name.
HTTP method and URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys
Request JSON body:
{ "displayName": "DISPLAY_NAME", "expressSettings": {} }
To send your request, choose one of these options:
curl
Save the request body in a file named
request.json
, and execute the following command:curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"PowerShell
Save the request body in a file named
request.json
, and execute the following command:$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand ContentYou should receive a JSON response similar to the following:
{ "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m", "displayName": "DISPLAY_NAME, "expressSettings": { } }
Record your express key for later use.
Create an assessment
To make a request from your application server to reCAPTCHA,
create an assessment using the projects.assessments.create
method.
Before using any of the request data, make the following replacements:
- API_KEY: The API key that you created for the authentication.
- EXPRESS_KEY: reCAPTCHA express key that you created for your application.
- USER_IP_ADDRESS: The IP address in the request from the user's device related to this event.
- HEADER_INFO: Optional. The HTTP headers that the client sent to your application server. It is a string array that contains request headers in the `[key:value]` format. For example, `[key:value, key:value,...]`. We recommend that you share as many headers as possible in the required order. Ensure that the order of the headers is consistent across all requests in the same session.
- JA3_FINGERPRINT: Optional. JA3 is an MD5 fingerprint of certain fields of the TLS client hello packet. For more information, see JA3 - A method for profiling SSL/TLS Clients.
- URI_NAME: Optional. The URI that is being accessed by the user.
- USER_AGENT: Optional. The user agent that is present in the request from the user's device related to this event.
- ACCOUNT_ID: Optional. A unique and persistent identifier for the user's account, such as a hashed account name.
HTTP method and URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
Request JSON body:
{ "event": { "siteKey": "EXPRESS_KEY", "express": true, "userIpAddress": "USER_IP_ADDRESS", "headers": ["HEADER_INFO"], "ja3": "JA3_FINGERPRINT", "requestedUri": "URI_NAME", "userAgent": "USER_AGENT", "user_info": { "account_id": "ACCOUNT_ID" } } }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$headers = @{ }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/123456789/assessments/abcdef1234000000", "event": { "token": "", "siteKey": "6L...", "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36", "userIpAddress": "1.2.3.4", "express": true, "requestedUri": "https://example.com/", "firewallPolicyEvaluation": false, "user_info": { "account_id": "123456789" }, "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"], }, "riskAnalysis": { "score": 0.7, "reasons": [] } }
Interpret scores
reCAPTCHA express returns only two scores: 0.3
and 0.7
.
0.3
indicates that the user interaction poses more risk and is likely fraudulent,
and 0.7
indicates that the user interaction poses low risk and is likely
legitimate.
If there are lack of signals, then reCAPTCHA express returns 0.7
by default.
What's next
- Learn about how to interpret risk scores.
- Learn about how to use reCAPTCHA express at the WAF layer.