Acceso de agentes de IA a API: ¿tokens directos o acciones mediadas?

Un agente de programación con IA no debería recibir un token general de SaaS solo porque necesita llamar a una API. Entregarle el token convierte el proceso del agente en propietario de una credencial, con todas las vías habituales por las que una credencial puede escapar: un comando detallado, un proceso hijo, un paquete de diagnóstico subido, el resultado de una herramienta o una instrucción que le pida al agente imprimir su configuración.

Eso no significa que cada llamada API necesite un ritual. Significa que debes separar la autoridad para realizar una acción de la posesión de la credencial que la autoriza. Dale al agente una forma limitada de solicitar trabajo útil, conserva la credencial en el componente que ejecuta la acción y deja que una persona decida cuando las consecuencias lo justifiquen.

La diferencia se difumina porque un comando curl correcto parece inofensivo. El problema empieza cuando el agente puede crear un despliegue en producción, cerrar un ticket de cliente, modificar una incidencia o ejecutar un comando remoto. En ese momento, un token deja de ser un detalle de configuración. Es autoridad operativa sin criterio propio.

Entregar un token directamente convierte al agente en un límite de credenciales

Cuando colocas SAAS_TOKEN en el entorno de un agente, en un archivo de configuración, en una definición de herramienta o en un almacén de secretos accesible desde el prompt, el agente puede realizar solicitudes autenticadas sin que otro componente decida si cada solicitud corresponde a la tarea. El token puede tener permisos razonables, pero sigue estando disponible para cualquier comportamiento de ese proceso y, a menudo, para los programas que este inicia.

Los desarrolladores suelen decir que el agente no puede «ver» una variable de entorno. Esa afirmación no resiste el uso normal de herramientas. Un agente puede pedirle a un shell que inspeccione su entorno, ejecutar un script que lo herede, ejecutar una herramienta de pruebas con registros de depuración o escribir una instantánea de configuración en un repositorio. La vía exacta de exposición depende del agente y de sus herramientas, por lo que la suposición segura es sencilla: si el proceso puede usar directamente un token bearer, normalmente también puede hacer que aparezca en algún lugar que no habías previsto.

Un token bearer tiene otra propiedad incómoda. El servicio SaaS no puede distinguir al agente previsto de cualquiera que haya copiado la cadena. RFC 6750, la especificación OAuth 2.0 Bearer Token Usage, indica que los tokens bearer deben protegerse contra su divulgación en almacenamiento y tránsito porque basta con poseerlos para usarlos. No es una formulación académica. Cuando un agente imprime uno en un registro de compilación, el servicio ve un cliente válido, no un error.

El acceso directo también confunde la responsabilidad. Los registros de auditoría del servicio pueden identificar una cuenta de bot, pero rara vez indican qué ejecución del agente formó la solicitud, qué instrucciones recibió, qué usuario la inició o si una persona aprobó el efecto resultante. Obtienes un evento de API a posteriori, pero no el rastro de decisión que lo explica.

Un token directo puede ser tolerable en un sandbox local desechable cuando se cumplen todas estas condiciones:

• El token caduca pronto y solo tiene el alcance mínimo fuera de producción.
• El destino no contiene datos de clientes, empleados ni producción.
• El agente se ejecuta en un entorno aislado que puedes eliminar.
• Una persona puede revocar la credencial sin interrumpir el trabajo compartido.

Los equipos convierten esta excepción en una práctica habitual porque copiar un token es rápido. La rapidez es real, pero también lo es la limpieza posterior cuando el token termina en un artefacto o el agente sigue una instrucción maliciosa incluida en la descripción de una incidencia.

Los permisos limitan lo que se puede hacer, pero no controlan la intención

Los alcances de OAuth, los roles de API y los permisos de repositorio responden a «¿qué puede hacer esta identidad?». No responden a «¿debería ocurrir esta solicitud ahora?». Son controles distintos, y tratarlos como si fueran intercambiables deja un agujero importante.

Considera un token de un gestor de incidencias con permiso para editar incidencias en un proyecto. Ese alcance puede ser correcto para un agente encargado de clasificar errores. Una inyección de prompts en una incidencia importada aún puede decirle al agente que cierre todas las incidencias abiertas, cambie las prioridades o publique comentarios engañosos. Cada solicitud encaja en el alcance. Todas siguen siendo incorrectas.

