This page explains how to migrate from reCAPTCHA to reCAPTCHA Enterprise. This assumes you already have a site that is instrumented to generate tokens using reCAPTCHA v2 or v3.
Before you begin
-
Sign in to your Google Account.
If you don't already have one, sign up for a new account.
-
In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
- Enable the reCAPTCHA Enterprise API.
Keys
You must create new keys. These keys will replace any Site Keys you created in reCAPTCHA. The table below describes the mappings from reCAPTCHA keys to reCAPTCHA Enterprise keys:
reCAPTCHA | reCAPTCHA Enterprise |
---|---|
reCAPTCHA v2 Checkbox | CHECKBOX |
reCAPTCHA v2 Invisible | INVISIBLE |
reCAPTCHA v3 | SCORE |
Web page instrumentation
You should already have this script included in some of your pages:
https://www.google.com/recaptcha/api.js
.
- Change the
api.js
component toenterprise.js
. - Replace calls to
grecaptcha.execute
withgrecaptcha.enterprise.execute
. - Update the
site key
parameter to point to the new key.
API Request
You must replace the backend call to https://www.google.com/recaptcha/api/siteverify
with one to https://recaptchaenterprise.googleapis.com
. The fastest way to
migrate the backend call is to use the v1beta
API, outlined below.
Before using any of the request data below, make the following replacements:
- API_KEY: API key associated with the current project
- project-id: your GCP project ID
- token: token returned from the `grecaptcha.enterprise.execute()` call
- key: reCAPTCHA Key associated with the site/app
HTTP method and URL:
POST https://recaptchaenterprise.googleapis.com/v1beta1/projects/project-id/assessments?key=API_KEY
Request JSON body:
{ "event": { "token": "token", "siteKey": "key" } }
To send your request, choose one of these options:
curl
Save the request body in a file called 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/v1beta1/projects/project-id/assessments?key=API_KEY
PowerShell
Save the request body in a file called 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/v1beta1/projects/project-id/assessments?key=API_KEY" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "homepage", "createTime": "2019-03-28T12:24:17.894Z" }, "score": 0.1, "reasons": ["AUTOMATION"], "event": { "token": "token", "siteKey": "key" }, "name": "projects/project-id/assessments/b6ac310000000000" }
What's next
- Learn how to interpret an assessment.
- Learn how to use the v1 Assessment API.