# Autenticação em APIs REST: Como Garantir Segurança na Consulta de CPF > Aprenda os métodos de autenticação em APIs REST e como garantir segurança na consulta de CPF. Guia com API keys, OAuth2 e boas práticas. **Publicado:** 05/01/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/autenticacao-apis-rest-seguranca-consulta-cpf --- APIs REST que consultam CPF lidam com dados pessoais protegidos pela LGPD, tornando a autenticação um requisito crítico e não opcional. A CPFHub.io utiliza API Key no header `x-api-key` — um método simples e eficaz quando combinado com variáveis de ambiente, secret managers e um proxy de backend para proteger a chave e os dados dos usuários. ## Introdução A consulta de CPF envolve dados pessoais sensíveis protegidos pela LGPD, tornando a autenticação um requisito crítico e não opcional. APIs REST utilizam diferentes métodos de autenticação para controlar o acesso, rastrear o uso e proteger tanto os dados quanto os consumidores. Este guia explica como autenticar corretamente na API da CPFHub.io e quais práticas de segurança adotar para proteger suas chaves e os dados dos usuários. --- ## Métodos de autenticação em APIs REST Existem diversos métodos de autenticação, cada um com trade-offs entre segurança, complexidade e usabilidade. | Método | Segurança | Complexidade | Caso de uso | |--------|-----------|-------------|-------------| | **API Key** | Média | Baixa | APIs públicas com controle de uso | | **Bearer Token (JWT)** | Alta | Média | APIs com autenticação de usuário | | **OAuth 2.0** | Muito alta | Alta | APIs com delegação de acesso | | **Basic Auth** | Baixa | Muito baixa | Ambientes de teste apenas | | **mTLS** | Muito alta | Muito alta | APIs críticas B2B | - **API Key** -- um identificador único enviado no header, simples de implementar e suficiente para a maioria dos cenários - **Bearer Token** -- token temporário obtido após autenticação, oferece expiração automática - **OAuth 2.0** -- protocolo completo para delegação de acesso entre serviços, usado por grandes plataformas - **mTLS** -- autenticação mútua com certificados, reservada para cenários de máxima segurança --- ## Implementando autenticação com API Key A API do CPFHub.io utiliza autenticação via **API Key** no header `x-api-key`. Veja como implementar corretamente em Python e JavaScript. ```python # Python - Autenticação com API Key import requests import os class CPFClient: def __init__(self): self.api_key = os.environ.get("CPFHUB_API_KEY") if not self.api_key: raise ValueError("CPFHUB_API_KEY não configurada") self.session = requests.Session() self.session.headers.update({ "x-api-key": self.api_key, "Content-Type": "application/json", "User-Agent": "MeuApp/1.0" }) self.base_url = "https://api.cpfhub.io/cpf" def consultar(self, cpf: str) -> dict: cpf_limpo = "".join(c for c in cpf if c.isdigit()) response = self.session.get(f"{self.base_url}/{cpf_limpo}") response.raise_for_status() return response.json() # Uso client = CPFClient() resultado = client.consultar("123.456.789-09") print(resultado["data"]["name"]) ``` ```javascript // JavaScript - Autenticação com API Key class CPFClient { constructor() { this.apiKey = process.env.CPFHUB_API_KEY; if (!this.apiKey) { throw new Error("CPFHUB_API_KEY não configurada"); } this.baseUrl = "https://api.cpfhub.io/cpf"; } async consultar(cpf) { const cpfLimpo = cpf.replace(/\D/g, ""); const response = await fetch(`${this.baseUrl}/${cpfLimpo}`, { headers: { "x-api-key": this.apiKey, "Content-Type": "application/json", }, }); if (!response.ok) { throw new Error(`Erro HTTP: ${response.status}`); } return response.json(); } } // Uso const client = new CPFClient(); const resultado = await client.consultar("123.456.789-09"); console.log(resultado.data.name); ``` - **Session/headers persistentes** -- configurar headers uma vez e reutilizar em todas as requisições - **Variável de ambiente** -- a chave nunca deve estar no código fonte ou em repositórios - **raise_for_status** -- lança exceção automática para respostas com status de erro --- ## Protegendo a API Key em diferentes ambientes A forma de armazenar e acessar a API key muda conforme o ambiente de execução. ```python # Python - Diferentes formas de carregar a API key # 1. Variável de ambiente (recomendado para produção) import os api_key = os.environ["CPFHUB_API_KEY"] # 2. Arquivo .env com python-dotenv (desenvolvimento) from dotenv import load_dotenv load_dotenv() api_key = os.environ["CPFHUB_API_KEY"] # 3. Secret manager (produção em cloud) import boto3 def get_api_key_from_aws(): client = boto3.client("secretsmanager", region_name="us-east-1") response = client.get_secret_value(SecretId="cpfhub/api-key") return response["SecretString"] ``` ```javascript // JavaScript - Proteção da API key // 1. Variável de ambiente (Node.js) const apiKey = process.env.CPFHUB_API_KEY; // 2. Arquivo .env com dotenv require("dotenv").config(); const apiKey = process.env.CPFHUB_API_KEY; // 3. NUNCA faça isto no frontend // const apiKey = "sk-abc123"; // ERRADO - exposto no bundle ``` | Ambiente | Método recomendado | Risco se exposta | |----------|-------------------|-----------------| | Desenvolvimento | Arquivo .env (no .gitignore) | Baixo | | CI/CD | Secrets do pipeline | Médio | | Produção (cloud) | Secret Manager (AWS/GCP/Azure) | Alto | | Frontend browser | Proxy no backend | Crítico | - **Nunca no frontend** -- API keys no código do browser são visíveis para qualquer pessoa - **Proxy pattern** -- o frontend chama seu backend, que adiciona a API key e repassa à API - **Rotação de chaves** -- troque a API key periodicamente e revogue chaves comprometidas --- ## Implementando um proxy seguro para frontend Se seu frontend precisa consultar CPFs, crie um proxy no backend que adiciona a autenticação. ```javascript // Node.js/Express - Proxy seguro const express = require("express"); const rateLimit = require("express-rate-limit"); const app = express(); const limiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 100, message: { error: "Muitas requisições. Tente novamente em 15 minutos." }, }); app.get("/api/cpf/:cpf", limiter, async (req, res) => { const { cpf } = req.params; const cpfLimpo = cpf.replace(/\D/g, ""); if (cpfLimpo.length !== 11) { return res.status(400).json({ error: "CPF inválido" }); } try { const response = await fetch( `https://api.cpfhub.io/cpf/${cpfLimpo}`, { headers: { "x-api-key": process.env.CPFHUB_API_KEY }, } ); const data = await response.json(); // Filtrar campos sensíveis antes de enviar ao frontend if (data.success) { res.json({ success: true, data: { nome: data.data.name, nascimento: data.data.birthDate, }, }); } else { res.status(404).json({ error: "CPF não encontrado" }); } } catch { res.status(500).json({ error: "Erro interno" }); } }); app.listen(3000); ``` - **Rate limiting** -- limita requisições por IP para evitar abuso do seu proxy - **Filtragem de campos** -- envie ao frontend apenas os dados necessários, minimizando exposição - **Proxy transparente** -- o frontend não sabe que existe uma API externa, interagindo apenas com seu backend --- ## Perguntas frequentes ### Por que usar API Key em vez de OAuth 2.0 para consultar CPF? Para a maioria dos cenários de consulta de CPF em backend, a API Key é suficiente e significativamente mais simples. OAuth 2.0 faz sentido quando há delegação de acesso entre diferentes sistemas ou quando o token precisa ter escopo e expiração automática. A CPFHub.io usa API Key no header `x-api-key` — segura quando armazenada em variáveis de ambiente ou secret managers e nunca exposta no frontend. ### O que acontece se minha API Key for exposta? Revogue a chave imediatamente no painel da CPFHub.io e gere uma nova. Além disso, audite os logs de consulta para identificar uso indevido. Para evitar recorrência, nunca armazene a chave no código-fonte, use `.gitignore` para arquivos `.env` e configure alertas de consumo anormal em [app.cpfhub.io/settings/billing](https://app.cpfhub.io/settings/billing). ### Como proteger a API Key em uma aplicação frontend (React, Vue, Angular)? Nunca inclua a API Key no bundle do frontend — qualquer usuário pode inspecionar o código e extraí-la. O padrão correto é criar um endpoint de proxy no seu backend (Node.js, Python, PHP, etc.) que recebe a requisição do frontend, adiciona o header `x-api-key` e repassa à API da CPFHub.io. O frontend só conhece seu próprio backend. ### A LGPD impõe requisitos específicos sobre autenticação em APIs que consultam CPF? Sim. A [LGPD (Lei nº 13.709/2018)](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm) exige que o acesso a dados pessoais seja controlado, auditável e proporcional à finalidade. Isso implica usar autenticação robusta (API Key com rotação periódica ou tokens com expiração), registrar logs de acesso, aplicar o princípio do menor privilégio e não armazenar dados além do necessário. A ANPD orienta que controles técnicos de acesso fazem parte das medidas de segurança exigidas. ### Leia também - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf) --- ## Conclusão A autenticação é a primeira linha de defesa ao consumir APIs de dados sensíveis como CPF. A API do CPFHub.io utiliza API Key no header, um método simples e eficaz quando combinado com boas práticas de segurança: variáveis de ambiente, secret managers, proxy para frontends e rate limiting. Nunca exponha chaves de API no código do browser e sempre filtre os dados antes de enviá-los ao cliente. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e configure uma integração segura com a API de CPF em menos de 30 minutos.