Autenticación con X-API-Key
Header simple. Sin OAuth, sin Bearer tokens, sin firmas HMAC. Una API key por entorno y HTTPS hace el resto.
Formato de la API key
Una API key de Normadata tiene 33 caracteres: un prefijo fijo y un cuerpo aleatorio que identifica la key en nuestros sistemas.
nd_— prefijo fijo (3 caracteres). Sirve para que cuando una key se filtre en logs o repos, sea fácil grep-earla.- Cuerpo: 22 caracteres base62 (a-z, A-Z, 0-9). Generado con un CSPRNG.
- Total: 33 caracteres. La longitud es estable.
- Ejemplo:
nd_a1b2c3d4e5f6g7h8i9j0k1
nd_ prefix (3 chars)
xxxxxxxxxxxxxxxxxxxxxx base62 random (22 chars)
─────────────────────
nd_a1b2c3d4e5f6g7h8i9j0k1 (33 chars total)Cómo autenticar
Mandá el header X-API-Key en cada request. No hace falta nada más — sin handshake, sin endpoint de token, sin refresh. El header solo 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"}'Buenas prácticas
Las keys son secretos. Tratalas como tales.
- NUNCA committees keys al repo. Usá variables de entorno: NORMADATA_API_KEY o equivalente.
- NUNCA expongas la key en código client-side (browser, app móvil). Las validaciones tienen que ir desde tu backend o desde una función edge tuya — nunca desde el navegador del usuario.
- Rotá keys regularmente. Hoy la rotación es manual vía soporte (pedinos una nueva, ponemos la vieja en sunset por 7 días, después la revocamos). Self-serve está en el roadmap.
- Una key por entorno: dev, staging, prod. Si una se filtra solo afecta un entorno y no rompés producción al rotar la de dev.
Request signing
No usamos request signing (HMAC, AWS Signature, JWT firmado, etc.). La autenticación es por header de API key sobre HTTPS. La transport security viene de TLS — no agregamos una capa adicional de firma en el body.
La complejidad de HMAC se justifica cuando el canal no es trusted o cuando hay que evitar replay attacks en el mismo canal. Sobre TLS 1.2+, con keys rotables y short-lived (cuando tengamos rotación self-serve), el header simple cubre el threat model.
Sandbox keys
Las sandbox keys self-serve están en roadmap. Mientras tanto, si necesitás una key separada para tests, mencionalo cuando te sumes a la lista de espera y te emitimos una key con cuota baja sin cargo.