API key u OAuth para consultar multas: qué riesgo resuelve cada modelo
Los dos mecanismos autentican al sistema de la flota que consulta infracciones, pero difieren en emisión, alcance, expiración, rotación y operación. La elección parte del riesgo.
Por Marco Ferreiro ·
Dos integraciones llaman a la misma API de infracciones. Una envía una clave estable; la otra obtiene un token con client credentials. Mirar sólo la cantidad de pasos lleva a conclusiones pobres. La pregunta es qué identidad, alcance y ciclo de vida necesita controlar el servicio.
Ambos modelos dependen de secretos protegidos, TLS, inventario y capacidad de revocar. OAuth no vuelve seguro a un cliente que dejó en un repositorio la clave con la que consulta patentes.
Qué es una API key en esta comparación
“API key” describe una credencial emitida por el proveedor y presentada en cada solicitud. OpenAPI permite documentar su ubicación en encabezado, consulta o cookie, aunque una implementación responsable evita URLs y logs donde pueda filtrarse.
No existe un único protocolo universal para emitirla, darle permisos o renovarla. El proveedor decide si representa a la flota entera, a uno de sus sistemas, al ambiente o al producto contratado.
Qué agrega client credentials
RFC 6749 define el grant para clientes confidenciales que actúan en nombre propio o bajo una autorización previamente acordada. El cliente se autentica ante un endpoint y recibe un access token con duración y, normalmente, alcance.
La API valida el token y no necesita recibir el secreto original en cada consulta de multas. A cambio aparecen nuevos componentes: servidor de autorización, emisión, caché, expiración y manejo de errores del token.
Riesgo 1: exposición del secreto
Una clave larga y un client secret son secretos. Se guardan en un gestor, no en código, repositorio, navegador ni en la app que usan los choferes. El grant client credentials sólo corresponde a clientes capaces de mantener confidencialidad.
Los tokens también son credenciales. Aunque duren poco, no se imprimen en logs ni se incluyen en URLs. TLS protege el tránsito; controles de proceso protegen almacenamiento y despliegue.
Riesgo 2: alcance excesivo
Una API key puede estar ligada a permisos fijos y mínimos. Para una integración que sólo consulta infracciones por dominio, esa simplicidad puede ser suficiente si el proveedor permite separar ambientes y clientes.
OAuth facilita emitir tokens con scopes específicos y distintos para cada servicio. Pero un scope llamado admin para todos no aporta granularidad real. Los permisos deben corresponder a operaciones verificables: consultar por patente, consultar por documento, descargar el informe de la flota.
Riesgo 3: credenciales largas
Con una API key estable, la rotación reemplaza la credencial distribuida. Para no cortar el barrido nocturno de patentes se necesita solapamiento: emitir nueva, desplegar, observar uso y revocar la anterior.
Client credentials permite mantener el secreto del cliente mientras los access tokens vencen rápido. Eso reduce la ventana de un token robado, pero no elimina la necesidad de rotar el secreto que los obtiene.
Riesgo 4: revocación y aislamiento
Cada cliente debe tener identidad propia. Compartir una clave entre cinco flotas impide revocar una sin afectar a las demás y borra el rastro de qué empresa consultó qué dominio.
OAuth puede centralizar baja de cliente y políticas. Una API key también puede aislar correctamente si el sistema emite una por cliente, ambiente y propósito. La diferencia está en la implementación, no en el nombre.
Riesgo 5: dependencia operativa
El flujo OAuth añade una llamada al token endpoint. El cliente debe cachear el token hasta cerca de su vencimiento, evitar pedir uno por patente consultada y manejar la indisponibilidad sin usar tokens expirados.
Una API key reduce esa dependencia, pero traslada más peso a rotación y monitoreo de una credencial duradera. La matriz debe incluir el costo de operar cada control.
Dos clientes ficticios
El Cliente A es un cron que consulta las mismas cuarenta patentes cada mañana, con una clave por ambiente en un gestor y rotación automatizada. Una API key resuelve su identidad con menos piezas.
El Cliente B es una rentadora con tres sistemas: el que consulta actas, el que arma el informe de compliance y el que avisa al conductor. Client credentials con scopes acotados separa mejor esas capacidades. Ninguno expone secretos al frontend.
Pruebas mínimas antes de elegir
En laboratorio verificamos:
- una credencial revocada deja de funcionar;
- los permisos fuera de alcance reciben rechazo;
- producción y prueba no comparten secretos;
- la rotación admite solapamiento breve;
- logs y métricas no contienen credenciales;
- un token expirado no se renueva en bucle;
- cada consulta de una patente conserva la identidad del cliente.
El resultado se documenta con tiempos y versiones, sin publicar valores secretos.
Una decisión revisable
Elegir API key hoy no impide migrar a OAuth si mañana hay que separar quién consulta por patente y quién por documento. Elegir OAuth tampoco justifica agregar acceso delegado cuando el caso es servidor a servidor.
La arquitectura registra la amenaza que motivó el mecanismo, quién es dueño de la credencial y cómo se rota. Así la discusión deja de ser “cuál suena más seguro” y pasa a controles que se pueden probar.
Metodología
- Alcance
- Matriz de amenazas para dos integraciones ficticias servidor a servidor, comparando API key y OAuth 2.0 client credentials.
- Unidad de análisis
- Credencial o token evaluado por identidad, alcance, duración, almacenamiento, rotación, revocación y trazabilidad.
- Cobertura
- Escenarios de un cliente con permiso fijo y una plataforma multi-servicio con scopes y tokens breves.
Limitaciones
- API key no define un estándar único de emisión o transporte; cada proveedor debe documentar su implementación.
- La comparación no cubre acceso delegado por una persona ni reemplaza un análisis de amenazas del sistema real.
Fuentes
- The OAuth 2.0 Authorization Framework — RFC Editor (consultada el )
- Best Current Practice for OAuth 2.0 Security — RFC Editor (consultada el )
- OpenAPI Specification version 3.1.2 — OpenAPI Initiative (consultada el )
- Digital Identity Guidelines revision 4 — National Institute of Standards and Technology (consultada el )
Preguntas frecuentes
¿OAuth siempre es más seguro que una API key?
No de forma automática. Una implementación débil puede agregar complejidad sin reducir riesgo. Hay que comparar amenazas, operación y controles reales.
¿Client credentials sirve para una aplicación en el navegador?
No para guardar un secreto. RFC 6749 limita ese grant a clientes confidenciales capaces de proteger sus credenciales.
¿Alcanza con rotar una credencial una vez por año?
No hay un período universal. La política debe considerar exposición, impacto, automatización, revocación y capacidad de solapar claves sin cortar servicio.
Notas relacionadas
Webhooks de nuevas multas: idempotencia, reintentos y trazabilidad
Un webhook confiable puede llegar más de una vez, demorarse o fallar después de ser procesado. El diseño debe deduplicar eventos, reintentar con límites y conservar evidencia de punta a punta.
Timeout no significa “sin multas”: cómo informar resultados parciales en una integración
Cuando una fuente no responde, el resultado es parcial o indeterminado, nunca cero. Un contrato explícito permite reintentar, alertar y decidir sin producir falsos negativos.
Corregir un acta no termina en la base: cachés y exportaciones
Corregir una fila no actualiza por sí solo respuestas cacheadas, archivos exportados ni consumidores. La rectificación necesita versión, evento y cierre verificable.