CapMonster Cloud API
Extensão para navegadores
Como encontrar e usar sua chave secreta do reCAPTCHA
Se o seu site depende do Google reCAPTCHA para bloquear bots, a chave secreta do reCAPTCHA é a credencial mais crítica de segurança que você possui. Sem ela, seu servidor não consegue verificar se um usuário realmente passou pelo desafio CAPTCHA — o que torna a proteção efetivamente inútil. Ainda assim, essa também é a chave mais comumente configurada de forma incorreta, exposta ou mal compreendida.
Este guia explica exatamente o que é a chave secreta, como encontrá-la no Google Admin Console, como integrá-la corretamente ao código do seu backend e como mantê-la segura. Também veremos como ferramentas como o CapMonster Cloud usam a chave pública complementar para testes automatizados legítimos da sua própria configuração de CAPTCHA.
O que é uma chave secreta do reCAPTCHA?
O Google reCAPTCHA emite duas chaves quando você registra um site — e entender a diferença entre elas é essencial antes de mexer em uma única linha de código.
A recaptcha secret key (às vezes chamada de recaptcha_secret_key no código) é usada exclusivamente no seu servidor. Ela é enviada em uma requisição POST para o endpoint siteverify do Google junto com o token gerado pelo navegador do usuário. O Google responde com um objeto JSON confirmando se o desafio foi concluído com sucesso.
Tanto o reCAPTCHA v2 (a caixa de seleção clássica e as variantes invisíveis) quanto o reCAPTCHA v3 (baseado em pontuação, sem interação do usuário) seguem esse mesmo modelo de duas chaves. A diferença está no que o token representa: um resultado binário de aprovação/reprovação no v2, ou uma pontuação de risco entre 0.0 e 1.0 no v3.
Como encontrar sua chave do reCAPTCHA no reCAPTCHA Admin Console
Se você está obtendo um par de Google reCAPTCHA key pela primeira vez, pode fazer isso pelo reCAPTCHA Admin Console — o processo é descrito nesta seção. Se você já registrou chaves do reCAPTCHA para seus sites, observe que as chaves existentes são gerenciadas no Google Cloud Console; você pode pular para a próxima seção.
Etapa 1 — Acesse o reCAPTCHA Admin Console
Vá para google.com/recaptcha/admin. Faça login com a conta do Google que você quer que seja proprietária das chaves.
Etapa 2 — Registre um novo site
Depois de fazer login, você verá um prompt para registrar o primeiro site:
Preencha:
- Label: Um nome de exibição usado apenas para sua própria identificação dentro do console. Use algo descritivo, como Produção – Formulário de Checkout ou Staging – Página de Contato. Não há implicações de SEO ou de segurança; isso serve apenas para clareza interna, especialmente ao gerenciar várias chaves.
- reCAPTCHA type: veja a tabela abaixo.
- Domains: Restringe quais domínios têm permissão para carregar e enviar tokens do reCAPTCHA usando esta chave. Um registro para example.com cobre automaticamente subdomain.example.com — não é necessário listar subdomínios separadamente. Regras importantes:
- Não inclua caminho, porta, query string ou fragmento (por exemplo, use example.com, não example.com/contact).
- Alterações de domínio podem levar até 30 minutos para se propagar.
- Esse campo não se aplica ao tipo de site reCAPTCHA v2 Android.
Manter essa lista enxuta é uma das formas mais eficazes de impedir o uso não autorizado da sua chave em domínios de terceiros.
- Google Cloud Platform: As chaves de API criadas são gerenciadas no Google Cloud Platform. Portanto, se você não tiver uma conta ou projeto no Google Cloud Platform, será solicitado a criar um automaticamente.
Etapa 3 — Escolha seu tipo de reCAPTCHA
Observe que você não poderá alterá-lo após o registro:
Ao usar o caminho google recaptcha v2 , você obtém um widget baseado em desafio com segurança ajustável. Ao usar o caminho recaptcha v3 , a proteção é invisível e baseada em pontuação — seu servidor decide o que fazer com o resultado.
Etapa 4 — Aceite os termos e envie
Marque a caixa dos Termos de Serviço e clique em Submit. O Google gerará seu par de chaves.
Etapa 5 — Copie suas chaves
Na tela de confirmação, você verá dois valores:
- Site key — é seguro torná-la pública; vai no seu HTML
- Secret key — sua google reCAPTCHA secret key; vai somente para o seu servidor
Copie ambas imediatamente para um gerenciador de senhas seguro ou um cofre de segredos. Depois, você poderá ver essas chaves acessando o Google Cloud Console (veja abaixo).
Como encontrar sua chave do reCAPTCHA no Google Cloud Console
Atualmente, o reCAPTCHA Admin Console permite registrar apenas seu primeiro site. O gerenciamento posterior das chaves e o registro de novas chaves são feitos no Google Cloud Console.
Etapa 1 — Acesse o Google Cloud Console
Para visualizar suas chaves de um site existente, abra o Google Cloud Console > Security > Detections and Controls > reCAPTCHA > guia Dashboard e role um pouco para baixo até a seção reCAPTCHA keys:
Etapa 2 — Abra o painel Key details
Clique em Key details e você será direcionado ao painel Key details:
Etapa 3 — Copie suas chaves
Na página Key details (painel de administração do reCAPTCHA), clique em Edit key:
O menu de configurações será aberto, e você verá tanto sua site key (ID) quanto sua secret key:
Como usar chaves do reCAPTCHA no seu código
O fluxo de verificação tem duas partes distintas: o frontend, que mostra o widget, e o backend, que valida a resposta.
Frontend: incorporando a chave do site
Coloque o trecho a seguir em qualquer página HTML em que você queira que o widget apareça. O atributo data-sitekey recebe sua recaptcha public key — nunca a secreta.
Widget de caixa de seleção do reCAPTCHA v2:
<html>
<head>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</head>
<body>
<form action="/submit" method="POST">
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Submit</button>
</form>
</body>
</html>Quando o usuário envia o formulário, o script do Google injeta um campo oculto g-recaptcha-response contendo um token de curta duração. Esse token é o que seu servidor deve validar.
Backend: verificando o token com a chave secreta
Seu servidor envia o token e a recaptcha_secret_key para o endpoint de verificação do Google:
POST https://www.google.com/recaptcha/api/siteverify
Node.js (usando axios):
const axios = require('axios');
async function verifyRecaptcha(token) {
const secret = process.env.RECAPTCHA_SECRET_KEY; // carregado do ambiente
const { data } = await axios.post(
`https://www.google.com/recaptcha/api/siteverify`,
new URLSearchParams({ secret, response: token })
);
return data.success; // true se for humano, false se for bot
}
PHP:
$token = $_POST['g-recaptcha-response'] ?? '';
$secret = getenv('RECAPTCHA_SECRET_KEY');
$options = [
'http' => [
'header' => "Content-type: application/x-www-form-urlencoded\\r\\n",
'method' => 'POST',
'content' => http_build_query(['secret' => $secret, 'response' => $token])
]
];
$context = stream_context_create($options);
$response = file_get_contents('https://www.google.com/recaptcha/api/siteverify', false, $context);
$result = json_decode($response, true);
if (!empty($result['success'])) {
// Prosseguir com o processamento do formulário
} else {
// Rejeitar a solicitação
}
Python (usando requests):
import requests, os
def verify_recaptcha(token: str) -> bool:
secret = os.environ["RECAPTCHA_SECRET_KEY"]
r = requests.post(
"https://www.google.com/recaptcha/api/siteverify",
data={"secret": secret, "response": token}
)
return r.json().get("success", False)A API do Google retorna um objeto JSON. Para o reCAPTCHA v2, verifique o campo success . Para o v3, verifique também o campo score (valores mais próximos de 1.0 indicam comportamento humano) e o campo action para confirmar que o token foi gerado na página esperada.
Boas práticas de segurança para suas chaves do reCAPTCHA
Proteger sua google reCAPTCHA private key não é opcional — uma chave secreta vazada permite que invasores forjem resultados de verificação e contornem totalmente sua proteção contra bots.
1. Nunca exponha a chave secreta no lado do cliente. A recaptcha private key nunca deve aparecer em HTML, JavaScript, binários de aplicativos móveis ou repositórios públicos do Git. Mesmo uma breve exposição no histórico de commits já é suficiente para comprometer seu site — trate-a sempre com a mesma sensibilidade de uma senha de banco de dados.
2. Armazene as chaves em variáveis de ambiente ou em um gerenciador de segredos. Colocar a recaptcha_secret_key diretamente nos arquivos-fonte é um dos erros de segurança mais comuns. Em vez disso, carregue-a em tempo de execução:
- Desenvolvimento local: arquivo .env carregado via dotenv (nunca versionado no controle de versão)
- Produção: segredos da plataforma (por exemplo, AWS Secrets Manager, Google Secret Manager, HashiCorp Vault ou a interface de variáveis de ambiente do seu provedor de hospedagem)
3. Restrinja os domínios permitidos. No Admin Console, sempre especifique os domínios exatos autorizados a usar sua recaptcha key. Isso impede que outros sites renderizem seu widget e consumam sua cota — ou potencialmente testem sua lógica de verificação.
4. Valide todos os campos na resposta da API. Uma verificação segura no lado do servidor deve confirmar:
- success é true
- hostname corresponde ao seu domínio real
- Para o v3: score está acima do seu limite (normalmente 0.5) e action corresponde ao nome de ação esperado
- O token ainda não foi usado anteriormente (tokens são de uso único; tentativas de replay retornam success: false)
5. Faça rotação das chaves se forem comprometidas. Se você suspeitar que sua google recaptcha private key vazou, vá imediatamente ao Admin Console, exclua o par de chaves afetado e registre um novo. Atualize todos os ambientes de implantação antes que a chave antiga pare de funcionar.
6. Mantenha o monitoramento ativo. O Google Cloud Console fornece análises de tráfego. Revise regularmente as requisições por domínio, as taxas de falha na verificação e picos incomuns — eles podem indicar vazamento de chave ou uma tentativa ativa de abuso.
Testes automatizados de reCAPTCHA com CapMonster Cloud
Depois que sua integração com o reCAPTCHA estiver em produção, você precisa confirmar que ela funciona de ponta a ponta — incluindo o fluxo de tokens, a validação no servidor e o comportamento do formulário após um desafio bem-sucedido. Resolver CAPTCHAs manualmente durante o QA é lento e inconsistente. É aí que o CapMonster Cloud se torna uma ferramenta prática.
O CapMonster Cloud é um serviço automatizado de resolução de CAPTCHA projetado para testar seus próprios sites e sistemas aos quais você tem acesso legal. Criticamente, ele funciona com sua recaptcha public key (a site key) — não com a secreta — o que significa que sua recaptcha_secret_key nunca sai do seu servidor, mesmo durante execuções automatizadas de teste.
Como funciona
O CapMonster Cloud aceita uma tarefa via sua API, resolve o CAPTCHA em seus servidores e retorna um token g-recaptcha-response pronto para uso, que você injeta no seu formulário para validação de ponta a ponta.
Exemplo de resolução de reCAPTCHA v3 usando o CapMonster Cloud:
Criar tarefa:
POST https://api.capmonster.cloud/createTaskRequisição
{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",
"websiteKey": "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
"isEnterprise": false,
"minScore": 0.7,
"pageAction": "myverify"
}
}Resposta
{
"errorId":0,
"taskId":407533072
}Obter resultado da tarefa:
POST https://api.capmonster.cloud/getTaskResultRequisição
{
"clientKey":"API_KEY",
"taskId": 407533072
}Resposta
{
"errorId":0,
"status":"ready",
"solution": {
"gRecaptchaResponse":"3AHJ_VuvYIBNBW5yyv0zRYJ75VkOKvhKj9_xGBJKnQimF72rfoq3Iy-DyGHMwLAo6a3"
}
}O token retornado é então enviado ao seu servidor exatamente como seria o token de um usuário real, permitindo verificar todo o pipeline de validação — incluindo a lógica da sua recaptcha_secret_key — em um teste automatizado e repetível. O CapMonster Cloud oferece suporte a reCAPTCHA v2 (caixa de seleção e invisível), reCAPTCHA v3 e uma ampla variedade de outros tipos de CAPTCHA, tornando-o adequado para testes abrangentes de regressão da camada de proteção contra bots do seu site.
A documentação detalhada da API e exemplos de integração estão disponíveis em capmonster.cloud.
Conclusão
Sua reCAPTCHA secret key é a base da verificação de bots no lado do servidor — encontrá-la corretamente, integrá-la com segurança e protegê-la contra exposição são etapas inegociáveis para qualquer implantação em produção. Registre seu site no reCAPTCHA Admin Console ou no Google Cloud Console, mantenha a chave secreta exclusivamente no lado do servidor, armazenada em variáveis de ambiente, e valide todos os campos retornados pelo Google — não apenas o valor booleano success.
Para equipes que precisam automatizar o QA dos seus fluxos de CAPTCHA, o CapMonster Cloud oferece uma forma limpa e orientada por API de testar todo o ciclo de vida do token sem jamais expor sua chave privada. Comece a usar o CapMonster Cloud hoje mesmo e elimine de vez a resolução manual de CAPTCHA do seu pipeline de testes.
