API de consulta de CPF: como funciona a autenticação via 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 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

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

{
    "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:

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

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

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
$cpf = '12345678900';
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "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 orienta que o acesso a dados pessoais deve ser controlado, auditável e restrito ao mínimo necessário.

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 — 50 consultas mensais gratuitas, sem cartão de crédito.