Lo mismo ocurre con una plataforma de despliegue. Un token limitado a una aplicación no sabe si el agente debe desplegar el commit actual, revertir una versión, cambiar una variable de entorno o eliminar un entorno de vista previa. El servicio ve llamadas API autorizadas. Solo tu flujo de trabajo puede decidir si esas llamadas corresponden a una tarea y a un destino aceptable.

Las buenas prácticas actuales de seguridad de OAuth 2.0 del IETF recomiendan tokens de corta duración, tokens vinculados al emisor cuando sea posible y privilegios más limitados para reducir el daño de los tokens bearer. Son buenas prácticas. Reducen la vida útil y el alcance de una credencial copiada. No añaden aprobación para una acción destructiva aunque tenga el alcance correcto, ni explican la intención del agente.

No respondas creando un catálogo enorme de reglas que intente predecir cada endpoint y argumento. Los equipos construyen esos catálogos y después pasan meses manteniendo excepciones para nuevas API de servicios y procedimientos de lanzamiento poco habituales. Una interfaz de acciones limitada, junto con una aprobación humana en el momento adecuado, suele soportar mejor el trabajo real que un lenguaje de políticas que nadie puede leer con seguridad.

Los gestores de incidencias necesitan rutas de escritura que conserven el criterio humano

Los gestores de incidencias parecen de bajo riesgo hasta que un agente empieza a hacer cambios a gran escala. Cerrar una incidencia puede ocultar el informe de un cliente. Cambiar etiquetas puede romper los informes de clasificación. Publicar un comentario puede exponer razonamientos internos a colaboradores externos. Añadir un usuario a un ticket puede ampliar el acceso a contexto sensible.

Separa el trabajo del agente en observación y mutación. Permítele recuperar incidencias, buscar etiquetas, revisar pull requests vinculadas y preparar una propuesta de actualización. Envía la mutación final mediante una acción que indique el proyecto, la incidencia, los campos modificados y el texto del comentario. El revisor debe ver el contenido real antes de que el servicio lo reciba.

Un contrato de solicitud puede hacer concreta esa frontera. El agente debe enviar una intención estructurada, no construir una línea de comandos que contenga credenciales.

{
  "service": "issue-tracker",
  "action": "update_issue",
  "issue": "APP-184",
  "changes": {
    "labels_add": ["needs-reproduction"],
    "comment": "I reproduced this on the current release and attached the failing test."
  }
}

El ejecutor debe inyectar su propia credencial y devolver un resultado limitado:

{
  "ok": true,
  "issue": "APP-184",
  "updated_fields": ["labels", "comment"],
  "request_id": "service-request-id"
}

No devuelvas el encabezado Authorization sin procesar, una traza HTTP completa ni un objeto de depuración que incluya secretos. Parece obvio hasta que alguien activa diagnósticos HTTP detallados durante una integración difícil. Mantén los diagnósticos detrás de una ruta de resolución de problemas operada por una persona y prueba la ocultación de datos, no la des por supuesta.

Un agente aún puede juzgar mal después de que una persona apruebe una sesión. Por eso los cambios destructivos en incidencias merecen una opción de aprobación separada. La autorización de sesión responde si el programa que se está ejecutando puede usar la integración. La aprobación por llamada responde si debe realizarse esa mutación concreta. La diferencia importa sobre todo cuando el agente puede leer texto no confiable de tickets, documentos o comentarios de pull requests.

Las API de despliegue tienen consecuencias que van más allá del botón de lanzamiento

Una API de despliegue suele ofrecer más que «desplegar esta versión». Puede modificar variables de entorno, activar compilaciones, reiniciar cargas de trabajo, crear dominios, revertir versiones, obtener registros o eliminar recursos. Un token de despliegue amplio se convierte en un control remoto cómodo para un agente que ya ha elaborado un plan equivocado.

Usa categorías de acción diferentes para el trabajo de despliegue. Leer el estado de una compilación y obtener los metadatos públicos de un despliegue suelen ser tareas rutinarias. Promover un artefacto a producción, revertir una versión, cambiar una referencia a un secreto y eliminar un entorno tienen consecuencias distintas. No las agrupes detrás de una sola aprobación llamada «acceso al despliegue».

Una solicitud razonable pide una referencia inmutable al artefacto y un destino explícito. Rechaza entradas vagas como «latest» cuando el servicio pueda resolver un commit, un digest de imagen o un identificador de compilación. Las etiquetas mutables crean un intervalo entre la aprobación y la ejecución: el revisor aprueba una cosa, pero la acción ejecuta otra.

