API key para consultar multas: alcance y rotación
Una clave no dice quién llama: dice qué puede hacer quien la tenga. Declarar operaciones, datos, entorno y caducidad al emitirla es lo que después vuelve barata una rotación.
Por Marco Ferreiro ·
Una API key responde una pregunta angosta: quién dice ser el que llama. No dice qué puede hacer, sobre qué patentes, en qué entorno ni hasta cuándo. Esas cuatro respuestas forman el alcance, y se declaran al emitir la clave o no se declaran nunca.
El alcance y la rotación suelen discutirse por separado: uno es tema de seguridad, la otra tarea de operaciones. Son la misma decisión: el alcance determina cuánto cuesta reemplazar la clave y cuántas patentes quedan expuestas si se filtra.
Damos por elegido el mecanismo: el reemplazo sin corte se trata aparte. Lo que sigue es qué tiene que llevar la clave para que ese procedimiento salga barato.
Una clave es un portador, no una identidad
Quien presenta la clave actúa como el consumidor: el servidor no distingue el proceso que consulta patentes de una copia guardada en un repositorio, un ticket o un log. HTTP aporta menos vocabulario del que se le atribuye: RFC 9110 define un marco general de autenticación por desafío y respuesta, pero no especifica ningún esquema, y una API key en un encabezado propio ni siquiera figura en el documento.
La lectura corriente —401 para autenticación, 403 para autorización— no es lo que dice el texto. El 401 obliga a mandar un desafío WWW-Authenticate, y si la solicitud traía credenciales indica que la autorización fue rechazada para ellas. El 403 describe un servidor que entendió y se niega: considera insuficientes las credenciales que hubiera, pero admite que una solicitud puede estar prohibida por motivos ajenos a ellas. Y un servidor que quiere ocultar un recurso prohibido puede responder 404.
Ninguno de los tres es un resultado de negocio: un cliente que traduce 401, 403 o 404 a “sin infracciones” convierte un problema de alcance en un dato falso.
Cuatro dimensiones del alcance
Declaramos el alcance eje por eje, porque cada uno se rompe distinto:
- operaciones: qué recursos y métodos habilita; consultar no es crear un lote ni emitir otra clave;
- datos: sobre qué conjunto vale —una empresa, una flota, un grupo de vehículos—;
- entorno: producción y sandbox no comparten secretos ni deberían aceptar la credencial del otro;
- tiempo: desde cuándo y hasta cuándo es válida.
La operación que emite credenciales merece un eje propio: una clave capaz de crear otras tiene el alcance de cualquier clave que llegue a emitir.
El contrato escrito cubre sólo parte. OpenAPI permite declarar un esquema apiKey, decir si viaja en encabezado, consulta o cookie, y exigirlo operación por operación. Lo que no permite es describir su alcance: los scopes existen para oauth2 y openIdConnect, y para el resto la especificación sólo admite nombres de roles que no define ni intercambia. Dice qué operaciones piden una clave, no qué puede hacer una clave.
El alcance no reemplaza la autorización por objeto
Una clave restringida a una empresa filtra la puerta, no cada acta. La autorización rota a nivel de objeto encabeza la lista de riesgos de API de OWASP en su edición 2023: el identificador de un acta o un lote llega en la solicitud y el servidor lo devuelve sin comprobar que sea del titular.
La comprobación ocurre en cada acceso, con el mismo criterio en listados de infracciones, filtros, cursores y descargas. Las pruebas negativas están en aislamiento entre empresas.
Rotar sin ensanchar
Reemplazar una clave es una migración; ampliarle los permisos es un cambio de riesgo. La rotación no debería mezclarlos: la nueva se emite con un alcance igual o menor al de la anterior, y cualquier permiso adicional se pide y se registra aparte. Emitirla con permisos amplios por apuro deja una credencial que nadie sabe acotar después.
La guía de gestión de claves de NIST está escrita para material criptográfico, no para credenciales de portador, pero su noción de criptoperíodo —el lapso durante el cual una clave está autorizada a usarse— traslada bien: la duración se sopesa contra el riesgo y las consecuencias de la exposición, no contra un calendario. Con el mismo criterio viene el límite: si la clave se compromete, el período deja de valer. La caducidad ordena la rotación esperada; no gobierna un incidente.
La granularidad tampoco es estética: define el alcance. Una clave compartida por el barrido de patentes, el informe mensual y el alta de vehículos necesita la unión de los tres, así que compartirla la ensancha por construcción. Una por consumidor, entorno y propósito lo mantiene mínimo.
Qué verificar antes de emitir la próxima clave
Antes de entregar una credencial nueva, verificá que el registro diga a qué consumidor pertenece, qué operaciones habilita, sobre qué patentes, en qué entorno y hasta cuándo; y que el valor no aparezca en logs, errores ni URLs.
Después pedí una prueba negativa por cada eje: una operación fuera de alcance, un acta de otra empresa, la clave de sandbox contra producción y una clave vencida. Las cuatro deben ser rechazadas con el código correcto.
Si alguna de esas respuestas no está escrita, el alcance real de la clave es desconocido, y una rotación apurada es el peor momento para descubrirlo.
Metodología
- Alcance
- Diseño del alcance y del ciclo de vida de una API key en una integración servidor a servidor de consultas de infracciones. No cubre acceso delegado por una persona ni el procedimiento de reemplazo sin corte, tratado aparte.
- Unidad de análisis
- Cada clave emitida, con su consumidor, entorno, conjunto de operaciones, conjunto de datos y ventana de validez.
- Cobertura
- Marco de autenticación y semántica de códigos de estado de RFC 9110, declaración de esquemas de seguridad en OpenAPI 3.1.2, criptoperíodo y ciclo de vida de claves según NIST, y el riesgo de autorización por objeto descrito por OWASP en su edición 2023, consultados el 29 de agosto de 2026.
Limitaciones
- No existe un estándar único de emisión, formato ni transporte de una API key: cada proveedor documenta su implementación y esta nota no describe la de un servicio en particular.
- La guía de NIST citada trata material criptográfico: su noción de criptoperíodo se aplica acá por analogía a una credencial de portador, no como prescripción directa.
- El intervalo de caducidad y la granularidad de las claves dependen del riesgo, la arquitectura y las obligaciones de cada organización.
- La nota no publica secretos, endpoints internos ni configuración específica de multas.ar.
Fuentes
- RFC 9110 — HTTP Semantics — RFC Editor (consultada el )
- OpenAPI Specification version 3.1.2 — OpenAPI Initiative (consultada el )
- NIST SP 800-57 Part 1 Revision 5 — gestión de claves — National Institute of Standards and Technology (consultada el )
- OWASP API1:2023 Broken Object Level Authorization — OWASP Foundation (consultada el )
Preguntas frecuentes
¿Se puede ampliar el alcance de una API key ya emitida?
Técnicamente suele poder hacerse, pero conviene evitarlo: ampliar en silencio deja una credencial cuyos permisos reales no coinciden con el registro de emisión. Es preferible emitir otra clave con el alcance nuevo, migrar al consumidor y revocar la anterior.
¿Un 403 significa que la clave venció?
No. RFC 9110 describe el 403 como un servidor que entendió la solicitud y se niega a cumplirla: si venían credenciales, las considera insuficientes, aunque el mismo texto admite que una solicitud puede estar prohibida por motivos ajenos a la credencial. El 401 tampoco es sólo “falta la clave”: cuando la solicitud incluía credenciales, indica que la autorización fue rechazada para esas credenciales. Ninguno de los dos, ni un 404, debería traducirse a “sin infracciones”.
¿Cada cuánto hay que rotar una API key?
No hay un intervalo universal. La guía de NIST que citamos trata material criptográfico, y su criterio es que la duración se sopese contra el riesgo y las consecuencias de la exposición antes que contra un calendario. Declarar una caducidad al emitir, y poder reemplazar la clave sin cortar servicio, pesa más que elegir un número.
¿Alcanza con una clave por empresa?
Suele quedar corto. Una clave que sirve a varios procesos necesita la unión de los permisos de todos, así que el alcance se ensancha sin que nadie lo haya decidido. Una clave por consumidor, entorno y propósito mantiene cada alcance en su mínimo y permite atribuir consumo.
Notas relacionadas
Por qué actas e identificadores deben viajar como texto y no como números JSON
Un número de acta no es una cantidad. Serializarlo como número puede quitar ceros, alterar dígitos o producir resultados distintos entre lenguajes.
Auditoría de accesos: qué se registra
Un log operativo explica por qué falló una consulta. Un registro de accesos explica quién vio qué información y con qué habilitación. Son artefactos distintos y conviene no mezclarlos.
Claves JSON duplicadas: dos clientes leen distinta la misma multa
Dos campos `status` o `amount` pueden atravesar validación sintáctica y terminar con valores distintos según el parser. La frontera segura los rechaza antes del binding.