# Seguridad de las actualizaciones de versión de API para agentes de IA

Una actualización de versión de una API puede ampliar la autoridad de un agente sin cambiar una sola línea de sus instrucciones. Los cambios peligrosos suelen parecer inofensivos en las notas de la versión: cambia un valor predeterminado, aparece un endpoint, un token antiguo obtiene una ruta de compatibilidad o una respuesta incluye registros que la versión anterior omitía.

Las integraciones operadas por personas a veces sobreviven a esa ambigüedad porque alguien detecta una pantalla desconocida o se detiene ante una solicitud extraña. Un agente de programación autónomo no hace esa pausa. Si puede crear solicitudes a partir de la documentación, inspeccionar errores y probar alternativas, cualquier operación que pase a estar disponible se convierte en parte de su autoridad práctica.

## Las etiquetas de versión no miden la autoridad

Un número de versión describe la promesa de compatibilidad del proveedor de una API, no el cambio de permisos que experimenta un agente. Trata cada actualización de API como una revisión de autoridad hasta comparar lo que podía hacer la credencial antes y después.

La especificación de Versionado Semántico indica que una versión MAJOR cambia cuando se produce una modificación incompatible de la API pública. Esa afirmación ayuda a quienes mantienen bibliotecas a decidir si los clientes podrían dejar de funcionar. No afirma que una versión MINOR no pueda añadir un endpoint administrativo, ampliar un filtro predeterminado o aceptar un token de acceso destinado a otra audiencia. Las tres cosas pueden conservar la compatibilidad y, al mismo tiempo, aumentar lo que un agente puede hacer.

Esta distinción importa porque los equipos suelen formular la pregunta equivocada: «¿Nuestro código seguirá funcionando?». La pregunta que protege la cuenta es: «¿Qué operaciones puede realizar correctamente este agente existente, contra qué recursos y con qué credencial?».

Una actualización de API tiene cuatro superficies independientes:

- Compatibilidad de solicitudes: métodos, rutas, parámetros y formatos de carga útil.
- Alcance de los recursos: las cuentas, proyectos, repositorios, archivos o registros a los que puede dirigirse una solicitud.
- Alcance de las acciones: las operaciones de lectura, escritura, eliminación, despliegue, facturación e identidad que pueden completarse.
- Aceptación de credenciales: qué tokens, claves, firmas, audiencias y ámbitos acepta el proveedor.

Una prueba correcta de compatibilidad de solicitudes no dice casi nada sobre las otras tres superficies. Por eso un cambio puede superar una batería de regresión convencional y aun así dar a un agente una nueva ruta hacia los datos de producción.

No supongas que una versión de API fechada resuelve este problema. Un proveedor puede mantener estable una superficie fechada mientras cambia un servicio de autenticación compartido, añade campos opcionales que el agente descubre o modifica valores predeterminados fuera de la ruta del endpoint. Fijar una versión resulta útil. Considerar esa fijación como un límite de permisos es imprudente.

## Construye el mapa de autoridad antes y después

No puedes revisar una actualización basándote solo en un registro de cambios. Construye un mapa compacto de las solicitudes que el agente puede emitir y compara después el comportamiento observado en las versiones antigua y nueva.

Empieza por el tráfico real, no por el diseño previsto. Los agentes suelen usar más endpoints de los que sugiere la tarea original: llamadas de descubrimiento, reintentos después de errores de validación, paginación, endpoints de búsqueda que convierten nombres en identificadores y APIs prácticas sugeridas por los mensajes de error. Incluye esas llamadas porque pueden revelar identificadores de recursos o conceder una ruta más amplia que la acción planificada.

Para cada familia de solicitudes, registra estos datos:

| Campo | Qué registrar |
|---|---|
| Operación | Método HTTP y ruta normalizada, como `POST /v2/projects/{id}/deployments` |
| Límite de recursos | El tenant, proyecto, repositorio, entorno o clase de registro que puede tocar |
| Credencial | Clase de token o etiqueta de la clave de API, nunca el secreto |
| Condición de autorización | Ámbito, rol, audiencia, autorización del usuario o regla del servidor que la permite |
| Comportamiento predeterminado | Qué ocurre cuando faltan filtros opcionales, límites de página y campos de destino |
| Expectativa de denegación | El estado y el error esperados para recursos y acciones prohibidos |

El mapa debe nombrar el límite de recursos con palabras sencillas. «Puede llamar a la API de despliegues» es demasiado vago. «Puede crear despliegues solo en el proyecto de pruebas» se puede comprobar. Si el proveedor no ofrece suficiente detalle para expresar ese límite, utiliza una identidad de prueba separada para el agente hasta poder establecerlo.