{
  "service": "deployment-platform",
  "action": "promote_release",
  "application": "billing-api",
  "environment": "production",
  "artifact": {
    "git_commit": "8cf4f3a",
    "build_id": "build-4921"
  },
  "reason": "Fixes the confirmed invoice retry failure"
}

El ejecutor debe comprobar que los identificadores aprobados coinciden con la solicitud que envía. También debe registrar el identificador de respuesta del servicio y el entorno de destino. Registrar solo «despliegue correcto» sirve de muy poco a las dos de la madrugada, cuando alguien pregunta qué artefacto se movió y quién lo autorizó.

No hagas que el agente raspe un panel web para evitar diseñar una API. La automatización del navegador oculta detalles de la revisión, falla sin avisar y puede hacer clic sobre un estado antiguo de la página. Si la plataforma ofrece una API, usa una acción mediada y limitada sobre esa API. Si solo ofrece un panel, acepta que algunas operaciones sigan siendo trabajo humano hasta que puedas crear un conector fiable.

Las herramientas de soporte al cliente requieren minimizar los datos antes de automatizar

Los sistemas de soporte combinan acciones operativas con datos personales. Un ticket puede incluir datos de cuenta, información de contacto, archivos adjuntos, historial de pedidos, registros y mensajes cargados de emoción. El acceso directo del agente plantea dos preguntas: ¿puede leer material que no necesita? ¿Puede enviar una respuesta perjudicial en nombre de tu empresa?

No lo resuelvas enviando por defecto transcripciones completas de tickets al agente. Obtén solo los campos necesarios para la tarea. Si el agente necesita clasificar un ticket, quizá necesite el asunto, un cuerpo redactado y el área del producto. Probablemente no necesite todas las notas internas anteriores, los registros de facturación ni los archivos adjuntos.

Las acciones de escritura requieren una revisión más estricta que la clasificación. Un patrón útil es preparar primero y enviar después. El agente crea una propuesta de respuesta con referencias al ticket y a cualquier fuente interna que haya usado. Una persona comprueba el tono, las afirmaciones fácticas, los detalles específicos de la cuenta y si la respuesta revela por accidente notas internas. Solo entonces un ejecutor debe publicar el mensaje.

Cerrar, fusionar o reasignar tickets también requiere una semántica de acción explícita. «Resolver ticket» es demasiado vago si envía en silencio un correo de cierre, cambia el reloj del acuerdo de nivel de servicio o elimina un borrador. El esquema de solicitud debe identificar el efecto secundario que realizará el servicio de soporte.

Aquí es donde una cuenta de servicio amplia resulta especialmente tentadora. Evita problemas de permisos y permite al agente gestionar cualquier cola. También significa que una sola instrucción defectuosa puede cruzar límites entre cuentas. Asigna identidades de servicio a colas o equipos cuando el proveedor lo permita y limita la interfaz de acciones mediadas a las operaciones que ese equipo necesita realmente.

SSH es autoridad de ejecución, no una credencial API con otra sintaxis

SSH merece un tratamiento aparte porque una clave privada puede dar acceso a un shell, transferencia de archivos, reenvío de puertos y herramientas que tienen sus propias credenciales. Una API de despliegue puede ofrecer un conjunto finito de operaciones. Un shell remoto puede combinar nuevas operaciones al instante.

Dar una clave privada SSH a un agente de programación crea dos riesgos a la vez. La clave puede filtrarse y el agente puede generar comandos remotos arbitrarios. Restringir la cuenta ayuda, pero una cuenta restringida con acceso a scripts de despliegue, credenciales de una CLI en la nube o configuración de producción aún puede hacer mucho más de lo que implicaba la tarea original.

Usa un mediador que conserve la clave privada y reciba el host, el comando y los argumentos solicitados. Haz que la acción registre el host resuelto y el comando exacto después de procesar los argumentos. No apruebes una cadena de shell que el agente pueda reinterpretar mediante comillas anidadas, sustitución de comandos o un script remoto obtenido de una rama no confiable.

En hosts sensibles, prefiere operaciones remotas fijas en lugar de un shell general. Un comando como release-status --service billing-api es más fácil de revisar que bash -lc '...'. Si debes permitir un comando general, muéstralo exactamente como se ejecutará y exige aprobación por llamada. Trata sudo, la instalación de paquetes, la lectura de archivos secretos, la redirección del shell y los comandos de copia saliente como casos de mayor riesgo, no como mantenimiento ordinario.

