Autenticação com X-API-Key
Header simples. Sem OAuth, sem Bearer tokens, sem assinaturas HMAC. Uma API key por ambiente e o HTTPS faz o resto.
Formato da API key
Uma API key da Normadata tem 33 caracteres: um prefixo fixo e um corpo aleatório que identifica a key nos nossos sistemas.
nd_— prefixo fixo (3 caracteres). Serve pra quando uma key vaza em logs ou repos ficar fácil de grepar.- Corpo: 22 caracteres base62 (a-z, A-Z, 0-9). Gerado com um CSPRNG.
- Total: 33 caracteres. O tamanho é estável.
- Exemplo:
nd_a1b2c3d4e5f6g7h8i9j0k1
nd_ prefix (3 chars)
xxxxxxxxxxxxxxxxxxxxxx base62 random (22 chars)
─────────────────────
nd_a1b2c3d4e5f6g7h8i9j0k1 (33 chars total)Como autenticar
Manda o header X-API-Key em cada request. Não precisa mais nada — sem handshake, sem endpoint de token, sem refresh. O header só se aplica a https://api.normadata.io/v1/* sobre HTTPS.
$ curl -X POST https://api.normadata.io/v1/verify/tax-id \
-H "X-API-Key: nd_a1b2c3d4e5f6g7h8i9j0k1" \
-H "Content-Type: application/json" \
-d '{"value":"20-12345678-3","country":"AR"}'Boas práticas
Keys são segredos. Trata como tais.
- NUNCA commita keys no repo. Usa variáveis de ambiente: NORMADATA_API_KEY ou equivalente.
- NUNCA expõe a key em código client-side (browser, app mobile). As validações têm que rodar do seu backend ou de uma função edge sua — nunca do navegador do usuário.
- Rotaciona keys regularmente. Hoje a rotação é manual via suporte (a gente emite uma nova, coloca a antiga em sunset por 7 dias, depois revoga). Self-serve está no roadmap.
- Uma key por ambiente: dev, staging, prod. Se uma vaza, só afeta um ambiente e você não quebra produção ao rotacionar a de dev.
Request signing
A gente não usa request signing (HMAC, AWS Signature, JWT assinado, etc.). A autenticação é por header de API key sobre HTTPS. A transport security vem do TLS — não adicionamos uma camada extra de assinatura no body.
A complexidade do HMAC se justifica quando o canal não é trusted ou quando precisa evitar replay attacks no mesmo canal. Sobre TLS 1.2+, com keys rotáveis e short-lived (quando tivermos rotação self-serve), o header simples cobre o threat model.
Sandbox keys
As sandbox keys self-serve estão no roadmap. Enquanto isso, se precisar de uma key separada pra testes, menciona quando entrar na lista de espera e a gente emite uma key com cota baixa sem custo.