reCAPTCHA Client API Documentation

reCAPTCHA is a freely available CAPTCHA implementation. It distinguishes humans from computers. This document describes how to embed a reCAPTCHA on your website and how to customize its appearance.

How the reCAPTCHA API Works

1. The user loads the web page with the reCAPTCHA challenge JavaScript embedded.
2. The user's browser requests a challenge from reCAPTCHA. reCAPTCHA gives the user a challenge and a token that identifies the challenge.
3. The user fills out the web page form, and submits the result to your application server, along with the challenge token.
4. reCAPTCHA checks the user's answer, and gives you back a response.
5. If true, generally you will allow the user access to some service or information. E.g. allow them to comment on a forum, register for a wiki, or get access to an email address. If false, you can allow the user to try again.


This guide focuses on the first three steps. We have a set of APIs for checking the reCAPTCHA answer.

Signing up for a reCAPTCHA Key

In order to use reCAPTCHA, you need a public/private API key pair. This key pair helps to prevent an attack where somebody hosts a reCAPTCHA on their website, collects answers from their visitors and submits the answers to your site. You can sign up for a key on the reCAPTCHA Administration Portal.

Key Scope

Your reCAPTCHA token is valid only at the domain you sign up for and any subdomains (due to the potential attack mentioned above). Some users require keys for multiple sites, for example, a development server and a production server or simply multiple sites hosted on the same server. Three techniques can be used to work around this:

If one of your servers is "localhost" or "127.0.0.1", reCAPTCHA will not enforce the same-domain rule. Just use the same key as for the production server.

Generate a key for a broader scope. For example, if your application is a.example.com and your test server is test.corp.example.com, generate a key for example.com. Note that multiple users can sign up for the key for a domain, so there's no need to worry if you don't own all of example.com.

Generate a different key for each domain.