Autenticacion
Tu API key es como un gafete de acceso: lo pasas por el lector (header Authorization) en cada llamada. Esta guia te explica como obtenerlo, usarlo y mantenerlo seguro.
Como obtener tu API key (2 min)
- 1
Entra al Panel
Ve a panel.cfdi4.com/login con tu usuario y contrasena.
- 2
Ve a RFCs → selecciona tu RFC
En el menu lateral izquierdo, click en RFCs y selecciona el RFC para el cual necesitas la key.
- 3
Click en "Generar API key"
Boton azul en la seccion API keys. Si ya tienes una, primero revala la anterior.
- 4
Copia la key — solo se muestra UNA vez
Si la pierdes, tienes que generar una nueva (la anterior se invalida al instante).
- 5
Guardala en lugar seguro
Variable de entorno (
.env, secrets manager). NO en codigo, ni en un doc de texto, ni en un chat.
Como usar tu API key
Incluyela en el header Authorization con prefijo Bearer:
curl -X POST https://api.cfdi4.com/api/v1/usuario/datos-fiscales \
-H "User-Agent: MiApp/1.0" \
-H "Authorization: Bearer sat_2955d29be541ed4d73f625576ef6c7652f654a21e0bd7cbe" \
-H "Content-Type: application/json" \
-d '{"rfc": "XAXX010101000"}'Basic (usuario:contrasena en base64) y Digest (con hash).Donde enviar la key (y donde NO)
El unico lugar seguro. Por convencion NO se loguea.
Los logs del server registran la URL completa → la key queda expuesta.
Puede ser cacheado por proxies → leak historico.
Lo mismo que query string: queda en logs y proxies.
Rotacion de keys (cada 90 dias)
Como buena practica, rota tu API key cada 90 dias. O inmediatamente si sospechas que fue comprometida.
- Ve al RFC correspondiente en el Panel
- Seccion API keys → click Revocar junto a la key actual
- Click Generar nueva API key
- Actualiza la variable de entorno en tu app y redeploya
Errores comunes
| Codigo | Significado | Solucion rapida |
|---|---|---|
1001 | API key invalida o no proporcionada | Verifica que el header diga Bearer sat_xxx (no Basic, no solo la key sin Bearer) |
1002 | API key revocada o expirada | Genera una nueva en el Panel |
1003 | Operacion no habilitada para este RFC | Habilita la operacion en Panel → Operaciones |
1004 | Saldo insuficiente | Recarga creditos en Panel → Saldos |
6001 | User-Agent no permitido | Anade -H \"User-Agent: MiApp/1.0\" |
Mejores practicas
✅ HACER
- Guardar la key en variable de entorno (
SAT_API_KEY) - Rotar cada 90 dias o si hay compromiso
- Keys diferentes para dev / staging / prod
- Monitorear logs del Panel para detectar uso anomal
- Usar HTTPS siempre (la key viaja en cada request)
❌ NO HACER
- Commitear la key a Git (queda en el historial)
- Compartirla entre personas
- Hardcodearla en el codigo (
const API_KEY = "sat_...") - Exponerla en logs o mensajes de error
- Reutilizarla en multiples apps
- Ponerla en un cliente (frontend, app movil)
Whitelisting de IP (opcional)
Ejemplos en 7 lenguajes
Ve a /docs/ejemplos/curl y los demas lenguajes para ver codigo listo para copiar.