---
title: "Autenticação por chave de API"
description: "A chave vai no header Authorization como Bearer, identifica a conta inteira e pode ser rotacionada sem interrupção. Nunca em query string, código versionado ou frontend."
canonical: "https://cnpj.ia.br/docs/autenticacao"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

docs · base agosto/2026 Atualizado em 02/09/2026

# Autenticação por chave de API

A chave vai no header Authorization como Bearer, identifica a conta inteira e pode ser rotacionada sem interrupção. Nunca em query string, código versionado ou frontend.

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](https://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

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

#### Python

```python
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())
```

#### Node

```javascript
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](https://cnpj.ia.br/docs/busca-empresas) não está disponível. O que cada plano inclui está em [`/precos`](https://cnpj.ia.br/precos) e no [OpenAPI](https://cnpj.ia.br/openapi/openapi.json), 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

| Status | Código | Quando | O que fazer |
| --- | --- | --- | --- |
| 401 | `invalid_api_key` | Header ausente, chave desconhecida ou revogada | Conferir a variável de ambiente; criar chave nova no portal se a antiga foi revogada |
| 401 | `key_expired` | A chave expirou | Criar chave nova no portal |
| 403 | `insufficient_plan` | Operação fora do plano da conta | Trocar de plano em `/precos`; a chave não muda |
| 403 | `payment_required` | Cobrança em atraso há mais de 7 dias | Regularizar o pagamento no portal; a chave volta a funcionar sem recriar |

Nenhum erro consome crédito. O envelope completo está em [Erros e retentativas](https://cnpj.ia.br/docs/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.

## Perguntas frequentes

**Posso ter mais de uma chave na mesma conta?**

Sim. Crie uma chave por sistema ou por ambiente. Todas gastam a mesma franquia e contam para o mesmo limite de requisições por minuto. Revogar uma não afeta as outras.

**A API aceita OAuth ou só chave?**

Só chave, no header `Authorization: Bearer`. A chave é da conta e serve para a API e para o servidor MCP. OAuth não faz parte do contrato `/v1`.

**Quanto tempo uma chave revogada continua funcionando?**

Na API, nenhum: a revogação vale na próxima requisição. No servidor MCP, a chave é validada com um cache de até 60 segundos, então chamadas feitas nessa janela ainda podem ser aceitas antes da recusa.

**O que acontece se eu passar a chave na URL?**

A API ignora a query string para autenticação e responde `401 invalid_api_key`. Se você fez isso em produção, considere a chave vazada, porque ela foi para logs no caminho; revogue e crie outra.