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

> Aprenda as melhores práticas para armazenar e gerenciar API keys de consulta de CPF de forma segura em diferentes ambientes.

**Publicado:** 12/12/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/api-cpf-melhores-praticas-armazenar-api-keys-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](https://owasp.org/) 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)

```bash
# .env
CPFHUB_API_KEY=SUA_CHAVE_DE_API
```

### Python

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

```javascript
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

```python
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

```python
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

```python
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

```yaml
# 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
```

```python
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

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

```yaml
# 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:

```python
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.

```python
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](https://www.gov.br/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.

### 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)
- [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos)
- [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 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.