Como encontrar e usar sua chave secreta do reCAPTCHA

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.

Chave	Também conhecida como	Onde fica	O que faz
Chave do site	chave pública do reCAPTCHA	Frontend (HTML, JS)	Renderiza o widget CAPTCHA no navegador
Chave secreta	chave privada do reCAPTCHA	Backend (somente servidor)	Verifica o token do usuário com a API do Google

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:

Tipo	O que o usuário vê	Mais indicado para
reCAPTCHA v2 — caixa de seleção "I'm not a robot"	Caixa de seleção, pode acionar desafio com imagens	Formulários de login, formulários de contato, seções de comentários
reCAPTCHA v2 — Invisível	Sem widget visível; o desafio é acionado no envio do formulário	Fluxos de checkout, formulários de cadastro em que a UX é crítica
reCAPTCHA v2 — Android	Integração nativa com Android SDK	Aplicativos móveis
reCAPTCHA v3	Totalmente invisível, retorna uma pontuação de risco (0.0–1.0)	Monitoramento de várias ações em todo o site

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/createTask

Requisiçã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/getTaskResult

Requisiçã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.