# API de consulta de CPF: como funciona a autenticação via API key > Entenda como a autenticação via API key funciona em APIs de consulta de CPF, como gerar e proteger sua chave de acesso. **Publicado:** 02/06/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-consulta-cpf-autenticacao-api-key --- A autenticação via API key é o mecanismo que controla quem pode consultar dados de CPF em uma API REST. Ela funciona como uma senha única da aplicação: cada requisição ao endpoint `GET https://api.cpfhub.io/cpf/{CPF}` precisa incluir o header `x-api-key` com a chave da sua conta. Sem ela, a resposta é um 401 Unauthorized imediato. Com ela, a API devolve nome, data de nascimento e gênero do titular em menos de um segundo. ## Introdução Toda API que lida com dados sensíveis precisa de um mecanismo de autenticação robusto. No caso de APIs de consulta de CPF, a autenticação garante que apenas aplicações autorizadas possam acessar informações cadastrais — um requisito para conformidade com a LGPD. --- ## O que é uma API key Uma API key é uma string única que identifica e autentica a sua aplicação perante um serviço de API. Ela funciona como uma "senha" que: * **Identifica** quem está fazendo a requisição. * **Autoriza** o acesso aos recursos da API. * **Rastreia** o consumo de consultas por conta. * **Controla** os limites de uso (rate limiting). Diferente de métodos como OAuth 2.0, a autenticação por API key é mais simples e direta — ideal para comunicações server-to-server onde não há interação de usuário final. A [ANPD](https://www.gov.br/anpd) recomenda que dados de autenticação para acesso a dados pessoais sejam mantidos em ambientes controlados e auditáveis. --- ## Como funciona na CPFHub.io A API da CPFHub.io utiliza o header `x-api-key` para autenticação. Cada requisição deve incluir esse header com a chave válida da sua conta. ### Exemplo de requisição autenticada ```bash curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" \ --max-time 15 ``` ### Resposta bem-sucedida ```json { "success": true, "data": { "cpf": "12345678900", "name": "Joao da Silva", "nameUpper": "JOAO DA SILVA", "gender": "M", "birthDate": "15/06/1990", "day": 15, "month": 6, "year": 1990 } } ``` ### Resposta com chave inválida (401) Se a API key estiver ausente, expirada ou inválida, a API retorna status 401 Unauthorized. --- ## Como gerar sua API key O processo para obter uma API key na CPFHub.io é simples: 1. Crie uma conta gratuita em cpfhub.io (sem cartão de crédito). 2. Acesse o painel de controle em app.cpfhub.io. 3. Navegue até a seção de Chaves de API. 4. Gere uma nova chave. 5. Copie a chave imediatamente — por segurança, ela pode não ser exibida novamente. O plano gratuito já inclui 50 consultas por mês, permitindo testar a integração antes de contratar um plano pago. --- ## Autenticação via header vs. query string Existem duas formas comuns de enviar API keys: | Método | Exemplo | Segurança | | --- | --- | --- | | Header (recomendado) | `x-api-key: SUA_CHAVE` | Alta — não aparece em logs de URL | | Query string | `?api_key=SUA_CHAVE` | Baixa — exposta em logs, histórico e cache | A CPFHub.io utiliza autenticação via header, que é a abordagem mais segura. A chave nunca aparece na URL, reduzindo o risco de exposição em logs de servidor, proxies ou ferramentas de monitoramento. --- ## Implementando a autenticação em diferentes linguagens ### Python ```python import requests headers = { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' } response = requests.get( 'https://api.cpfhub.io/cpf/12345678900', headers=headers, timeout=15 ) if response.status_code == 401: print('Chave de API inválida ou ausente') elif response.status_code == 200: data = response.json() print(data) ``` ### Node.js ```javascript async function consultarCPF(cpf) { const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, { method: 'GET', headers: { 'x-api-key': process.env.CPFHUB_API_KEY, 'Accept': 'application/json' }, signal: AbortSignal.timeout(15000) }); if (response.status === 401) { throw new Error('Chave de API inválida ou ausente'); } return response.json(); } ``` ### PHP ```php "https://api.cpfhub.io/cpf/{$cpf}", CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15, CURLOPT_HTTPHEADER => [ 'x-api-key: SUA_CHAVE_DE_API', 'Accept: application/json' ], ]); $response = curl_exec($curl); $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($httpCode === 401) { echo 'Chave de API inválida ou ausente'; } else { $data = json_decode($response, true); print_r($data); } ``` --- ## Tratamento de erros de autenticação Ao integrar a API, trate sempre os possíveis cenários de erro relacionados à autenticação: * **401 Unauthorized** — Chave inválida, expirada ou ausente. Verifique se a variável de ambiente está configurada corretamente. * **403 Forbidden** — Acesso negado ao recurso. Verifique as permissões da sua conta. Importante: a CPFHub.io não bloqueia a aplicação ao atingir o limite do plano. Consultas acima da cota mensal são cobradas a R$0,15 cada, garantindo continuidade operacional sem interrupções. --- ## Boas práticas de segurança * **Nunca exponha a chave no frontend** — API keys devem ser usadas apenas no backend (server-to-server). * **Use variáveis de ambiente** — Nunca hardcode a chave no código-fonte. * **Rotacione periodicamente** — Gere novas chaves e desative as antigas regularmente. * **Restrinja por IP quando possível** — Limite o uso da chave a IPs conhecidos. * **Não commite em repositórios** — Adicione arquivos como `.env` ao `.gitignore`. * **Monitore o uso** — Acompanhe o consumo pelo dashboard para detectar acessos não autorizados. --- ## Perguntas frequentes ### Como o header `x-api-key` diferencia uma requisição autorizada de uma não autorizada? A API valida o valor do header `x-api-key` contra o banco de chaves ativas da conta. Se a chave não existir, estiver revogada ou pertencer a outra conta, a resposta é 401 Unauthorized antes de qualquer processamento do CPF. Isso garante que nenhum dado pessoal seja exposto sem autenticação válida. ### O que acontece se eu atingir o limite de consultas do meu plano? A CPFHub.io não bloqueia a aplicação. Ao ultrapassar o limite mensal (50 consultas no plano gratuito, 1.000 no Pro), cada consulta adicional é cobrada a R$0,15 automaticamente. O serviço segue respondendo normalmente, sem retornar erros de quota. ### Posso usar a mesma API key em múltiplos ambientes (dev, staging, prod)? Tecnicamente é possível, mas não é recomendado. Gere chaves separadas por ambiente para ter controle granular do consumo, facilitar a rotação e isolar eventuais vazamentos. O painel da CPFHub.io permite criar múltiplas chaves para a mesma conta. ### Como garantir conformidade com a LGPD ao usar autenticação via API key? Armazene a chave apenas em variáveis de ambiente no servidor, nunca no código-fonte ou em logs. Registre cada consulta com timestamp e finalidade. A [ANPD](https://www.gov.br/anpd) orienta que o acesso a dados pessoais deve ser controlado, auditável e restrito ao mínimo necessário. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## Conclusão A autenticação via API key é o mecanismo central de segurança para consultas de CPF via API. Entender como ela funciona e seguir as boas práticas de proteção da chave são passos essenciais para manter a integridade e a conformidade da sua integração. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.