Después, crea una comparación en dos columnas. Ejecuta el mismo conjunto de solicitudes contra las versiones antigua y nueva con una cuenta aislada que contenga recursos deliberadamente separados: al menos un proyecto permitido, uno prohibido, un registro inactivo y una cuenta de otro tenant si el servicio admite multiinquilinato. Los datos de prueba deben tener nombres reconocibles para que puedas detectar resultados que se hayan filtrado accidentalmente.

No compares solo los códigos de estado. Una respuesta `200` puede ocultar la diferencia importante: el doble de registros, un nuevo enlace `next_page` que cruza un límite, un campo de credencial adicional o un identificador de objeto que permita al agente llamar más tarde a un endpoint privilegiado. Compara la estructura de las respuestas y los identificadores, y revisa los campos nuevos para detectar autoridad posterior.

## Los valores predeterminados modificados crean rutas de acceso que nadie solicitó

Un parámetro omitido sigue siendo una decisión de autorización cuando el servidor decide qué significa. Los valores predeterminados modificados merecen la misma revisión que un endpoint de escritura nuevo.

El problema habitual empieza con una solicitud de listado que parece inofensiva. La versión uno exige `project_id` y devuelve solo registros activos. La versión dos permite la solicitud sin `project_id`, y el proveedor define la omisión como «todos los proyectos visibles para este token». El código fuente del agente no cambió si ya omitía ese campo opcional. Lo que cambió fueron los datos a los que puede llegar.

Otros valores predeterminados producen el mismo resultado:

- Un endpoint de listado empieza a incluir objetos archivados, eliminados o heredados.
- La paginación pasa de un conjunto pequeño y fijo de resultados a recorrer cursores con una URL `next`.
- Un endpoint de creación elige el espacio de trabajo predeterminado de quien llama en lugar de rechazar la falta de un ID de espacio de trabajo.
- Un endpoint de actualización acepta los campos omitidos como «conservar el valor actual» en lugar de exigir una versión de concurrencia explícita.
- Un endpoint de búsqueda empieza a indexar contenido de servicios conectados.

Los proveedores llaman mejoras a estos cambios porque reducen el trabajo del cliente. Para un agente, reducir el trabajo del cliente suele significar que hay menos fricción antes de que una acción alcance un objetivo más amplio.

Revisa los valores predeterminados con solicitudes deliberadamente incompletas. Para cada parámetro opcional, envía una solicitud sin el parámetro, otra con un valor vacío si la API lo permite y otra con un valor seguro explícito. Compara el conjunto de destinos y el error del servidor. Un agente que genera solicitudes probará de forma natural los campos omitidos, especialmente después de ver un ejemplo de documentación que los deja fuera.

No confíes en un texto del prompt como «usa solo el proyecto A» para contener esto. Las instrucciones del prompt influyen en la elección de la solicitud, pero la API decide si una solicitud puede tocar el proyecto B. Coloca el límite del proyecto en la credencial, en el diseño del endpoint o en una pasarela que valide la solicitud antes de que salga de la máquina.

## Los endpoints nuevos amplían las credenciales generales

Un endpoint nuevo modifica la autoridad de una credencial existente si esa credencial puede autenticarse en él. El agente no tiene que haber llamado antes al endpoint para que exista el riesgo.

Los equipos suelen excluir los endpoints nuevos de la revisión porque los llaman «funcionalidad nueva». Esa lógica solo funciona cuando una persona obtiene un nuevo control en la interfaz y un administrador concede el acceso por separado. Falla cuando un token bearer con un ámbito amplio funciona automáticamente contra la nueva ruta.

Supón que un agente tiene un token descrito como `projects:write`. En la versión uno, ese token puede crear y editar metadatos de proyectos. La versión dos añade `POST /projects/{id}/exports`, que crea una exportación descargable y utiliza el mismo ámbito. La cadena del ámbito no cambió, pero sí cambió el efecto de poseerla. El agente puede descubrir ese endpoint mediante un esquema de API, un cliente generado, una sugerencia de error o la documentación normal.

Clasifica los endpoints nuevos por efecto y no por verbo HTTP. Los endpoints `GET` pueden exponer código fuente, valores secretos, historial de auditoría, datos personales o URLs de descarga firmadas. Los endpoints `POST` pueden crear costes irreversibles o activar flujos de trabajo externos. Una ruta `DELETE` puede ser menos peligrosa que una ruta `GET` que revele una credencial utilizable en otro lugar.

Revisa cada ruta con estas cuatro preguntas:

