Autenticação em APIs REST: Como Garantir Segurança na Consulta de 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.

• 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 - 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 - 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 - 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 - 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

• 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.

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

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) 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.

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 — 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.