Authentication

Every request to the CPFHub.io API must be authenticated with an API key sent in the x-api-key header.

Getting your API key

When you create your account, an API key is generated automatically. Go to app.cpfhub.io/api-keys to view and copy it at any time.

If you need to, you can generate a new key on that same page. Each account has a single active key. When you generate a new one, the previous one stops working within 5 minutes and starts returning 401 with "API Key inativa" (inactive API key).

The key is an opaque string. Do not validate its prefix, length or format in your code.

Sending the API key

Include the x-api-key header in every request:

curl "https://api.cpfhub.io/cpf/12345678909" \
  -H "x-api-key: $CPFHUB_API_KEY"

Store the key in an environment variable (CPFHUB_API_KEY in the example) and read it from there in your code.

Base URL

All requests must use HTTPS:

https://api.cpfhub.io

Requests over http:// get a 301 redirect to HTTPS. Many HTTP clients turn a POST into a GET when they follow that redirect, which breaks the Real-Time Lookup and the batch lookup. Always use https://.

Authentication errors

The API only responds in Portuguese, so the error messages below are shown as returned, with the translation in parentheses.

In these cases the error field is a string:

{
  "success": false,
  "error": "API Key não fornecida"
}

The same API key works for all endpoints: Simple Lookup, Real-Time Lookup, Batch Lookup and credit balance.

For full details on every error, see Error Codes.

Updated on October 3, 2026