API de CPF: melhores práticas para armazenar API keys de forma segura

Armazenar API keys de CPF de forma segura é tão importante quanto a própria validação: uma chave comprometida expõe dados pessoais, consome sua cota e gera risco de conformidade com a LGPD. O OWASP recomenda nunca inserir credenciais no código-fonte — use variáveis de ambiente, secret managers e rotação periódica para proteger sua chave da CPFHub.io em qualquer ambiente.

Introdução

Uma API key comprometida pode expor dados sensíveis de CPF, consumir toda a sua cota e gerar problemas de conformidade com a LGPD. Apesar disso, é surpreendentemente comum encontrar chaves de API hardcoded em código-fonte, commitadas em repositórios públicos ou armazenadas em arquivos de configuração sem proteção.

O que NUNCA fazer

Antes das boas práticas, veja os erros mais comuns:

• Hardcode no código -- api_key = "sk_live_abc123" diretamente no código-fonte.

• Commit em repositório -- Chave no .env que foi commitado por engano.

• Frontend exposto -- API key no JavaScript do navegador, visível para qualquer usuário.

• Logs não filtrados -- Chave impressa em logs de debug.

• Compartilhamento por chat -- Chave enviada por Slack, e-mail ou WhatsApp sem criptografia.

Prática 1: Variáveis de ambiente

A forma mais básica e amplamente adotada:

.env file (desenvolvimento local)

# .env
CPFHUB_API_KEY=SUA_CHAVE_DE_API

Python

import os
import requests

api_key = os.environ.get('CPFHUB_API_KEY')
if not api_key:
    raise ValueError('CPFHUB_API_KEY nao configurada')

headers = {
    'x-api-key': api_key,
    'Accept': 'application/json'
}

response = requests.get(
    'https://api.cpfhub.io/cpf/12345678900',
    headers=headers,
    timeout=15
)

Node.js

const apiKey = process.env.CPFHUB_API_KEY;
if (!apiKey) {
    throw new Error('CPFHUB_API_KEY nao configurada');
}

const response = await fetch('https://api.cpfhub.io/cpf/12345678900', {
    method: 'GET',
    headers: {
    'x-api-key': apiKey,
    'Accept': 'application/json'
    },
    signal: AbortSignal.timeout(15000)
});

Proteção do .env

Adicione ao .gitignore imediatamente:

# .gitignore
.env
.env.local
.env.production

Prática 2: Secret managers em cloud

Para ambientes de produção, use o gerenciador de segredos do seu provedor cloud:

AWS Secrets Manager

import boto3
import json
import requests

def obter_api_key():
    client = boto3.client('secretsmanager', region_name='us-east-1')
    response = client.get_secret_value(SecretId='cpfhub/api-key')
    secret = json.loads(response['SecretString'])
    return secret['api_key']

api_key = obter_api_key()
headers = {
    'x-api-key': api_key,
    'Accept': 'application/json'
}

response = requests.get(
    'https://api.cpfhub.io/cpf/12345678900',
    headers=headers,
    timeout=15
)

Google Secret Manager

from google.cloud import secretmanager

def obter_api_key():
    client = secretmanager.SecretManagerServiceClient()
    name = "projects/meu-projeto/secrets/cpfhub-api-key/versions/latest"
    response = client.access_secret_version(request={"name": name})
    return response.payload.data.decode("UTF-8")

Azure Key Vault

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

def obter_api_key():
    credential = DefaultAzureCredential()
    client = SecretClient(
    vault_url="https://meu-vault.vault.azure.net/",
    credential=credential
    )
    secret = client.get_secret("cpfhub-api-key")
    return secret.value

Prática 3: Docker e containers

Docker secrets

# docker-compose.yml
version: '3.8'
services:
    app:
    image: minha-app
    secrets:
    - cpfhub_api_key
    environment:
    - CPFHUB_API_KEY_FILE=/run/secrets/cpfhub_api_key

secrets:
    cpfhub_api_key:
    file: ./secrets/cpfhub_api_key.txt

import os

def obter_api_key():
    # Tentar Docker secret primeiro
    secret_file = os.environ.get('CPFHUB_API_KEY_FILE')
    if secret_file and os.path.exists(secret_file):
    with open(secret_file, 'r') as f:
    return f.read().strip()

    # Fallback para variavel de ambiente
    return os.environ.get('CPFHUB_API_KEY')

Kubernetes secrets

# secret.yaml
apiVersion: v1
kind: Secret
metadata:
    name: cpfhub-credentials
type: Opaque
data:
    api-key: U1VBX0NIQVZFX0RFX0FQSQ== # base64 encoded

# deployment.yaml
spec:
    containers:
    - name: app
    env:
    - name: CPFHUB_API_KEY
    valueFrom:
    secretKeyRef:
    name: cpfhub-credentials
    key: api-key

Prática 4: Rotação de chaves

Troque a API key periodicamente para limitar o impacto de um possível vazamento:

import os
from datetime import datetime

class GerenciadorChaves:
    def __init__(self):
    self.chave_primaria = os.environ.get('CPFHUB_API_KEY_PRIMARY')
    self.chave_secundaria = os.environ.get('CPFHUB_API_KEY_SECONDARY')

    def obter_chave_ativa(self):
    """Retorna a chave primaria, com fallback para a secundaria."""
    return self.chave_primaria or self.chave_secundaria

    def testar_chave(self, chave):
    """Verifica se a chave ainda esta valida."""
    import requests
    response = requests.get(
    'https://api.cpfhub.io/cpf/00000000000',
    headers={
    'x-api-key': chave,
    'Accept': 'application/json'
    },
    timeout=15
    )
    return response.status_code != 401

O processo de rotação:

1. Gere uma nova chave no dashboard (app.cpfhub.io).
2. Configure a nova chave como CPFHUB_API_KEY_SECONDARY.
3. Teste a nova chave.
4. Promova para CPFHUB_API_KEY_PRIMARY.
5. Desative a chave antiga.

Prática 5: Auditoria e monitoramento

• Monitore o uso -- Acompanhe o consumo pelo dashboard da CPFHub.io para detectar uso anômalo.

• Alertas de consumo atípico -- Configure alertas se o consumo ultrapassar padrões históricos.

• Logs sem chave -- Nunca registre a API key em logs. Use mascaramento.

def mascarar_chave(chave):
    if len(chave) <= 8:
    return '****'
    return chave[:4] + '****' + chave[-4:]

# Em logs
print(f'Usando chave: {mascarar_chave(api_key)}')
# Saida: Usando chave: sk_l****c123

Checklist de segurança

• API key NUNCA no código-fonte.

• .env no .gitignore.

• Variável de ambiente para desenvolvimento local.

• Secret manager para produção.

• API key NUNCA no frontend.

• Rotação periódica de chaves.

• Logs com chave mascarada.

• Monitoramento de uso anômalo.

• Chave diferente por ambiente (dev, staging, prod).

O que fazer se a chave vazar

1. Revogue imediatamente a chave no dashboard (app.cpfhub.io).
2. Gere uma nova chave.
3. Atualize a configuração em todos os ambientes.
4. Verifique os logs de uso para identificar acesso não autorizado.
5. Investigue como o vazamento ocorreu.
6. Implemente medidas para prevenir recorrência.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em ~900ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

A API key é a porta de entrada para dados sensíveis de CPF. Protegê-la adequadamente é uma responsabilidade técnica e legal, especialmente em contextos de conformidade com a LGPD. Com variáveis de ambiente, secret managers, rotação periódica e monitoramento, você reduz drasticamente o risco de comprometimento.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.