1. ¿Una credencial existente del agente se autentica correctamente?
2. ¿Qué ámbitos, roles o clases de claves de API existentes la permiten?
3. ¿Su salida puede proporcionar identificadores, URLs o tokens para otra operación?
4. ¿El agente puede llegar a ella mediante la biblioteca cliente, el documento de descubrimiento o la documentación proporcionada?

La última pregunta detecta una recomendación habitual y deficiente: «No informaremos al agente sobre el endpoint nuevo». La restricción parece práctica porque los agentes suelen seguir su contexto de trabajo. No es un control. Los agentes pueden inspeccionar esquemas, deducir rutas convencionales o recibir instrucciones en una tarea posterior. El servidor debe rechazar una operación no aprobada incluso cuando el cliente conoce su URL exacta.

Si el proveedor no puede separar la nueva ruta de un ámbito general antiguo, crea una identidad de integración más limitada antes de actualizar. Un token destinado a un flujo de trabajo concreto no debería heredar todos los significados futuros que un proveedor asigne a un nombre de ámbito amigable.

## Los cambios de autenticación son cambios de permisos

El comportamiento de autenticación debe formar parte de la revisión de la actualización, porque aceptar una credencial de forma diferente cambia quién puede actuar. Los equipos suelen probar el inicio de sesión correcto y omitir los casos de denegación donde una actualización causa el daño.

OAuth 2.0 define los tokens de acceso como credenciales que representan una autorización, mientras que RFC 9700, OAuth 2.0 Security Best Current Practice, exige la coincidencia exacta de las URI de redirección y describe protecciones contra la reutilización de tokens y el uso de tokens vinculados al emisor. La lección práctica va más allá de OAuth: el formato de un token por sí solo no establece su destinatario, emisor o ámbito previsto. El servidor de recursos debe aplicar esas propiedades en cada solicitud aceptada.

Los cambios de versión suelen afectar indirectamente a esa aplicación. Un proveedor puede introducir un nuevo emisor, aceptar tokens destinados a una API hermana, añadir una ruta de intercambio de tokens, modificar la rotación de tokens de renovación o permitir una clave de API antigua junto con un token con ámbitos. La presión por mantener la compatibilidad hace atractivos estos cambios. También crea rutas alternativas que los equipos olvidan probar.

Prueba tanto la aceptación como el rechazo. Para cada clase de credencial, prueba la operación permitida, la misma operación contra un recurso prohibido, una credencial caducada, un token con una audiencia incorrecta, un token sin el ámbito necesario y una credencial revocada. Si el proveedor admite tokens de renovación, comprueba si la renovación conserva la autorización anterior, cambia su audiencia o adquiere silenciosamente los ámbitos concedidos durante un consentimiento posterior.

Un registro útil tiene este aspecto:

```text
credential: build-agent-sandbox
request: POST /v3/projects/prod-42/deployments
expected: 403 forbidden
old version: 403 {"error":"insufficient_scope"}
new version: 201 {"id":"dep_...","environment":"production"}
review result: block upgrade and revoke credential
```

El cuerpo de la respuesta importa. Un `403` que se convierte en un `404` puede ser un cambio intencionado para ocultar información. Un `403` que se convierte en `201` es un aumento de autoridad, aunque las notas de la versión lo llamen una mejora de compatibilidad.

Examina también el comportamiento de los encabezados. Los encabezados personalizados pueden seleccionar una versión de API, una organización o un usuario suplantado. Si la nueva API trata un encabezado ausente como la organización predeterminada, un reintento del agente después de un error de formato en el encabezado puede acabar en el lugar equivocado. Registra los encabezados exactos en las pruebas, con los secretos ocultos, y prueba la omisión por separado.

## El comportamiento del agente convierte pequeñas diferencias en flujos completos

Un agente puede encadenar llamadas comunes por separado y producir un resultado que el diseñador de la API nunca revisó como un único permiso. La revisión de la versión debe seguir esas cadenas.

Un nuevo campo de listado puede revelar el ID de un repositorio. Ese ID puede alimentar un endpoint de descarga. La respuesta de la descarga puede incluir una URL firmada. La URL puede exponer un artefacto cuya configuración contiene el endpoint de otro servicio. Cada llamada puede parecer permitida por separado. La secuencia completa puede superar la tarea que recibió el agente.

Por eso la revisión de autorización endpoint por endpoint es necesaria, pero incompleta. Añade pruebas de flujo para las acciones que quieres que el agente realice y para las acciones cercanas que quieres excluir. Sigue el flujo de identificadores entre llamadas: IDs, cursores de paginación, ubicaciones, URLs prefirmadas, IDs de trabajos y mensajes de error que revelen nombres válidos de recursos.

