Autenticação
Todas as requisições à API do CPFHub.io precisam ser autenticadas com uma API Key enviada no header x-api-key.
Obtendo sua API Key
Ao criar sua conta, uma API Key já é gerada automaticamente. Basta acessar app.cpfhub.io/api-keys para visualizá-la e copiá-la a qualquer momento.
Se precisar, você pode gerar uma nova chave nessa mesma página. Cada conta tem uma única chave ativa: ao gerar uma nova, a anterior para de funcionar em até 5 minutos e passa a responder 401 com "API Key inativa".
Trocando a chave em produção
Não existe período com duas chaves válidas. Gere a nova chave só quando puder atualizar o segredo do seu sistema logo em seguida, para não interromper as consultas.
A chave é uma string opaca. Não valide prefixo, tamanho ou formato no seu código.
Guarde sua chave com segurança
Nunca exponha sua API Key em código client-side, repositórios públicos ou logs. Use variáveis de ambiente.
Enviando a API Key
Inclua o header x-api-key em todas as requisições:
curl "https://api.cpfhub.io/cpf/12345678909" \
-H "x-api-key: $CPFHUB_API_KEY"Guarde a chave numa variável de ambiente (no exemplo, CPFHUB_API_KEY) e leia de lá no seu código.
URL base
Todas as requisições devem usar HTTPS:
https://api.cpfhub.ioRequisições via http:// recebem um redirecionamento 301 para HTTPS. Muitos clientes HTTP transformam um POST em GET ao seguir esse redirecionamento, o que quebra a Consulta em Tempo Real e a consulta em lote. Use sempre https://.
Erros de autenticação
| Código | Mensagem (error) | Quando |
|---|---|---|
401 | API Key não fornecida | O header x-api-key não foi enviado |
401 | API Key inválida | A chave não existe |
401 | API Key inativa | A chave foi substituída por uma nova no dashboard |
403 | Usuário inativo. Entre em contato com o suporte. | Conta desativada |
403 | Conta bloqueada. Entre em contato com o suporte. | Conta bloqueada |
Nesses casos o campo error é uma string:
{
"success": false,
"error": "API Key não fornecida"
}A mesma API Key vale para todos os endpoints: Consulta Simples, Consulta em Tempo Real, Consulta em Lote, Consulta de CNPJ, CNPJ em Lote e saldo de créditos.
Para detalhes completos sobre todos os erros, veja Códigos de Erro.
Atualizado em 15 de outubro de 2026