CPFHub.io

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:

bash
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.io

Requisiçõ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ódigoMensagem (error)Quando
401API Key não fornecidaO header x-api-key não foi enviado
401API Key inválidaA chave não existe
401API Key inativaA chave foi substituída por uma nova no dashboard
403Usuário inativo. Entre em contato com o suporte.Conta desativada
403Conta bloqueada. Entre em contato com o suporte.Conta bloqueada

Nesses casos o campo error é uma string:

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