Haz que las pruebas sean concretas. Si el agente debe actualizar una incidencia en un repositorio, prueba que pueda:

- Leer la incidencia prevista y actualizar sus campos permitidos.
- Fallar cuando intente usar el ID de una incidencia de otro repositorio.
- Fallar cuando intente modificar la configuración o los webhooks del repositorio.
- Fallar cuando siga un enlace hacia una exportación, una lista de miembros o una ruta de gestión de tokens.

La ruta de fallo importa tanto como la de éxito. Un agente trata los errores como información. Una denegación detallada que nombre otro endpoint puede facilitar el descubrimiento de una ruta no prevista. Puedes aceptar ese intercambio con desarrolladores humanos, pero debes saber que existe antes de exponer la integración a un proceso autónomo.

Limita los reintentos durante las pruebas de actualización. Una política de reintentos que era inofensiva cuando una solicitud era idempotente puede crear acciones duplicadas si la nueva versión cambia el comportamiento de idempotencia o devuelve un tiempo de espera después de completar el trabajo. Comprueba si la API utiliza una clave de idempotencia, cuánto tiempo conserva esa clave y si la actualización cambia el nombre del encabezado o las reglas de cálculo del hash de la solicitud.

## Una diferencia de capacidades detecta cambios que las pruebas normales no ven

Una diferencia de capacidades es una prueba repetible que pregunta qué solicitudes puede completar una credencial, no si tu aplicación sigue recibiendo los datos esperados. Mantenla lo bastante pequeña para ejecutarla con cada versión candidata.

Crea un conjunto de solicitudes en un repositorio que no contenga secretos de producción. Usa variables de entorno para los tokens de prueba y apunta solo a una cuenta desechable. El siguiente patrón de shell registra las partes que revelan cambios de autoridad sin mostrar las credenciales:

```sh
curl -sS -D headers.txt -o body.json \
  -H "Authorization: Bearer $TEST_TOKEN" \
  -H "X-API-Version: 2025-01-01" \
  "https://api.example.test/v1/projects?limit=2"

printf 'status: ' && head -n 1 headers.txt
printf 'headers:\n' && grep -Ei '^(link|location|x-request-id|www-authenticate):' headers.txt
printf 'identifiers:\n' && jq -r '.. | objects | (.id? // empty)' body.json | sort -u
```

Ejecuta el conjunto una vez por cada versión y compara el estado, los encabezados seleccionados y los identificadores normalizados. No hagas una diferencia ciega de todo el JSON. Las marcas de tiempo, los IDs de solicitud y el orden generan ruido y hacen que los revisores aprendan a ignorar las diferencias. Normaliza primero esos campos, pero conserva los enlaces de paginación, los IDs de recursos, los nombres de roles y cualquier campo que pueda dirigir una solicitud posterior.

El conjunto debe incluir solicitudes correctas, denegaciones esperadas, parámetros opcionales omitidos y la primera página seguida de una solicitud de paginación. Añade una solicitud por cada ruta documentada recientemente que parezca relacionada con un ámbito existente del agente. El objetivo no es enumerar todo el proveedor. Es cubrir cada operación que el agente pueda descubrir o combinar de forma realista.

Un archivo de resultados sencillo facilita la revisión de las decisiones:

```json
{
  "case": "forbidden-production-deploy",
  "credential": "build-agent-sandbox",
  "request": "POST /v3/projects/prod-42/deployments",
  "expected_status": 403,
  "observed_status": 403,
  "observed_resource_ids": [],
  "version": "2025-01-01"
}
```

Exige una decisión explícita del revisor para cada diferencia. «Es lo esperado porque el proveedor lo cambió» no es una decisión. El revisor debe indicar si el comportamiento nuevo sigue dentro de la autoridad aprobada del agente y, en caso afirmativo, dónde se aplica esa autoridad.

## Los registros demuestran lo ocurrido, no lo que debería haber ocurrido

Los registros de solicitudes ayudan a investigar una actualización, pero no sustituyen una revisión de autoridad previa al despliegue. Responden a preguntas diferentes.

Antes de la actualización, la diferencia de capacidades te indica si el proveedor aceptará una solicitud no deseada. Después de la actualización, los registros te indican si el agente realmente la intentó, qué proceso hizo el intento y si necesitas contener la cuenta. Necesitas ambas cosas porque una solicitud denegada hoy puede ser aceptada mañana después de un cambio de comportamiento del proveedor.

