Autenticação e segurança

Os endpoints públicos de dados aceitam uma API key no header X-API-Key. A exigência é controlada por ambiente; em produção, a configuração recomendada é API_REQUIRE_KEY=true.

GET /v1/cnpjs/00000000000191 HTTP/1.1
Host: api.seudominio.com
X-API-Key: cnpj_live_...

Formato e ciclo de vida

As chaves novas usam prefixos que identificam o ambiente:

• cnpj_dev_ para desenvolvimento;
• cnpj_test_ para revisão ou staging;
• cnpj_live_ para produção.

O segredo completo é exibido somente na criação. O banco guarda um hash SHA-256 e um prefixo identificador, não o segredo. A expiração padrão da ferramenta administrativa é 90 dias, mas prazo comercial, autoatendimento, rotação sobreposta e recuperação ainda estão a confirmar.

Uma chave ausente, desconhecida, expirada ou revogada retorna 401:

{ "detail": "API key ausente, invalida, expirada ou revogada" }

Proteja a chave

• use variáveis de ambiente ou um gerenciador de segredos;
• nunca use NEXT_PUBLIC_*, bundle frontend, aplicativo móvel ou repositório público;
• não registre headers completos em logs, APM ou tickets;
• use chaves diferentes por ambiente e cliente;
• revogue imediatamente uma chave suspeita e faça rotação antes da expiração.

Playground

A referência permite informar X-API-Key e executar apenas os endpoints GET publicados no OpenAPI. As chamadas saem diretamente do navegador para a URL configurada; o portal não atua como proxy e não recebe a chave no servidor.

O playground público substitui o executor padrão por um formulário próprio: a chave existe somente no estado React da página, não usa localStorage, sessionStorage, cookie ou URL, e desaparece ao recarregar ou sair. O controle Limpar credenciais apaga o estado imediatamente. Prefira uma chave de desenvolvimento/revisão e não use uma chave de produção em computador compartilhado.

O playground depende do CORS da API. Em produção, API_CORS_ORIGINS deve conter exatamente o domínio HTTPS do portal; curingas não são usados com credenciais.

Administração

Rotas /v1/admin/* usam Bearer token separado e não aparecem no OpenAPI público. Uma API key pública nunca concede acesso administrativo.