También importa verificar el host SSH. El cliente debe comprobar la clave del host del servidor frente a una entrada de known-hosts gestionada. Aceptar automáticamente una nueva huella del host permite que un error de red o DNS se convierta en un evento de uso de credenciales. Eso anula el propósito de ocultar cuidadosamente la clave privada.

Las acciones mediadas contienen las credenciales y crean un punto de decisión

Un sistema de acciones mediadas mantiene el token SaaS o la clave privada SSH dentro de un ejecutor y ofrece al agente una interfaz para solicitarle trabajo definido. El ejecutor adjunta las credenciales, realiza la solicitud y devuelve el resultado. El agente nunca recibe un secreto, ni siquiera un marcador que pueda sustituir por accidente en un comando.

Esto cambia el modo de fallo. Un agente con acceso directo que acepta una instrucción maliciosa puede decidir y ejecutar una acción con una credencial reutilizable. Un agente mediado aún puede solicitar una acción incorrecta, porque ningún control de seguridad hace perfecto el criterio de un modelo de lenguaje. Pero el ejecutor puede identificar al solicitante, exigir que una persona apruebe la llamada, mantener las credenciales fuera del alcance del agente y registrar la solicitud y el resultado.

Sallyport usa este modelo para llamadas a API HTTP y comandos SSH: un agente compatible con MCP se conecta mediante sp mcp, mientras la aplicación de macOS conserva las credenciales API y SSH en su bóveda cifrada y ejecuta las acciones por sí misma. La compuerta de la bóveda rechaza todas las acciones mientras está bloqueada, que es el comportamiento correcto cuando la persona responsable no está frente al equipo.

No confundas un mediador con un proxy de intermediario. Un proxy observa o retransmite tráfico general. Una puerta de enlace de acciones recibe una solicitud de acción concreta, aplica sus controles de autorización, usa una credencial que conserva y devuelve un resultado. Esa forma más estricta resulta útil porque proporciona un punto de aprobación y un registro de auditoría, en lugar de intentar interpretar todo el tráfico después de que el agente ya lo haya formado.

Las mejores interfaces mediadas son deliberadamente aburridas. Exponen pocos verbos comprensibles, aceptan parámetros estructurados, rechazan destinos ambiguos y devuelven información suficiente para verificar el efecto. Un endpoint universal que acepte URL, encabezados y cuerpos arbitrarios puede recrear silenciosamente el acceso directo con más pasos.

El diseño de aprobaciones falla cuando las personas no pueden juzgar la solicitud

Una solicitud de aprobación debe ayudar a una persona a decidir, no limitarse a interrumpirla. «El agente solicita acceso a la herramienta de soporte» obliga al revisor a aprobar un futuro desconocido. «Publicar esta respuesta en el ticket 4821 como el equipo de soporte» ofrece una acción concreta que puede inspeccionar.

Para la primera llamada de un proceso de agente nuevo, muestra la identidad del proceso y su autoridad de firma de código. La identidad del proceso no es un adorno. En un equipo de desarrollo, varios terminales, extensiones y programas auxiliares pueden solicitar la misma integración. El revisor debe saber qué programa firmado está solicitando el acceso antes de conceder una sesión.

Después, elige el nivel adecuado de autorización:

• Usa una aprobación de sesión para tareas de bajo impacto que necesiten lecturas repetidas o llamadas rutinarias durante una ejecución del agente.
• Usa una aprobación por llamada para mensajes externos, cambios de estado, despliegues, comandos remotos y acciones con efectos irreversibles.
• Bloquea el almacén de credenciales cuando te ausentes, para que cada acción falle en lugar de quedar esperando una aprobación sin supervisión.
• Revoca la sesión actual cuando cambie la tarea, el agente se comporte de forma extraña o ya no reconozcas el proceso.

La fatiga de aprobaciones es un fallo de diseño. Si una persona tiene que aprobar cada consulta inofensiva, aprenderá a hacer clic sin leer. Si una sola aprobación concede al agente toda una tarde de mutaciones en producción, la interfaz ha ocultado demasiada autoridad detrás de la comodidad. Separa los tipos de acción según sus consecuencias y haz que la actividad ordinaria sea silenciosa, mientras que la actividad importante sea específica.