Registra el selector de versión, la operación normalizada, el límite de destino, la etiqueta de la credencial, la decisión, el estado y el ID de correlación. No registres tokens bearer, encabezados de autorización sin procesar, cuerpos completos de solicitudes ni campos de respuesta que contengan secretos. Un registro de seguridad que almacena la credencial que debía proteger solo desplaza la brecha.

Separa el registro de sesión del registro de acción. La sesión indica qué proceso de agente recibió permiso para operar durante una ejecución. El registro de acción indica qué solicitud individual hizo. Esta distinción se vuelve problemática cuando un agente de larga duración comienza con una versión revisada y después recibe un cambio de entorno o una biblioteca cliente regenerada.

Sallyport mantiene un diario de sesiones y un diario de actividad proyectados desde un único registro de auditoría cifrado y encadenado mediante hashes, de modo que un operador pueda inspeccionar tanto la ejecución del agente como cada acción HTTP o SSH. Su comprobación sin conexión `sp audit verify` puede verificar la cadena sin acceso a la bóveda, algo útil cuando una revisión de actualización se convierte en una revisión de incidente.

No confundas las evidencias de manipulación con la prevención. Un registro de auditoría intacto puede demostrar que se utilizó un endpoint nuevo. No puede retirar datos exportados de un servicio remoto. Mantén las acciones sensibles detrás de credenciales y aprobaciones que fallen antes de que la solicitud salga de la máquina.

## La aprobación debe vincularse a un proceso, no a una tarea vaga

Una aprobación humana solo puede detener una actualización no revisada si indica a la persona qué ejecutable solicita la autoridad. «El agente quiere acceso a la API» aporta muy poca información cuando varios procesos locales pueden hablar el mismo protocolo.

Vincula la autorización de sesión a la autoridad de firma de código del proceso solicitante cuando el sistema operativo lo permita. Esto detecta un fallo habitual de sustitución: un agente de confianza inicia una sesión y después un auxiliar no confiable o un binario copiado intenta reutilizar la misma ruta de credenciales. La identidad del proceso no demuestra que todas las solicitudes futuras sean sensatas, pero proporciona al operador un objeto concreto que aprobar o revocar.

Reserva la aprobación por llamada para credenciales cuyo efecto sea difícil de limitar, como el despliegue en producción, la administración de cuentas o la exportación de datos. Exigir que una persona apruebe cada lectura inofensiva solo la acostumbra a hacer clic en las tarjetas sin leerlas. La fatiga por aprobación es un error de diseño, no un defecto de la persona usuaria.

Sallyport utiliza una escala fija de decisión con tres controles: la bóveda bloqueada rechaza todas las acciones, un proceso de agente nuevo solicita autorización de sesión de forma predeterminada y una configuración por clave puede exigir una aprobación separada para cada uso. Este modelo limitado no expresa todas las reglas organizativas, pero evita ocultar los cambios de autoridad dentro de un conjunto de sintaxis de políticas.

Cuando una actualización de API cambia el alcance efectivo de una credencial, revoca la sesión actual y exige una aprobación nueva después de la revisión. No permitas que una sesión aprobada para los endpoints de ayer continúe silenciosamente en los endpoints más amplios de mañana.

## Convierte la revisión de autoridad en un requisito de lanzamiento

Una actualización de versión de API debe fallar el control de lanzamiento cuando una credencial actual obtiene una solicitud correcta inexplicada, una solicitud denegada pasa a estar permitida o una respuesta expone un identificador nuevo que permite un flujo prohibido.

Incluye la revisión en el mismo registro de cambios que las actualizaciones de dependencias y los cambios en clientes generados. Registra los selectores de API antiguo y nuevo, las notas de la versión del proveedor, el resultado de la diferencia de capacidades, las clases de credenciales probadas y la persona que aceptó cada diferencia intencionada. Es un trabajo rutinario, por eso se omite hasta que aparece la primera entrada extraña en la auditoría.

No esperes a una versión MAJOR de la API. Activa la revisión cuando el proveedor cambie una versión de API, un servicio de autenticación, la configuración de una aplicación OAuth, un SDK generado, un esquema de descubrimiento, un encabezado predeterminado o la definición de un ámbito. Un cambio fuera de la URL también puede modificar la decisión del servidor remoto.

Empieza por la credencial que causaría más daño si obtuviera una ruta adicional. Asígnale una cuenta de prueba aislada, escribe cinco solicitudes permitidas y denegadas y ejecútalas contra la versión propuesta. Si no puedes explicar por qué cada éxito pertenece al trabajo del agente, la integración no está preparada para el uso autónomo.