reCAPTCHA Enterprise in Google Cloud: Telling Real Users from Bots and Fraudsters
A complete, plain-English guide to reCAPTCHA Enterprise: how it scores every visitor, how tokens and assessments work, how to stop fake accounts, stolen passwords, card testing and scraping, and how to design a protection plan that blocks attackers without annoying genuine customers.
Picture a popular concert hall with one front door and thousands of people queuing outside. Most are genuine fans with tickets. A few are touts who send hundreds of helpers to buy every seat and resell them, and a few are pickpockets who work the crowd. A single security guard who stops everyone and asks identical questions would slow the real fans and still be fooled by clever touts. A wiser guard watches how people behave: who rushes in too fast, who comes back again and again with different faces, who carries a list of stolen tickets. That guard waves most people through without a word, asks a few for extra proof, and turns the rest away. reCAPTCHA Enterprise is that watchful guard for your website and mobile app.
This guide assumes you know nothing about the topic. We explain every new word, give everyday comparisons, and build from the basic idea to production-grade practice. By the end you will understand what a site key and a token are, how an assessment produces a score, how to choose a sensible threshold, how to stop account takeover, fake sign-ups and card testing, how to protect mobile apps, how to keep the system accurate over time, and which mistakes let attackers slip through.
1What reCAPTCHA Enterprise Is and Why It Exists
reCAPTCHA Enterprise is a Google Cloud service that tells you how likely it is that a visitor or an action is a real person and not a bot or a fraudster.
The problem it solves
Every public website attracts unwanted visitors. A bot is a program that acts like a person, only much faster and in huge numbers. Some bots are helpful, such as the crawlers that let search engines find your pages. Many are harmful: they create thousands of fake accounts, try stolen passwords on your login page, copy your product prices, post spam in comment boxes, or test stolen credit card numbers on your checkout. Fraud is the wider word for these dishonest uses of your service, and some of it is carried out by real humans, not just programs.
The old way to fight this was to show every visitor a puzzle, such as typing distorted letters. That annoyed real customers, was hard for people with disabilities, and modern programs learned to solve the puzzles anyway. A better approach is to judge visitors quietly in the background and ask for proof only when something looks suspicious.
Think of an airport. Most travellers pass through with a quick glance because their documents and behaviour look normal. A few are pulled aside for extra checks because something does not add up. Nobody wants every passenger strip-searched. reCAPTCHA Enterprise brings that risk-based approach to your website.
What the service actually does
The service watches how a visitor interacts with your page or app and combines that with signals gathered from across the internet. When you ask, it returns a risk score, a number between zero and one that says how likely the visitor is to be a genuine person. A score near one means very likely human; a score near zero means very likely a bot. It also returns reason codes that explain why a score is low. Your own server then decides what to do: allow the action, ask for extra verification, slow the visitor down, or block them.
Beyond simple bot detection, the enterprise version adds protections for specific harms: account takeover, fake account creation, leaked passwords, text-message abuse, and payment fraud. It is a managed service, so there are no detection servers for you to run or tune from scratch.
The service gives you a judgment, not a verdict. It never blocks anyone by itself in a plain integration. You stay in control of what happens at each risk level, which is why good design of your reaction matters as much as the detection.
2Where It Fits in the Google Cloud Family
reCAPTCHA Enterprise is one layer in a defence that also includes your network edge, your identity system and your monitoring tools.
Cloud Armor
Google’s edge protection and web application firewall. It can work with reCAPTCHA Enterprise to judge traffic before it reaches your application.
Identity and Access Management
Decides which people and programs may create keys, request assessments and read results.
Identity Platform and sign-in systems
Your login and sign-up flows are the most common places to call reCAPTCHA Enterprise.
Cloud Logging and Monitoring
Record your own application’s decisions and alert on unusual patterns, adding context to what the service reports.
Secret Manager
A safe place for the credentials your server uses when it calls the service.
Your application and payment systems
The place where scores are turned into decisions, and where outcomes are sent back as feedback.
A shopping centre has a perimeter fence (Cloud Armor), a staff badge system (IAM), a guard at each shop entrance (reCAPTCHA Enterprise), a camera room (logging and monitoring) and a safe for cash (Secret Manager). Each does one job, and together they protect the building better than any one alone.
reCAPTCHA Enterprise versus a firewall
A firewall looks at network traffic: addresses, request rates and patterns that match known attacks. It is excellent at blocking floods and known exploits. reCAPTCHA Enterprise looks at the visitor: is this a real person using a real browser or app, and does this action look natural? The two complement each other. A firewall can stop ten thousand identical requests per second, while reCAPTCHA Enterprise can notice that a slow, polite stream of requests from many addresses is actually one scripted attacker.
reCAPTCHA Enterprise versus your own rate limits
Rate limits cap how often one address or account may act. They are simple and useful, but attackers spread their traffic across thousands of addresses to stay under the cap. The risk score helps because it is based on behaviour and shared knowledge of attacks, not only on counting requests from one source.
flowchart LR
V["Visitor"] --> E["Edge protection such as Cloud Armor"]
E --> A["Your web app or mobile app"]
A -->|"Execute with site key"| R["reCAPTCHA Enterprise"]
R -->|"Token"| A
A -->|"Token to your server"| S["Your backend"]
S -->|"Create assessment"| R
R -->|"Score and reasons"| S
S --> D["Allow, challenge or block"]
3Core Concepts and Vocabulary
A small set of words unlocks the whole service.
Site Key
A public identifier for one of your websites or apps. It is placed in your page and tells the service which of your properties is calling.
Token
A short-lived, single-use code that the page or app receives after the service observes the visitor. It is the visitor’s evidence slip.
Assessment
A request your backend makes to ask the service what it thinks of a token. The reply contains the score and reasons.
Score
A number from zero to one. Higher means more likely a real person, lower means more likely a bot.
Action
A name you give to the thing the visitor is doing, such as login or checkout. Scores are judged in the context of the action.
Reason Code
A label explaining why a score is low, such as automation or unusual traffic. It guides your response.
Challenge
An extra test, such as a checkbox or image puzzle, shown only when more proof is wanted.
Annotation
Feedback you send back after the fact, saying whether an assessed event turned out to be legitimate or fraudulent.
Account Defender
An add-on capability that learns what normal activity looks like for each account and flags takeovers and fake accounts.
Credential Stuffing
An attack where stolen username and password pairs from one breach are tried on many other sites.
At a cinema, the site key is the name of the cinema printed on the door. The token is the wristband a guard gives you after watching you at the entrance. The assessment is the ticket office phoning the head guard to ask “is this wristband genuine and what do you think of this person?”. The score is the head guard’s answer, and the challenge is the extra question asked if the answer is “not sure”.
The site key is public and harmless to expose. The credentials your backend uses to create assessments are private and must never appear in a web page or mobile app. Mixing these two up is a classic beginner error.
4Key Types: Choosing How Visitors Are Checked
The type of key you create decides what the visitor sees and how the check runs.
Every integration starts with creating a key for your property. The key type is chosen at creation and shapes the whole experience. There are several families, and each has a clear job.
| Key type | What the visitor sees | Typical use |
|---|---|---|
| Score-based key | Nothing, the check runs invisibly | Login, sign-up, checkout, forms, any action where you want a risk number |
| Checkbox key | An “I am not a robot” box, sometimes followed by a puzzle | Places where you want a visible gate |
| Mobile key | Nothing, runs inside the app through a software kit | Android and iOS applications |
| Firewall or edge key | Possibly a challenge page issued at the edge | Protecting traffic through supported firewall and edge providers |
| Lightweight express key | Nothing, simplified setup with limited features | Quick, basic protection where deep features are not needed |
Score-based keys: the quiet default
Score-based keys are the most common choice. Your page asks the service to observe the visitor while they act, and gets back a token. Your server then asks for the score. Because the visitor sees no puzzle, the experience is smooth. You decide the thresholds and responses yourself, so this key type is the most flexible.
Checkbox keys: a visible gate
Checkbox keys show a small box that visitors click. Often a click is enough; when the service is unsure it may show an image puzzle. Choose this when you prefer a visible step, for example on a contact form that is flooded with spam and where one extra click is acceptable.
Mobile keys
Apps cannot run the web script, so there is a software kit for Android and iOS that gathers the app’s signals and returns a token in the same way. A mobile key is tied to the identity of your app, such as its package name or bundle identifier, so that tokens created by copycat apps are rejected.
Edge and firewall keys
Some keys are designed to work with a firewall or content delivery service. The edge component installs a special token on visitors and evaluates traffic before it reaches your servers. Google Cloud Armor offers a tight integration, and some third-party edge providers are supported as well. Check the current documentation for supported providers and features.
A score-based key is a store detective in plain clothes. A checkbox key is a uniformed guard at the door who asks you to sign in. A mobile key is a guard who works inside your private members’ app. An edge key is a guard at the car park gate who checks vehicles long before they reach the shop.
flowchart TD
Q1{"Is the visitor using a mobile app?"}
Q1 -->|Yes| M["Create a mobile key"]
Q1 -->|No| Q2{"Do you want to judge traffic at the edge before your servers?"}
Q2 -->|Yes| ED["Create an edge or firewall key"]
Q2 -->|No| Q3{"Prefer an invisible check with full control over reactions?"}
Q3 -->|Yes| SC["Create a score-based key"]
Q3 -->|No| CB["Create a checkbox key"]
Using one key for every page and every environment makes your data muddy. Create separate keys for production and testing, and ideally separate keys for very different parts of your product, so that scores and settings can be tuned independently.
5Architecture and Components
Four parties take part in every check: the visitor’s device, the service, your backend, and your decision logic.
Although reCAPTCHA Enterprise is fully managed, it helps to picture its parts. Each plays a distinct role, and errors usually come from misunderstanding who does what.
The client side
A script on your web page, or a software kit inside your mobile app, watches how the visitor behaves and gathers signals about the device and the environment.
The Google service
It receives those signals, compares them with patterns learned across a huge number of sites, and issues a token that stands for the observation.
Your backend
It receives the token along with the visitor’s request, and calls the assessment interface to learn the score and reasons. This call must come from a trusted server, never from the visitor’s device.
Your decision logic
Rules in your code turn the score into an action: let the request pass, require extra verification, slow it down, or deny it.
The feedback loop
After the outcome is known, such as a confirmed fraud or a successful second verification, your system tells the service, which helps tune its judgments for your site.
Imagine an exam hall. The invigilator at the desk (client side) notes how each student behaves. A central examination board (the service) holds knowledge of cheating patterns. The school office (your backend) phones the board when it needs advice. The headteacher (your decision logic) decides who is allowed to continue, and the final report to the board about who really cheated (feedback) makes tomorrow’s advice sharper.
Why the backend call is non-negotiable
The token that reaches your server came through the visitor’s device, and an attacker controls that device. A token alone proves nothing until your server verifies it with the service. If your code skips this step, or trusts a client who says “I passed”, then attackers can simply claim success. The server-side assessment is the only trusted moment in the whole flow.
Never make the assessment call from a web page or mobile app. The credentials for that call would be exposed to attackers, and the result could be forged. Always call from your own server with protected credentials.
flowchart LR
subgraph Client["Visitor side"]
PG["Web page or mobile app"]
end
subgraph Google["Google Cloud"]
RE["reCAPTCHA Enterprise"]
end
subgraph Yours["Your environment"]
BE["Backend service"]
DL["Decision rules"]
FB["Feedback sender"]
end
PG -->|"Signals"| RE
RE -->|"Token"| PG
PG -->|"Request with token"| BE
BE -->|"Assessment request"| RE
RE -->|"Score and reasons"| BE
BE --> DL
DL --> FB
FB -->|"Annotation"| RE
6Internal Working: One Visitor, Start to Finish
Follow a single login attempt through every step.
Let us trace a real example. A visitor opens your login page, types an email and password, and presses the button. Here is what happens behind the scenes.
The page loads the script
When the page opens, it loads the reCAPTCHA Enterprise script with your site key. From this moment the service starts learning how the visitor interacts: movement, timing, and the nature of the environment.
The visitor presses the button
Just before the form is sent, your page asks the script to execute and tells it the action name, for example login.
A token is created
The service returns a token within a short moment. The page puts that token into the form data it sends to your server.
Your server asks for an assessment
Before checking the password, the server calls the service with the token, the site key, and the action it expects.
The service evaluates
It checks that the token is valid, fresh, unused, issued for your site and the expected action, and then produces a score with reasons.
Your server decides
A high score lets the login continue. A middle score may trigger a second factor. A very low score may be refused or delayed.
Feedback follows
Later, the outcome, such as a correct password and successful second verification, is sent back as an annotation to help improve accuracy.
sequenceDiagram
participant U as Visitor
participant P as Web page
participant R as reCAPTCHA Enterprise
participant S as Your server
U->>P: Open login page
P->>R: Load script with site key
U->>P: Press sign in
P->>R: Execute with action login
R-->>P: Token
P->>S: Credentials and token
S->>R: Create assessment with token
R-->>S: Validity, score, reasons
S->>S: Apply decision rules
S-->>P: Allow, challenge or deny
S->>R: Later send annotation
Ask for the token as close as possible to the moment of the real action, and send it to your server immediately. Tokens are short-lived and can be used only once, so a token created too early, or reused, will be rejected.
Some teams load the script only on the login page and nowhere else. The service learns better when it can watch behaviour across more of your site, so loading it widely on your pages usually improves accuracy, as long as you respect your privacy rules.
7Tokens, Actions and the Assessment Response
Reading the reply correctly is the difference between real protection and a false sense of security.
The life of a token
A token is a short-lived code. It is valid for only a couple of minutes, and it can be assessed only once. If your server tries to use the same token a second time, or uses an expired token, the service reports it as invalid. This protects against attackers who record a good token and replay it later.
What comes back in an assessment
An assessment response has several parts, and a careful server reads all of them, not just the score.
Token properties
Whether the token is valid, why it is invalid if not, which action it was created for, which site it belongs to and when it was made.
Risk analysis
The score and the list of reason codes. This is the core judgment.
Event details
The site key and the expected action you supplied, echoed back for checking.
Assessment name
A unique identifier of this assessment, which you keep so you can send feedback about it later.
A passport check at a border involves more than looking at the photo. The officer confirms the passport is genuine (token valid), not expired (fresh), issued by the right country (right site), and that the traveller’s stated reason matches the visa (right action). Only after those checks does the officer weigh the risk (score).
Always check these four things
Is the token valid?
If not, treat the request as suspicious or ask the visitor to try again. Never read a score from an invalid token.
Does the action match?
If the token was created for a different action than the one your server expected, an attacker may be reusing a token from an easier page.
Is the site correct?
Make sure the token was issued for your own site and key, not for someone else’s.
Only then, read the score and reasons
Apply your thresholds and include the reason codes in your decision and in your logs.
Problem
The server reads only the score and ignores token validity and the action name.
Why It’s Harmful
An attacker can present a token created for a harmless page and use it on a sensitive one, or replay an old token. The score may then look healthy even though the token proves nothing about the current action.
Correct Approach
Check validity, action, site and freshness first, and read the score only if all of them pass.
8Scores, Reason Codes and Choosing Thresholds
The score is a risk dial, and where you set the line decides how many customers you annoy and how many attackers you stop.
What a score means
Scores run from zero to one. One means the interaction looks very much like a genuine person, and zero means it looks very much like a bot. By default the service returns a small number of distinct score levels, and a finer-grained option exists for organisations that need more detail. Check the current documentation for what your chosen tier returns, because the number of levels affects how precisely you can tune.
Reason codes
A low score comes with reasons that explain the suspicion. These help you choose the right response and help your team investigate.
| Reason idea | What it suggests | Sensible response |
|---|---|---|
| Automation | Signs that a program, not a person, is driving the page | Block or require strong proof |
| Unexpected environment | The device or browser looks unusual or tampered with | Add an extra check |
| Too much traffic | Unusual volume from the same source or pattern | Slow down and limit |
| Unexpected usage patterns | Behaviour that differs from normal use of your site | Review and add friction |
| Low confidence | The service does not have enough information to be sure | Use a gentle challenge instead of blocking |
| Suspected carding | Pattern consistent with testing stolen card numbers | Block the payment attempt and review |
A doctor takes your temperature and also notes the symptoms. A temperature alone says “unwell”, but the symptoms tell the doctor what to do. The score is the temperature and the reason codes are the symptoms. Good decisions use both.
Choosing your thresholds
There is no perfect number for everyone. A common starting point is a middle value, and teams then tune from real traffic. A free-form comment box can tolerate a stricter line because a lost message costs little. A checkout form needs a gentler line combined with extra checks, because blocking a real customer costs money. Use the dashboard distribution of scores for your own traffic to see how many visitors fall into each range, and move the line gradually.
flowchart TD
S["Assessment returned"] --> V{"Token valid and action matches?"}
V -->|No| B1["Treat as suspicious and retry"]
V -->|Yes| H{"Score high?"}
H -->|Yes| A1["Allow the action"]
H -->|No| M{"Score in the middle?"}
M -->|Yes| C1["Add gentle extra verification"]
M -->|No| B2["Block or slow down and log reasons"]
When you first launch, run in observation mode: record scores and reasons but do not block anyone. After a week or two you will see the real distribution of your traffic, and you can set thresholds with confidence instead of guessing.
A score is a probability, not a proof. Some real people will score low, for example someone using unusual privacy tools, and some bots may score well. Design a kind path for false positives, such as a second verification, rather than a hard wall.
9Challenges: Asking for Extra Proof Only When Needed
A challenge is a speed bump, not a wall, and it works best when it appears rarely.
Why challenges exist
Silent scoring is wonderful for real visitors, but when the service is unsure, you may want more proof before allowing a sensitive action. A challenge is a small test that a genuine person can pass quickly and that is costly or difficult for automated programs. Examples include a checkbox that evaluates the click itself, an image puzzle, or a second verification step that you build, such as a code sent to a verified email address or phone.
A bank cashier happily serves regular customers without any questions. If someone asks to withdraw a very large sum, the cashier politely asks for identification. The extra question appears only when the situation justifies it. Challenges should work the same way.
Types of extra proof
Checkbox challenge
A visible box that a person clicks. The service studies the way it is clicked, and may escalate to a puzzle if still unsure.
Image challenge
Visitors pick matching pictures. More friction, so used only for doubtful cases.
Your own second factor
A code by email or phone, or an approval in an app. Strong proof of ownership of an account.
Cooling-off delay
Slow down repeated attempts so attackers cannot make thousands of tries per minute.
Accessibility and fairness
Puzzles are hard for many people, including those who use screen readers, have low vision, or cannot easily use a mouse. Heavy use of image challenges can lock out real customers and may create legal and reputational risk. Prefer silent scoring and light second factors, keep challenges for truly doubtful cases, and make sure an alternative path exists for those who struggle.
flowchart LR
A["Low or middle score"] --> B{"How sensitive is the action?"}
B -->|"Low sensitivity"| C["Silent allow with logging"]
B -->|"Medium sensitivity"| D["Light challenge or short delay"]
B -->|"High sensitivity"| E["Second factor or manual review"]
Friction should rise with risk. Reading an article needs none, posting a comment needs little, changing a password needs more, and moving money needs the most. Tie your challenge to the action, not just to the score.
If every visitor sees a puzzle, you have recreated the old problem. Real customers will leave, and sophisticated attackers will simply buy puzzle-solving services. Silent scoring plus targeted checks is both kinder and stronger.
10The Feedback Loop: Annotating Assessments
The service gets smarter about your site when you tell it what really happened.
An assessment is a prediction made at the moment of the action. The truth often becomes known later: a payment is charged back, a customer completes a second verification, a support team confirms a hijacked account. Annotation is the act of sending that truth back to the service, linked to the original assessment. This helps the service adapt to the patterns of your particular business.
A weather forecaster improves by checking yesterday’s forecast against what actually happened. If nobody reports back, the forecaster never learns. Your annotations are the report of what really happened.
What to report back
| Situation | What to tell the service |
|---|---|
| A payment is later disputed as fraud | The event was fraudulent, with a reason such as a chargeback |
| A customer completes second verification successfully | The event was legitimate, with a reason such as passed second factor |
| A second verification fails repeatedly | The event looks fraudulent, with a reason such as failed second factor |
| The password was correct or incorrect on login | Add the matching reason, which strengthens the signal |
| Support confirms an account was hijacked | Mark the related events as fraudulent |
Timing of feedback
Some feedback can be sent immediately, such as the result of a password check, and some arrives days or weeks later, such as a payment dispute. Both are valuable. Keep the assessment identifier with your own records, for example stored with the order or the login attempt, so that you can find it when the truth arrives.
Store the assessment name
Save the identifier of each assessment next to the related order, login or sign-up record.
Watch for outcomes
Connect events such as chargebacks, verified identities and confirmed takeovers to the stored identifier.
Send the annotation
Report whether the event was legitimate or fraudulent, with the most accurate reason available.
Review improvement
Check the dashboard over time to see whether scores separate good and bad traffic more cleanly.
sequenceDiagram
participant S as Your server
participant R as reCAPTCHA Enterprise
participant D as Your database
participant F as Fraud or support team
S->>R: Create assessment
R-->>S: Score and assessment name
S->>D: Store assessment name with order
F->>D: Later confirm outcome
D->>S: Outcome and stored name
S->>R: Send annotation with legitimate or fraudulent
Most teams integrate detection but never send feedback. They get decent results, but they miss the chance to make the service noticeably more accurate for their business. Treat feedback as part of the integration, not an optional extra.
Only report outcomes you are reasonably sure about. Wrong feedback teaches the system the wrong lesson, so a small amount of accurate feedback is better than a large amount of guesswork.
11Account Defender: Stopping Takeovers and Fake Accounts
Bots are only one threat. The most costly attacks target the accounts of your real customers.
Two big account threats
Account takeover happens when an attacker gains control of a genuine customer’s account, often with a stolen password, then steals stored value, personal data or loyalty points. Fake account creation happens when attackers register large numbers of bogus accounts to abuse free trials, sign-up bonuses, reviews or messaging.
A bank teller recognises a regular customer by their usual habits: they visit the same branch, withdraw similar amounts, and sign in a familiar way. If a stranger walks in with the customer’s card but behaves strangely, the teller becomes suspicious. Account Defender learns each account’s normal behaviour in a similar way.
How it works in simple terms
Account Defender builds a profile of normal activity for each account, using an identifier that your site provides for the account. Privacy-minded setups use an identifier that is hashed or otherwise masked, so that the service does not need the real username. With that profile, a later login can be judged not only as “is this a bot?” but also as “is this the usual person for this account?”. It can also group accounts that look related, which is a useful clue for finding networks of fake accounts created by one attacker.
Account takeover signals
Flags logins that differ from the account’s usual pattern, even if the password is correct.
Fake account signals
Highlights sign-ups that look like mass creation by the same actor.
Related account groups
Shows clusters of accounts that share behaviour, helping you act on a whole network at once.
Feedback-driven learning
Improves as you report which accounts were truly hijacked or legitimate.
What your server must do
Provide a stable account identifier
Each assessment for a logged-in or signing-up user includes an identifier for the account, preferably masked so it does not reveal the real username.
Read the account-specific verdict
Alongside the usual score, the response carries an account-level assessment, which you treat as an additional input.
Respond in proportion
A suspicious login might require a second factor, while a clearly hostile one might be blocked and the account locked for safety.
Send feedback
Tell the service about verified takeovers and verified genuine users.
Send masked or hashed account identifiers, not raw email addresses or names, wherever the design allows. Check the current documentation for recommendations on identifier format and for availability of this feature in your tier.
When a takeover is suspected, protect the real owner: require a verified second factor and a safe password reset rather than simply deleting the account or leaving it open. The goal is to stop the attacker, not to punish the customer.
12Password Leak Detection and Credential Stuffing
Attackers do not need to guess passwords when billions of real ones are already leaked.
The attack in plain words
When a website is breached, the stolen pairs of usernames and passwords end up for sale. Because many people reuse the same password on several sites, attackers take a leaked list and try each pair on other websites, a method called credential stuffing. A small fraction of tries succeed, and with millions of attempts that is plenty to cause damage. The login attempts look polite and use correct-looking details, so simple rate limits barely slow them.
Imagine a thief who steals a ring of keys from one apartment building and tries every key on the doors of other buildings in the city. Many fail, but people who used the same lock everywhere find their doors opening. Credential stuffing is that key-ring attack carried out by software.
How leak detection helps
Password leak detection lets you check whether a username and password pair the visitor just submitted appears in known collections of leaked credentials. The check is designed to protect privacy: it works with specially processed, one-way versions of the credentials so that the real values are not revealed to the service or to anyone else. If a match is found, you know that the pair is already in criminal hands, even if it is correct for your site.
Visitor submits credentials
Your login page sends the details to your server along with the reCAPTCHA token.
Your server runs the private check
Using the recommended method, the server prepares privacy-preserving versions of the credentials and asks whether the pair is known to be leaked.
The result guides your response
A leaked pair, even a correct one, triggers a protective step such as forcing a password change or a second factor.
Combine with the score
A leaked pair plus a low score is a strong sign of credential stuffing and may justify blocking the attempt.
flowchart TD
L["Login attempt arrives"] --> A["Assess token and read score"]
A --> B["Run private leaked credential check"]
B --> C{"Pair found in leaked data?"}
C -->|No| D{"Score acceptable?"}
C -->|Yes| E["Require password reset or second factor"]
D -->|Yes| F["Continue login"]
D -->|No| G["Block or add extra verification"]
Other defences that work well together
Second factors
Even a correct leaked password is useless without the second proof.
Unique passwords and managers
Encourage customers to use a different password for each site.
Alerts to the owner
Tell customers about unusual sign-ins so they can react quickly.
Gentle slow-down
Add increasing delays after repeated failures from the same pattern.
When you ask a customer to change a leaked password, say that the password appeared in a public leak elsewhere and that your site was not necessarily breached. Clear, calm wording protects trust.
13Text Message Abuse, Card Testing and Payment Fraud
Some attacks aim straight at your money: your messaging bill and your payment system.
SMS toll fraud
Many sites send a verification code by text message. Attackers abuse this by triggering thousands of messages to phone numbers they control or profit from, often in costly destinations. You pay for each message and the attacker receives a share of the fee. This is sometimes called SMS toll fraud or pumping. The visitor looks like a normal person requesting a code, and the damage appears as a surprising bill.
Imagine a free phone at a shop counter that anyone may use to call the owner’s own number. A scammer arranges for the owner’s number to be a premium-rate line, then makes the shop phone call it all day. The shop pays, the scammer profits. A text message verification form without protection is that free phone.
reCAPTCHA Enterprise offers protection for this scenario by assessing the phone number request together with the visitor, producing a signal about the chance that the phone number request is part of a pumping pattern. Your server uses that signal to decide whether to send the message. Check the current documentation for availability and exact response fields.
Card testing, also called carding
Criminals who steal card numbers do not know which are still active. They test them with tiny purchases or donations on websites that are easy to abuse. Merchants then face fees, chargebacks and damaged payment relationships. The reason code for suspected carding flags traffic that matches this pattern.
Card testing
Large numbers of small payment attempts using different card numbers, usually with many failures.
Chargeback fraud
A purchase with a stolen card is later disputed by the real owner, costing the merchant the goods and a fee.
Account-linked payment abuse
Hijacked accounts used to spend stored payment methods or loyalty value.
Promotion abuse
Bots claiming discount codes or sign-up bonuses at scale.
Payment fraud assessment
For merchants, Google offers payment-oriented risk assessment that scores a transaction using the information you share about it, such as the customer, the payment method and the order. This is a separate capability from simple bot detection and is typically used with more details about the transaction. Availability, inputs and pricing are specific to the offering, so confirm them in the current documentation.
Problem
The payment form, the text message code request and the promotion claim all rely only on an ordinary rate limit per address.
Why It’s Harmful
Attackers use thousands of addresses and slow, steady traffic, so each address stays under the limit while the total damage grows.
Correct Approach
Add reCAPTCHA Enterprise assessments, use the specific protections for text messages and payments, combine them with limits per account, per phone number and per card, and alert on unusual spikes in cost.
Set budget alerts on your messaging provider and payment accounts. An unexpected cost spike is often the first sign of abuse, and an alert gives you hours instead of weeks to react.
14Edge Protection and Firewall Integration
Judge traffic at the front gate, before it reaches your application at all.
Instead of calling the service from every page of your code, you can place reCAPTCHA Enterprise at your network edge. With a supported firewall or content delivery service, visitors receive a special session token, a longer-lived token that represents the visitor’s browsing session. The edge evaluates the session token and applies rules that you define, for example allowing, blocking, redirecting to a challenge page, or limiting the rate of traffic with a poor reputation.
Instead of asking each shop in a mall to check every shopper, the mall puts a guard at the car park entrance. The guard hands trusted visitors a badge valid for the afternoon, and every shop can see the badge. Edge integration works the same way, protecting the whole site with one set of rules.
Two kinds of tokens
| Token type | Lifetime and purpose | Typical use |
|---|---|---|
| Action token | Short-lived, single-use, tied to one named action | Judging a specific event such as login or checkout |
| Session token | Longer-lived, represents a browsing session | Evaluating all traffic through the edge across many pages |
Benefits of the edge approach
Advantages
- Bad traffic is stopped before it consumes your application’s capacity.
- Rules can be changed centrally without redeploying code.
- Protects many pages at once, including ones with no custom code.
- Useful for scraping and page-level abuse, not just forms.
Disadvantages / Trade-offs
- Less precise knowledge of the business meaning of each action.
- Depends on the supported edge provider and its rule language.
- Still benefits from server-side assessments for the most sensitive actions.
flowchart LR
V["Visitor"] --> E["Edge firewall with reCAPTCHA rules"]
E -->|"Good session token"| A["Your application"]
E -->|"Missing or poor token"| C["Challenge page or block"]
A -->|"Sensitive actions"| R["Server-side assessment"]
Use the edge for broad, cheap filtering and the server-side assessment for decisions that carry real business risk. Each layer catches what the other misses.
Edge rules affect every visitor. Start by logging what a rule would do, review the results, and only then enforce it. A badly tuned rule can block search engines, partners and real customers at the same moment.
15Protecting Mobile Apps
Phones and tablets need the same watchful guard, with different equipment.
Mobile apps are attacked in the same ways as websites: fake accounts, credential stuffing and scraping through the app’s hidden interfaces. Because apps cannot run the web script, reCAPTCHA Enterprise provides a software kit for Android and iOS. The app asks the kit for a token at the moment of the action, sends it to your backend, and the backend creates an assessment exactly as it does for web traffic.
Create a mobile key
Tie it to the identity of your app, such as its package name or bundle identifier, so that copycat apps cannot use it.
Add the software kit
Include the kit in your app and prepare it early in the app’s life, so that it can gather signals before the sensitive moment.
Ask for a token on key actions
Call the kit with a clear action name when the user logs in, signs up or pays.
Verify on your server
The app sends the token to your backend, which calls the assessment interface and applies decision rules.
A members-only club has a guard at the street door for walk-in visitors (the website) and a separate guard at the private lift (the mobile app). They carry different tools but report to the same security office.
Special points for mobile
Old app versions
Users do not update immediately. Plan how old versions without the kit will be handled during a rollout.
Network conditions
Mobile connections are slow or unstable. Allow for timeouts and offer a graceful retry.
App store rules
Disclose data collection in your privacy information as the app stores require.
Tampered devices
Rooted or emulated environments can lower the score. Treat that as a signal, not as an automatic block.
Protecting the website but leaving the mobile interface open. Attackers will simply switch to the weaker door. Protect every entry point that offers the same sensitive actions.
16Setting Up reCAPTCHA Enterprise Step by Step
A calm, ordered path from an empty project to a protected login.
Setup is straightforward when you follow a sensible order. Think of it like installing a new alarm system in a shop: you decide where the sensors go, test them, and agree what to do when an alarm sounds, before you rely on it.
Choose the project and turn on the service
reCAPTCHA Enterprise lives in a Google Cloud project. Enable the service and make sure billing is configured, since usage beyond any free allowance is charged.
Map your sensitive actions
List the places where abuse hurts you most: sign-up, login, password reset, checkout, coupon use, text message requests, contact forms, and heavy data downloads.
Create keys
Create separate keys for production and testing, and choose the right key type for each platform. Restrict each key to your own domains or app identifiers.
Add the client integration
Load the script on your pages, or add the software kit to your app, and request a token with a clear action name when each sensitive action happens.
Add the server integration
Create an assessment on your server using protected credentials, check token validity and action, and log the score and reasons.
Run in observation mode
For a week or two, record scores but do not block. Study the distribution, and look at which real customers score low.
Set thresholds and responses
Decide what happens at each score range and for each action, including a kind path for false positives.
Add feedback and monitoring
Send annotations when outcomes are known, and set up alerts on traffic, scores and your own business metrics.
Write the playbook
Document who responds to an attack, how thresholds are changed quickly, and how to roll back a rule that blocks real customers.
A new alarm system is first run silently for a few days to learn what normal looks like, then switched to full alert. Observation mode is that quiet learning period, and it prevents the embarrassing first week of false alarms.
Use separate keys and ideally separate projects for development, staging and production. Test traffic will otherwise pollute your production statistics and make tuning harder.
Keys should be limited to your own domains or app identifiers. An unrestricted key can be copied by others and used on their sites, wasting your allowance and mixing their traffic into your data.
17Access Control and Securing the Integration
The protection tool must itself be protected.
Who can do what
Access is managed through Identity and Access Management, using predefined roles for common jobs.
| Role idea | What it allows | Typical holder |
|---|---|---|
| Administrator | Create, change and delete keys and settings | A small security or platform team |
| Agent | Create assessments and send annotations | Your backend services |
| Viewer | View keys, metrics and settings | Analysts, support, auditors |
In a casino, the people who set up the security cameras are not the same as the staff who watch the monitors, and neither can open the cash vault. Splitting roles protects against mistakes and abuse. Your backend should be an agent, able to ask questions but not change the settings.
Protecting the server-side call
Use a dedicated service identity
Give each backend service its own identity with only the agent role, so activity can be traced and revoked separately.
Avoid long-lived secret files
Prefer identities that Google Cloud supplies to your running service, instead of copying credential files into code or servers.
Store any needed secrets safely
Keep credentials in a secret store and rotate them on a schedule.
Fail safely
Decide in advance what your server does if the service is unreachable: allow with extra checks for low-risk actions, and deny or delay for high-risk ones.
Problem
Verification is done in the browser or app, and the page tells the server “this visitor passed”.
Why It’s Harmful
An attacker controls the browser and can simply send the message “passed” without ever being checked. The protection becomes decoration.
Correct Approach
Always verify the token on your own server by creating an assessment, and make decisions only from that trusted reply.
Every dependency can fail. Agree in advance whether the login should fail open with extra checks or fail closed when the service cannot be reached. Making that decision calmly now beats improvising during an outage.
18Privacy, Compliance and Telling Your Users
A tool that watches behaviour carries a duty to be open about it.
To judge whether a visitor is a real person, the service collects signals about how they interact with your page or app and about their device and environment. That is what makes it effective, and it also means you are responsible for handling the topic honestly. Privacy rules differ between countries, industries and platforms, so always take advice from your own legal and privacy specialists. The points below are general guidance, not legal advice.
A shop with security cameras puts up a sign saying so. The cameras protect everyone, but visitors have a right to know. Telling users that you use risk analysis to protect the site is the digital version of that sign.
What good practice looks like
Disclose clearly
Mention in your privacy notice that you use a fraud and abuse protection service and what it observes. The service’s own terms also ask you to give notice to your users.
Collect only what you need
Send the minimum details required, such as masked account identifiers instead of raw email addresses where the design allows.
Respect consent rules
In some regions, behaviour monitoring may be subject to consent or notice rules. Work out which apply to your visitors.
Keep your own records tidy
Scores, reasons and assessment identifiers you store are personal data in many settings. Decide how long to keep them and who may see them.
The badge and the notice
For invisible keys, a small badge normally appears on the page. The terms allow you to hide it only if you replace it with a visible notice that tells users the site is protected and that the provider’s privacy policy and terms apply. Read the current terms carefully before changing the look of your page.
Fairness and accessibility
Automated risk decisions can wrongly affect real people, especially those using privacy tools, shared networks or assistive technology. Offer a clear, humane route to resolve mistakes, such as a support contact or an alternative verification, and watch for patterns where certain groups are unfairly blocked more often.
Logging full request bodies next to risk scores can accidentally capture passwords or personal details. Log the assessment identifier, the score, the reasons and the decision, and keep sensitive content out of those logs.
Bring your privacy and legal teams into the design before launch. Adding disclosure and consent steps later is slower and riskier than building them in from the start.
19Monitoring, Metrics and Ongoing Tuning
Attackers adapt, so protection is a habit, not a one-time installation.
What the console shows
The Google Cloud console presents statistics for each key, including how many requests arrive, how scores are distributed, how many tokens were invalid, and, where relevant, how challenges were solved. These views help you see whether a sudden surge is organic, such as a marketing campaign, or hostile, such as a bot wave at three in the morning.
Traffic volume
Requests over time. Sudden spikes outside normal business patterns deserve attention.
Score distribution
The share of traffic at each score level. A healthy site usually has a large high-score group.
Invalid tokens
Many invalid or missing tokens can mean broken integration or direct attacks on your server.
Challenge outcomes
Pass and fail rates show whether challenges annoy real people or stop attackers.
A hospital monitors patients’ vital signs all the time, not just on admission. Your score distribution and traffic charts are the vital signs of your site’s health, and a sudden change is a reason to look closer.
Add your own business signals
The service sees traffic, but you see consequences. Track how many sign-ups are confirmed, how many orders are disputed, how many password resets succeed, how many text messages you send and what they cost. Compare these with the scores to learn whether your thresholds match real outcomes. Cloud Logging and Cloud Monitoring are the natural home for your own decision logs and alerts.
Log every decision
Record action, score, reasons and the response you chose, without sensitive content.
Build a small dashboard
Show blocked, challenged and allowed counts by action over time, next to business outcomes.
Alert on surprises
Notify the team on sudden changes in score distribution, a jump in blocked traffic, or unusual costs.
Review monthly
Compare scores with outcomes, retune thresholds gently, and record each change and its reason.
flowchart LR
AS["Assessments and scores"] --> LG["Your decision logs"]
LG --> DB["Dashboard"]
LG --> AL["Alerts"]
BO["Business outcomes such as disputes"] --> DB
DB --> RV["Monthly review"]
AL --> OC["On-call responder"]
RV --> TH["Adjust thresholds and rules"]
TH --> AS
When you adjust a threshold or rule, change only one thing and watch the effect for a few days. Many changes at once make it impossible to know which one helped or hurt.
20Cost, Quotas and Performance
The service is inexpensive for many sites, but design choices change both the bill and the speed.
How charges usually work
Pricing is based mainly on the number of assessments you create, often with a monthly free allowance and a price per thousand assessments beyond it. Extra capabilities, such as account protection, payment fraud analysis and finer score detail, can carry their own charges or sit in higher tiers, and large organisations can negotiate commitments. Always read the current pricing page for exact figures, because they change.
Assessments
Each server-side assessment is counted. Assess sensitive actions, not every page view, unless you use edge integration for broad coverage.
Premium features
Account defence, payment analysis and finer scores may be billed differently from basic scoring.
Attack traffic
If attackers hammer a protected form, every attempt may create an assessment. Edge filtering can reduce this.
Your own infrastructure
Logging, storage and network costs from your own decision logs add to the total.
A security guard company may charge per visitor checked. Checking only the visitors who enter the vault room costs far less than checking everyone who walks past the shop window. Choose where you place the checks with the same sense of proportion.
Quotas and limits
Like most cloud services, the interface has limits on how many requests you can make per minute. Normal sites rarely reach them, but a flood of attack traffic or a very large launch might. Review the current limits, ask for increases ahead of big events, and design your server to cope with temporary errors using short, gradually lengthening retries.
Performance and user experience
Asking for a token adds a small delay, and the server-side assessment adds another round trip. These are usually short, but they matter on slow mobile connections and for checkout flows. Good habits include loading the script early and asynchronously so it does not delay the page, requesting the token just before the action, calling the assessment interface from a server close to Google’s service, and keeping the decision logic fast and simple.
Loading the script in a way that stops the page from drawing slows real customers and hurts conversion. Load it asynchronously and design for the case where it fails to load, so that a network hiccup does not break your whole form.
Set billing alerts for the project. A sudden jump in assessments can be the first sign of an attack on your forms, and an early alert gives you time to tighten the edge rules.
21Design Patterns for Effective Protection
Good protection comes from a handful of repeatable habits.
Pattern 1: One named action per sensitive step
Give each important step its own action name, such as login, signup, checkout and password reset, and check that the returned action matches. This blocks token reuse across pages and lets you tune each action separately.
Pattern 2: Observe, then enforce
Start in observation mode, study real score distributions, then enable responses gradually, beginning with the gentlest.
Pattern 3: Friction proportional to risk
Match the extra proof to the sensitivity of the action and the score, from silent allow to second factor to block.
Pattern 4: Defence in depth
Combine edge rules, server-side assessments, account-level signals, rate limits and second factors, so that one weak layer does not mean total failure.
Pattern 5: Close the feedback loop
Store assessment identifiers with business records and send annotations when outcomes are known.
Pattern 6: Separate keys by purpose and environment
Use distinct keys for production, testing, web and mobile, and for very different areas of the product, so that data and tuning stay clean.
Pattern 7: A graceful path for false positives
Give wrongly flagged visitors a way forward, such as a second verification or a support contact, rather than a dead end.
Pattern 8: Decide the failure mode in advance
Write down what your system does when the service is unreachable, with different answers for low-risk and high-risk actions.
flowchart TD
V["Visitor"] --> L1["Layer 1: Edge rules and session token"]
L1 --> L2["Layer 2: Server-side assessment with action check"]
L2 --> L3["Layer 3: Account signals and leaked credential check"]
L3 --> L4["Layer 4: Second factor for risky cases"]
L4 --> OK["Action allowed"]
L1 -.-> X["Block early"]
L2 -.-> X
L3 -.-> X
L4 -.-> X
A medieval castle had a moat, a wall, a gate, guards and an inner keep. An attacker had to beat all of them. Modern protection layers follow the same wisdom: never rely on a single barrier.
22Anti-patterns: What Not to Do
These habits quietly weaken protection or hurt real customers.
Problem
The team sets a strict threshold on day one and blocks everything below it.
Why It’s Harmful
Without data, the line is a guess. Real customers using unusual setups are blocked, support tickets surge, and revenue drops while the team still does not know the true traffic picture.
Correct Approach
Run in observation mode first, study the distribution, and tighten gradually with a gentle response for the middle range.
Problem
Only the login page is protected, while sign-up, password reset, the mobile interface and the text message request are left open.
Why It’s Harmful
Attackers pick the weakest door. Fake accounts pour in through sign-up, resets are abused to take over accounts, and text message costs rise.
Correct Approach
Map all sensitive actions and entry points, and protect each with an appropriate check.
Problem
Every visitor is forced to solve a visible puzzle.
Why It’s Harmful
Customers leave, accessibility suffers, and determined attackers use puzzle-solving services anyway.
Correct Approach
Use silent scoring and show challenges only for doubtful, sensitive cases.
Problem
The same key is used for development, staging and production, and for many unrelated sites.
Why It’s Harmful
Statistics become a muddle, tests pollute real data, and a leak of the key affects everything. Domain restrictions become hard to manage.
Correct Approach
Create separate keys per environment and purpose, each restricted to its own domains or app identifiers.
Problem
No feedback is ever sent, and thresholds are never revisited after launch.
Why It’s Harmful
Attackers adapt while your settings stand still. Accuracy slowly declines and nobody notices until a costly incident.
Correct Approach
Send annotations, review metrics monthly, and treat tuning as routine work.
Problem
When the service cannot be reached, the code silently allows everything, including payments and password resets.
Why It’s Harmful
Attackers can cause or exploit outages to slip through, and the most sensitive actions lose all protection exactly when it matters.
Correct Approach
Define a failure mode per action: allow low-risk actions with extra monitoring, but delay or deny high-risk ones.
23Best Practices and Common Mistakes
A checklist in plain words that any team can adopt.
Do
- Verify every token on your own server.
- Check token validity, action and site before reading the score.
- Name one action per sensitive step.
- Start in observation mode and tune with real data.
- Match friction to risk and give false positives a way forward.
- Send feedback with accurate reasons.
- Use separate keys with domain or app restrictions.
- Disclose the protection in your privacy notice.
Do Not
- Trust the browser or app to say a visitor passed.
- Reuse tokens or request them long before the action.
- Block everything below an unmeasured threshold.
- Force puzzles on all visitors.
- Leave sign-up, reset and mobile interfaces unprotected.
- Put server credentials in pages or apps.
- Log passwords or personal details next to scores.
- Forget the failure mode when the service is unreachable.
Common mistakes beginners make
Forgetting that tokens expire
Tokens are short-lived and single-use. A form left open for a long time will fail unless the page requests a fresh token at submit time.
Mismatched actions
The page names the action one way and the server expects another, so every assessment looks suspicious. Keep a shared list of action names.
Wrong domain settings
A key restricted to the wrong domain, or missing the test domain, causes failures that look like attacks.
Treating the score as a yes or no
A score is a probability. Use zones and reasons, not a single hard line.
Ignoring the search engines and partners
Legitimate crawlers and partner systems may look automated. Plan allow rules for known good automation so you do not block your own visibility.
No monitoring after launch
Protection that is not watched decays quickly. Set alerts and schedule reviews.
After each release, test your protected actions end to end in a safe environment: one normal user, one expired token, one reused token and one mismatched action. This short test catches most integration mistakes before attackers do.
24Real-world and Industry Examples
The same service protects very different businesses. These scenarios show how.
Online retail and flash sales
A fashion retailer launches a limited-edition sale. Bots try to buy every item to resell. Score-based checks on the checkout, edge rules during the sale and limits per account keep real fans in the queue. Suspicious orders are held for review, and confirmed fraud is sent back as feedback.
Banking and financial apps
A bank protects its app and website login with account-level signals and leaked credential checks. Logins that look unusual for the customer trigger a second factor, and confirmed takeovers are reported back. Customers who are verified pass quickly on the next visit.
Ticketing and events
A ticket seller faces scalpers who use many accounts. Related account grouping helps find networks of fake accounts, and rules slow or block them while genuine buyers proceed.
Media and streaming sign-ups
A streaming service offers free trials and sees thousands of fake sign-ups. Sign-up assessment with account protection, a second verification for risky sign-ups, and removal of related account clusters cut trial abuse sharply.
Messaging and verification codes
An app that verifies phone numbers sees a huge bill from text messages sent to far-away numbers. Pumping protection, limits per number and country, and alerts on cost bring the abuse under control.
Travel and price comparison
A travel site finds competitors copying its fares at high speed. Session tokens at the edge and rate rules for poor-reputation traffic reduce scraping while search engines and partners are allowed through on agreed rules.
A small business website
A small company with a contact form receives hundreds of spam messages a day. A score-based key on the form, with a soft response for the middle range, removes nearly all spam without annoying customers, and it needs only a few lines of code.
flowchart LR
RT["Retail checkout"] --> RE["reCAPTCHA Enterprise"]
BK["Bank login"] --> RE
TK["Ticket sign-up"] --> RE
ST["Streaming trial"] --> RE
MS["Text message codes"] --> RE
RE --> DEC["Each business applies its own rules"]
25Advantages, Disadvantages and Trade-offs
An honest comparison always includes the limits.
Advantages
- Invisible for most real visitors, so the experience stays smooth.
- Detection benefits from signals learned across a huge number of sites.
- Fully managed, with no detection servers to maintain.
- Reason codes and scores allow flexible, proportional responses.
- Covers web, mobile and edge integration.
- Specialised protections for accounts, passwords, text messages and payments.
- Feedback loop tunes the service for your business.
Disadvantages / Trade-offs
- You must build the decision logic and the kind paths for false positives.
- Scores are probabilities, not certainties.
- Behaviour monitoring raises privacy and disclosure duties.
- Server calls add small delays and costs.
- Sophisticated attackers adapt, so tuning never ends.
- Some advanced features depend on tier, region and availability.
How the options compare
| Approach | Strength | Limitation |
|---|---|---|
| No protection | Zero effort | Open to spam, fake accounts, stuffing and fraud |
| Simple rate limits | Easy and cheap | Attackers spread across many addresses |
| Visible puzzles for everyone | Simple to understand | Annoys users, poor accessibility, solvable by services |
| Web application firewall alone | Strong against known attack patterns | Does not judge whether a visitor is a real person |
| reCAPTCHA Enterprise | Behaviour-based scoring, account and payment protections | Needs design, tuning and privacy care |
| Specialised third-party bot platforms | Deep dedicated bot features, wide cross-cloud options | Extra cost and integration work |
Rate limits are a turnstile that counts people. A firewall is a fence that blocks known troublemakers. Visible puzzles are a quiz at the door for everyone. reCAPTCHA Enterprise is the experienced guard who watches behaviour, waves most people through, and reacts to what looks wrong. The best premises use several of these together.
If you have a public form, login, sign-up or checkout and meaningful abuse, a behaviour-based service is usually worth it. Start with the simplest integration on your most abused action, learn from the data, and add account, edge and payment protections as your needs grow. Compare current features and prices before committing.
26Troubleshooting Common Problems
When something looks wrong, work from the visitor toward your decision, one link at a time.
flowchart TD
A["Many real users blocked or all tokens invalid"] --> B{"Is the script or kit loading on the page or app?"}
B -->|No| C["Fix loading, content rules and network blocks"]
B -->|Yes| D{"Does the key match the domain or app identifier?"}
D -->|No| E["Correct key restrictions"]
D -->|Yes| F{"Is the token requested right before the action and sent once?"}
F -->|No| G["Request a fresh token at submit time"]
F -->|Yes| H{"Does the action name match on page and server?"}
H -->|No| I["Align the action names"]
H -->|Yes| J{"Is the server using the right project and permissions?"}
J -->|No| K["Fix service identity and role"]
J -->|Yes| L["Review thresholds, reasons and recent changes"]
Symptom: every assessment says the token is invalid
The usual causes are expired tokens, tokens used twice, a key that does not match the domain, or a server using the wrong project. Check that the page asks for the token just before submission, that the token is sent once, and that the server is calling the same project and key as the page.
Symptom: real customers keep getting low scores
Look at the reason codes. Common causes include unusual browser setups, corporate networks that share one address, privacy tools, or a script that loads late so the service sees little behaviour. Load the script earlier, widen coverage across pages, and move the middle range to a gentle challenge instead of a block.
Symptom: bots still get through
Check whether every entry point is protected, whether tokens are actually verified on the server, whether the action name is checked, and whether thresholds are too lenient for the action. Review blocked and allowed samples and add edge rules for obvious automation.
Symptom: permission errors from the server
The service identity may lack the agent role, or may belong to a different project. Grant the narrow role to the correct identity, and confirm which project the call targets.
Symptom: sudden bill increase
Look for attack traffic hitting protected forms, loops in your own code that assess repeatedly, or assessments on every page view where only key actions need them. Reduce unneeded calls and add edge filtering.
Problem
A form works in testing but fails for many real visitors, with tokens reported as invalid.
Why It’s Harmful
Common reasons are that visitors keep the page open for a long time before submitting, that the token is created too early, or that the key is restricted to the test domain only. Real customers are blocked while attackers may have other routes.
Correct Approach
Request a fresh token at the moment of submission, confirm the domain list covers production, and test an old open page on purpose.
27Responding to an Attack: A Simple Playbook
Preparation turns a frightening surge into a managed event.
Sooner or later a wave of abusive traffic arrives: thousands of fake sign-ups overnight, a burst of login attempts, or a sudden stream of tiny card payments. A short written playbook helps the team act calmly instead of guessing.
Notice
An alert fires on traffic, score distribution, cost or business signals. Confirm that it is real and not a campaign or a bug.
Identify the target
Find which action is being hit and what the scores and reasons say. Different attacks need different responses.
Tighten the right control
Raise the threshold for that action only, add a second factor, add edge rules, or add limits per account, number or card. Avoid changing everything at once.
Protect real users
Watch for rising complaints, and make sure a verification path exists for wrongly blocked customers.
Clean up
Remove fake accounts, cancel fraudulent orders, reset hijacked accounts, and report outcomes as feedback.
Relax and review
When the wave passes, step controls back to normal gradually and hold a short review about what to automate next time.
sequenceDiagram
participant M as Monitoring
participant T as On-call team
participant R as Rules and thresholds
participant S as Support
M->>T: Alert on unusual traffic or cost
T->>T: Identify the targeted action
T->>R: Tighten controls for that action
T->>S: Prepare path for wrongly blocked users
R-->>M: Effect visible in metrics
T->>R: Relax gradually after the wave
T->>T: Review and improve playbook
A shop that rehearses what to do during a rush of shoplifters, such as locking one door and calling the right person, copes far better than one that improvises. A written playbook is your rehearsal.
Blocking all traffic from an entire country or network can stop the attack, but it also stops real customers and partners. Prefer targeted controls, and set a time limit so emergency rules do not stay forever.
Once or twice a year, rehearse changing a threshold and rolling it back in a test environment. Knowing exactly how to make and undo a change under pressure is worth more than any document.
28Testing, Rollout and a Maturity Path
Introduce protection carefully, prove that it works, and grow it in stages.
The riskiest moment of any protection project is the first launch, because mistakes there either let attackers through or block real customers. A calm testing and rollout plan removes most of that risk. Think of it like opening a new road: you test it with a few cars first, watch the traffic, and only then open all lanes.
What to test before launch
The normal visitor
A real person on a common browser and phone completes each protected action smoothly, with no unexpected friction.
The expired token
Leave a form open for a long time and then submit it. The page should quietly request a fresh token or show a friendly retry message.
The reused token
Try sending the same token twice. The second attempt must be rejected by the server.
The wrong action
Present a token created for one action on a different action. The server must notice the mismatch.
The service outage
Simulate the service being unreachable and confirm that each action follows its planned failure mode.
The unusual setup
Try privacy-focused browsers, slow networks and assistive technology, to see how real but unusual visitors are treated.
Before a theatre opens a new fire exit system, staff run a drill with ordinary visitors, a visitor in a wheelchair, and a blocked corridor. Only after every case works do they trust the system with a full house. These six tests are your drill.
A gentle rollout plan
Staging first
Deploy the full integration to a staging environment with its own keys, and run the six tests.
Observation in production
Release with scoring and logging only. No visitor is blocked, but every score and reason is recorded.
Study the data
After a week or two, examine score distributions per action, and look at samples of low scores to see whether they are bots or real people.
Enable the gentlest response
Begin with light measures for the lowest scores, such as a second verification, on the most abused action only.
Expand step by step
Add more actions and stronger responses one at a time, watching complaints and business metrics after each change.
Document and hand over
Write down thresholds, reasons for them, owners and the rollback method, so the knowledge outlives any one person.
flowchart LR
ST["Staging tests"] --> OB["Observation mode in production"]
OB --> AN["Analyse score distribution"]
AN --> G["Gentle response on one action"]
G --> EX["Expand to more actions"]
EX --> OP["Operate, monitor and retune"]
OP -.->|"Learn and adjust"| AN
Moving from older reCAPTCHA versions
Many sites begin with the older, simpler reCAPTCHA products and later move to the enterprise service for its richer scoring, reason codes and specialised protections. The idea is the same, a site key on the page and a server-side check, but the enterprise service uses an assessment interface and offers more detail. Plan the move as a normal rollout: create new keys, integrate in staging, run in observation mode, then switch traffic across. Check the current migration guidance in the documentation, because details and timelines can change.
A maturity path
| Stage | What it looks like | Next step |
|---|---|---|
| Stage 1: Unprotected | Spam, fake accounts and fraud are handled by hand after the fact | Protect the single most abused form with a score-based key |
| Stage 2: Protected forms | Key actions are assessed on the server, thresholds are set from data | Add feedback and decision logging |
| Stage 3: Layered | Edge rules, account signals and second factors work together | Add leaked credential checks and text message protection |
| Stage 4: Measured | Dashboards, alerts, monthly reviews and cost tracking are routine | Automate responses and rehearse the attack playbook |
| Stage 5: Adaptive | Feedback loops, related account analysis and fast tuning keep pace with attackers | Share lessons across teams and keep improving |
Learning to look after a garden starts with a fence against rabbits, then watering schedules, then watching which plants thrive, and finally adjusting with the seasons. Protection grows the same way, from the first fence to the practised gardener.
Cloud services and attacker methods both change. Treat the official documentation, release notes and pricing pages as the final word on features, limits and terms, and revisit them every few months.
The most common launch failure is blocking on day one with a guessed threshold. A single week of observation turns guesses into evidence and is the cheapest insurance in the whole project.
29Frequently Asked Questions
The site key is a public identifier of your website or app, placed in your page. A token is a short-lived, single-use code created for one visitor action, which your server verifies through an assessment.
No. With score-based keys the check is invisible. Visible challenges are shown only if you choose a checkbox key or trigger an extra check for doubtful cases.
It is a number from zero to one. Higher means the interaction looks more like a real person, and lower means it looks more like a bot. It is a probability, so combine it with reason codes and business context.
The browser or app is under the visitor’s control. Only a server-side assessment with protected credentials gives a trusted result that cannot be forged by an attacker.
Tokens are valid for a short time, about two minutes, and can be assessed only once. Ask for a fresh token right before the action. Check current documentation for the exact lifetime.
An action is a label for what the visitor is doing, such as login or checkout. Naming it lets the service judge in context and lets your server detect tokens reused on a different page.
It is optional but valuable. Sending annotations about confirmed fraud or confirmed legitimate users helps the service adapt to your business and improves accuracy over time.
Yes. Android and iOS software kits create tokens inside the app, which your backend verifies in the same way as web tokens, using a key tied to your app’s identity.
It is an attack that tries leaked username and password pairs on other sites. Scoring helps spot automated attempts, and leaked credential checks tell you when a submitted pair is known to be exposed so you can require a reset or second factor.
No. A firewall blocks known attack patterns and floods, while reCAPTCHA Enterprise judges whether a visitor behaves like a real person. They work best together.
The service uses behaviour and device signals, so you should disclose its use in your privacy notice, collect only what you need, and follow the rules of the regions you serve. Take advice from your legal team.
Decide in advance per action. Low-risk actions may proceed with extra monitoring, while high-risk actions such as payments should be delayed or denied until protection is available.
For many sites the cost is modest, often with a free monthly allowance and a price per thousand assessments beyond it. Extra features may cost more. Check the current pricing page.
30Summary and Key Takeaways
reCAPTCHA Enterprise is the watchful, mostly invisible guard of your website and mobile app. It observes how visitors behave, issues a short-lived token, and, when your server asks, returns a risk score with reason codes. Your server verifies every token, checks its validity and action, and turns the score into a proportional response: allow, add a gentle check, slow down or block. Beyond bot detection, the service offers focused protection against account takeover, fake accounts, leaked passwords, text message abuse and payment fraud, and it can work at the network edge through firewall integration. Success depends on good habits: protecting every sensitive entry point, starting in observation mode, matching friction to risk, closing the feedback loop, respecting privacy and accessibility, monitoring continuously, and keeping a calm playbook for the day an attack arrives.
Key Takeaways
- Verify on the server — only a server-side assessment is trustworthy, and the page or app must never decide on its own that a visitor passed.
- Check before you score — confirm token validity, action name and site first, then read the score and reasons.
- Scores are probabilities — use zones and reason codes, observe real traffic before enforcing, and give wrongly flagged people a kind way forward.
- Match friction to risk — silent scoring for most visitors, light checks in the middle, and strong proof only for sensitive actions.
- Layer your defences — combine edge rules, server-side assessments, account signals, leaked credential checks, rate limits and second factors.
- Close the loop — store assessment identifiers, send honest feedback, monitor decisions and costs, and retune regularly.
- Be open and prepared — disclose the protection to your users, decide failure modes in advance, and keep a short attack playbook ready.