Evita textos de aprobación que repitan la descripción vaga del propio agente. La capa de acciones ya tiene campos estructurados. Úsalos. Muestra el servicio, la cuenta o el rol autenticado, el proyecto o host de destino, la operación y cualquier contenido dirigido a personas que saldrá de la organización. Oculta las credenciales y los campos privados que el revisor no necesite.

Los registros deben conectar cada efecto externo con una ejecución del agente

Los registros del proveedor del servicio por sí solos no bastan para el trabajo de los agentes porque empiezan en el límite de la API. Las transcripciones del agente tampoco bastan porque pueden omitir la solicitud real o editarse. Necesitas un registro de ejecución y otro de llamadas que compartan una conexión fiable.

El diario de una ejecución debe identificar el proceso del agente, el inicio y el final de la sesión, la aprobación que la permitió y una forma de revocarla de inmediato. El diario de llamadas debe registrar la solicitud de acción, el resultado de la autorización y la ejecución, el destino y el identificador de solicitud del servicio cuando exista. Mantén los cuerpos sensibles fuera de las vistas habituales si contienen contenido de clientes, pero conserva pruebas protegidas suficientes para investigar un incidente.

La evidencia contra manipulaciones importa si los registros pueden resolver una disputa. Un archivo de texto local puede mostrar un historial útil, pero un usuario o un proceso comprometido puede reescribirlo. Una cadena de hashes hace que cada registro dependa del anterior, de modo que las modificaciones posteriores rompan la verificación. Eso no vuelve infalible el registro. Hace más difícil reescribirlo sin ser detectado y proporciona al investigador una propiedad de integridad comprobable.

Sallyport proyecta sus diarios Sessions y Activity desde un registro de auditoría cifrado, encadenado mediante hashes y protegido contra escritura. Puedes verificar la cadena de texto cifrado sin conexión con sp audit verify, sin la clave de la bóveda. Una verificación correcta debería tener una forma como esta:

Audit chain: valid
Records checked: 184
First sequence: 1
Last sequence: 184

Si la verificación informa de una secuencia rota o de una discrepancia de hashes, conserva los archivos e investiga antes de confiar en el diario. No «repares» un registro sospechoso eliminando la parte final defectuosa. Podrías borrar la única prueba de cuándo y cómo cambió el registro.

La migración desde tokens directos debe empezar por la credencial más peligrosa

No intentes rediseñar todas las integraciones en una semana. Empieza por la credencial cuyo uso indebido sería más difícil de recuperar: autoridad para desplegar en producción, acceso amplio al soporte de clientes o una clave SSH que llegue a sistemas compartidos. La migración debe retirar los secretos utilizables del agente antes de intentar perfeccionar cada flujo de trabajo.

Sigue esta secuencia para cada integración:

1. Haz un inventario de dónde obtiene hoy la credencial el agente. Incluye variables de entorno, archivos del repositorio, secretos de CI, perfiles del shell, configuración de herramientas y prompts copiados.
2. Enumera las operaciones que el agente realiza realmente y separa lecturas, borradores, mutaciones y ejecución remota. La mayoría de los tokens directos permiten mucho más que esta lista.
3. Crea solicitudes de acción estructuradas para las operaciones necesarias. Vincula cada escritura a un destino con nombre y cada despliegue a una referencia inmutable del artefacto.
4. Mueve la credencial a un ejecutor que el agente no pueda leer. Rota la credencial antigua después de demostrar que la nueva ruta funciona.
5. Prueba los fallos de forma deliberada: bloquea la bóveda, rechaza una aprobación, revoca una sesión, envía un destino no válido y ejecuta la verificación de auditoría. Una demostración del camino correcto no demuestra casi nada.

El paso de rotación detecta un error que los equipos cometen constantemente: añaden un mediador, pero dejan el token original en el entorno del agente «por si acaso». Eso deja dos rutas hacia la misma autoridad y, con el tiempo, se usará la menos controlada. Elimina la alternativa. Si la ruta mediada aún no admite una operación necesaria, documenta la excepción temporal, limita su alcance y duración y asigna a una persona concreta la tarea de eliminarla.

Entregar directamente un token es fácil porque deja la decisión difícil en manos de una cadena dentro del entorno del proceso. Para sandboxes desechables, ese intercambio puede ser razonable. Para servicios que afectan a clientes, despliegues o infraestructura compartida, mantén las credenciales fuera del agente y haz visible la acción antes de que ocurra.