Autenticação por chave de API

Toda chamada a /v1, exceto GET /v1/status e GET /v1/demo, leva a chave da conta no header Authorization: Bearer <chave>. A chave é criada e revogada em app.cnpj.ia.br, aparece uma única vez e identifica a conta, não a pessoa: créditos, plano e limite de requisições por minuto são da conta, e todas as chaves dela somam.

Como enviar a chave

Só no header. A API não aceita chave em query string nem em cookie, e uma URL com chave acaba em log de proxy, histórico de navegador e sistema de monitoramento.

curl "https://api.cnpj.ia.br/v1/usage" \
  -H "Authorization: Bearer $CNPJIA_KEY"

import os, requests

s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['CNPJIA_KEY']}"
print(s.get("https://api.cnpj.ia.br/v1/usage", timeout=10).json())

const headers = { Authorization: `Bearer ${process.env.CNPJIA_KEY}` };
const res = await fetch("https://api.cnpj.ia.br/v1/usage", { headers });
console.log(await res.json());

O formato da chave é cnpj_live_ seguido do segredo. O prefixo existe para que scanners de segredo em repositórios reconheçam o padrão; trate qualquer string com esse prefixo como credencial.

O que a chave dá acesso

A chave autoriza as operações do plano da conta. Uma operação fora do plano responde 403 insufficient_plan sem consumir crédito: no Free, por exemplo, a busca de empresas não está disponível. O que cada plano inclui está em /precos e no OpenAPI, campo x-plan-min de cada operação.

Não existe escopo por chave no v0: toda chave da conta tem os mesmos direitos. Se você precisa isolar um sistema, crie uma chave por sistema: revogar uma não afeta as outras.

Erros de autenticação

Nenhum erro consome crédito. O envelope completo está em Erros e retentativas.

Rotação e revogação

Para trocar uma chave sem parar o sistema: crie a nova no portal, troque no cliente, confirme que as chamadas passam e revogue a antiga. Na API, a revogação vale imediatamente. No servidor MCP, que valida a chave com um cache curto, a chave revogada pode ser aceita por até 60 segundos; depois disso é recusada.

Revogue na hora se a chave apareceu em um commit, em um log ou em uma captura de tela. Não há como “desvazar” uma chave; a única ação segura é substituí-la.

Endpoints sem chave

GET /v1/status devolve a data da base e o estado do serviço; GET /v1/demo?cnpj= devolve o perfil full de uma lista fixa de instituições públicas, sem sócios. Custam 0 e 0 créditos, aceitam CORS e têm limite por IP. São feitos para páginas públicas e para testes antes de criar a conta, não para uso em produção.