reCAPTCHA migration to Google Cloud by the end of 2025: what do you need to do

In case you haven’t received an email from Google (or you haven’t noticed an ugly notification “reCAPTCHA terms are changing” on all of your widgets), reCAPTCHA is moving under the Google Cloud umbrella by the end of 2025. If you haven’t yet migrated, you have about 2 months or less to do so. Google is famous for delegating work to customers and not being backwards-compatible and this transition is not an exception.

Key takeways

• you are required to have a Google Cloud account and billing set up for migration
• all reCAPTCHA tiers now run on Enterprise API (this is reflected in APIs/domains for the widgets/verifications)
• Verification APIs are now called “Assessment” APIs (so instead of verifying client token you now “create an assessment”)
• reCAPTCHA pricing under GCP will be more usage-based than before with 10,000 requests/month free

Step-by-step migration

Administration

1. Google Cloud setup

Create Google Cloud account and setup the billing there.

2. Create a new GCP project and enable reCAPTCHA Enterprise

Now create a new project with a meaninful name.

Search for “reCAPTCHA” in the search bar and click on “reCAPTCHA Enterprise API”:

Finally, enable it:

reCAPTCHA and ‘without creating friction’ used together. Right…

3. Migrate sites from old reCAPTCHA

Login to the old reCAPTCHA admin and click big blue Migrate button on top. You will be taken to the page where you can migrate your sites one by one:

Google states that old statistics data will unlikely be migrated to GCP so only new data will appear there. With some delay.

I love good product names. “reCAPTCHA Express” data will be delayed only for 24 hours. Wonder how much time it takes when it’s not “express”.

Anywas, this should do the administrative part. Now onto coding.

Client side changes

On the client side the changes are fairly minimal:

1. Replace script https://www.google.com/recaptcha/api.js to https://www.google.com/recaptcha/enterprise.js (api.js becomes enterprise.js)
2. Replace usage of grecaptcha global Javascript object to grecaptcha.enterprise

Your sitekey should work, given that you went through administrative migration of the project (above).

Her’s the link to client-side official docs.

Server-side changes

Bad news are that APIs are completely different and you will need to rewrite your code. Good news is that Enterprise reCAPTCHA is part of Google cloud SDKs for Go, C#, Java, Node.js, PHP, Python and Ruby - so very likely you are covered here, at the expense of introducing a new dependency to your project.

Old APIs:

curl -X POST https://www.google.com/recaptcha/api/siteverify \
  -d "secret=${YOUR_SECRET_KEY}" \
  -d "response=${USER_RESPONSE_TOKEN}"

New APIs:

curl -X POST https://recaptchaenterprise.googleapis.com/v1/projects/${PROJECT_ID}/assessments?key=${API_KEY} \
  -d "{
    "event": {
      "token": "${USER_RESPONSE_TOKEN}",
      "siteKey": "${KEY_ID}",
      "userAgent": "${USER_AGENT}",
      "userIpAddress": "${USER_IP_ADDRESS}",
      "expectedAction": "${USER_ACTION}"
    }
  }"

Overall you probably should use an SDK for that as it will be easier than maintaining this mess yourself.

Here’s the link to the official assessment API docs.

Pricing changes

Previously reCAPTCHA pricing could be described as “it’s either free or call-us”. Now, like more GCP products, it has a more well-defined pricing, having 10,000 free requests per month and after that - $8 / 100,000 requests per month. Standard tier caps at 100,000 requests per month and if you need more - you can get an Enterprise tier where beyond first 100,000 requests the pricing is $1 / 1,000 requests.

Benefits

One significant benefit with migration to GCP, except clear pricing, is that now reCAPTCHA can be integrated with Google Cloud Armor (WAF) and you can assign it on various actions on the website (if your website is hosted on GCP, that is). Previously you’d need to engineer your own solution for the same functionality.