Autenticación HTTP para agentes de IA: patrones seguros para las credenciales

Un agente de IA debería poder solicitar una acción HTTP sin tener nunca la credencial que la hace posible. Esta regla importa más que saber si la solicitud usa un token bearer, autenticación Basic o un encabezado del proveedor. Si un secreto entra en el contexto del agente, puede filtrarse a través de un prompt, un registro de herramientas, un comando de shell generado, un archivo del repositorio o un resumen posterior que nadie pensaba conservar.

Los patrones de autenticación HTTP siguen siendo importantes porque cada uno determina qué se puede robar, reutilizar, reenviar por accidente y auditar. El diseño correcto parte del esquema que exige la API y después limita la credencial a un ejecutor de confianza que envía una solicitud definida de forma precisa en nombre del agente.

Los agentes convierten las credenciales habituales en datos copiados

Un agente desatendido cambia el riesgo de una credencial de API normal porque lee y escribe muchas formas de texto. Un desarrollador puede guardar un token en un almacén local de credenciales y pegarlo en una sola solicitud. Un agente puede inspeccionar variables de entorno, escribir información de depuración, preparar un comando curl, crear archivos de configuración e informar de su trabajo a una persona. Cada una de esas operaciones crea otro lugar donde puede acabar un secreto reutilizable.

La ruta peligrosa suele parecer inofensiva al principio:

1. Un ejecutor de tareas coloca PAYMENTS_TOKEN en el entorno del proceso del agente.
2. El agente ejecuta un comando de diagnóstico que imprime su entorno o escribe un script de shell.
3. El script llega a un repositorio, un artefacto de CI, el historial visible de una terminal u otra llamada de herramienta del agente.
4. Alguien encuentra el token más tarde y envía solicitudes válidas hasta que caduca o un operador lo revoca.

El token no necesitó un atacante sofisticado. Solo tuvo que convertirse en texto en un lugar diseñado para copiar texto.

No confundas el control de acceso del agente con la confidencialidad de las credenciales. Un sandbox puede impedir que un agente abra archivos fuera de un directorio. No ayuda si el secreto ya aparece en el contexto del modelo, en los argumentos de un comando o en el resultado de una herramienta. Del mismo modo, un aviso de aprobación que pregunta si el agente puede ejecutar curl aporta poco si el agente puede proporcionar cualquier host, ruta, cuerpo y encabezado de autorización heredado.

Por eso la autenticación HTTP para agentes de IA necesita dos fronteras independientes. El agente necesita permiso para proponer una solicitud. Un componente de confianza necesita custodiar la credencial y tener autoridad para enviar la solicitud. Si combinas ambas fronteras, entregas al agente un secreto fácil de copiar y haces que los controles posteriores dependan de que lo maneje perfectamente. Es una suposición de diseño poco razonable.

Una prueba útil es sencilla: pregunta si podrías pegar la transcripción completa del agente en un sistema de seguimiento de incidencias sin revocar la credencial. Si la respuesta es no, el secreto ha cruzado la frontera equivocada.

Los tokens bearer son fáciles de enviar y de reutilizar

Un token bearer da acceso a quien lo presenta, por lo que un agente nunca debe recibir uno a menos que aceptes que una filtración de la transcripción puede convertirse en una filtración de acceso a la API. RFC 6750 define el uso de tokens bearer en el encabezado de solicitud Authorization:

GET /v1/projects/alpha/releases HTTP/1.1
Host: api.example.test
Authorization: Bearer eyJhbGciOi...
Accept: application/json

El servidor no necesita demostrar que quien envía la solicitud es el agente previsto, el usuario original o la máquina original. Comprueba si el token presentado es válido y está autorizado. Esta propiedad mantiene simples los clientes HTTP, pero también hace que los tokens copiados resulten útiles para cualquiera que los tenga.

RFC 6750 permite enviar tokens bearer en el cuerpo de un formulario bajo condiciones restringidas y describe el uso de URI para casos antiguos. No los coloques en las cadenas de consulta. Las URL llegan al historial del navegador, a registros de proxies, sistemas de analítica, encabezados de referencia, tickets de soporte y registros de aplicaciones con más facilidad de lo que muchos equipos esperan. La propia norma advierte que el transporte mediante URI tiene una alta probabilidad de exposición. No hay una buena razón para convertir el secreto de un agente en parte de una URL.

Los tokens bearer encajan bien con los agentes solo cuando el diseño de credenciales que los rodea limita el daño. Prefiere tokens destinados a una audiencia de API concreta, con permisos limitados, una caducidad breve y una identidad independiente para el ejecutor de la acción. Un token de API que puede administrar todos los proyectos, leer todos los registros de clientes y no caduca nunca es una credencial maestra de producción con un nombre más amable.

El argumento habitual para entregar un token bearer a un agente es la rapidez: una variable de entorno, un cliente HTTP y ningún componente adicional. Es popular porque funciona en una demostración. Falla cuando el agente necesita depuración, delegación, tareas de larga duración o acceso a más de un servicio. Un token copiado en el contexto se vuelve más difícil de revocar de forma selectiva porque ya no sabes por todos los lugares que ha pasado.

Hay otra trampa: un token con un nombre restrictivo puede tener una autoridad efectiva muy amplia. Lee la documentación del proveedor para conocer el modelo de alcance real. Algunos servicios usan alcances específicos por endpoint. Otros conceden derechos a nivel de organización, proyecto, repositorio o cuenta. Algunos tokens de API heredan silenciosamente todos los privilegios del usuario que los creó. La etiqueta del token no demuestra cuáles son sus límites.

Un mediador puede custodiar el token bearer y construir el encabezado solo después de validar el destino solicitado. El agente debe enviar la intención y los datos de la solicitud, por ejemplo, «crear una versión en el proyecto alpha con este cuerpo», en vez del encabezado Authorization literal. El ejecutor añade el secreto después de validar y lo elimina antes de devolver cualquier registro al agente.

La autenticación Basic necesita una identidad de servicio independiente

La autenticación Basic puede ser aceptable para una cuenta de servicio limitada a través de TLS, pero es una forma deficiente de entregar a un agente el nombre de usuario y la contraseña de una persona. RFC 7617 define el formato transmitido como una codificación base64 de user-id:password colocada en el encabezado Authorization:

Authorization: Basic YWdlbnQtcmVsZWFzZXI6czNjcjN0LXZhbHVl

Cualquiera que pueda leer ese valor puede decodificarlo. Base64 cambia la representación, pero no protege el valor. TLS protege la conexión entre cliente y servidor, pero no protege la credencial después de que un agente, proceso local, registro de depuración o proxy haya copiado el encabezado.

Muchos proveedores de API usan autenticación Basic con un token de API como contraseña y un nombre de usuario fijo o ignorado. Eso no convierte el esquema en una versión más débil de la autenticación bearer. Crea una exposición similar a la reutilización, además de algunos riesgos prácticos. Un cliente o un registrador puede guardar el nombre de usuario decodificado, el encabezado sin procesar o ambos. Un desarrollador puede reutilizar una contraseña real de una cuenta porque el protocolo llama contraseña al segundo campo. Esa es precisamente la credencial que no debes delegar a un proceso autónomo.

Cuando la autenticación Basic sea inevitable, crea una cuenta exclusiva para el ejecutor. Dale solo los permisos necesarios para esa familia de solicitudes. No uses una cuenta personal, una cuenta de administrador ni credenciales compartidas entre automatizaciones sin relación. Una identidad de servicio permite revocar e investigar sin bloquear a una persona ni romper todos los trabajos a la vez.

Gestiona la codificación de caracteres de forma deliberada. RFC 7617 describe un problema de compatibilidad relacionado con el conjunto de caracteres del nombre de usuario y la contraseña, y permite que los servidores anuncien UTF-8. Si un proveedor solo admite valores ASCII normales, mantén las credenciales de máquina dentro de ese conjunto. No inventes un paso de codificación propio en un prompt del agente, porque crearías otro lugar incoherente donde un secreto puede transformarse y registrarse.

El ejecutor de solicitudes debe construir por sí mismo el encabezado Basic a partir de campos protegidos. El agente puede elegir una operación aprobada y proporcionar parámetros no secretos. No debe construir el valor base64 y nunca debe ver una credencial decodificada en un mensaje de error. Un error seguro indica que la autenticación falló para la referencia de credencial seleccionada. No repite el encabezado ni informa al agente de qué parte de la contraseña coincidió.

Los encabezados personalizados necesitan una semántica exacta del proveedor

Un encabezado de autenticación personalizado solo es seguro en la medida en que lo sean las reglas de verificación documentadas por la API y el manejo de su valor. Algunos ejemplos habituales son X-API-Key, Api-Key o un encabezado específico del proveedor. Algunos proveedores esperan una clave de API estática. Otros esperan una solicitud firmada con una marca de tiempo, un nonce, una ruta canónica y un resumen del cuerpo. Tratar todos los encabezados personalizados como intercambiables es una forma de romper la autenticación y, peor aún, de ampliar accidentalmente los lugares a los que se envía una credencial.

Primero, sigue exactamente la especificación del proveedor. Los nombres de los encabezados no distinguen mayúsculas y minúsculas en HTTP, pero los valores y las entradas de una firma pueden distinguirlas. Un esquema de firma puede exigir un orden concreto de canonicalización, los bytes exactos del cuerpo y una ventana temporal limitada. Si el ejecutor analiza JSON y lo vuelve a serializar antes de firmarlo, puede producir un JSON aparentemente válido con una secuencia de bytes diferente. El proveedor rechazará la solicitud y muchas personas responden desactivando las comprobaciones de firma o añadiendo reintentos demasiado amplios. Corrige el manejo de los bytes.

Segundo, distingue un encabezado usado para autenticar de otro que identifica a un cliente. User-Agent, los identificadores de solicitud y los identificadores de aplicación pueden ayudar al proveedor a observar el tráfico, pero normalmente no demuestran autoridad. Por el contrario, un encabezado X-API-Key puede ser tan reutilizable como Authorization: Bearer. No midas su sensibilidad por si su nombre contiene la palabra autorización.

Tercero, impide que el agente introduzca encabezados de contrabando. El agente no debe recibir un mapa libre de encabezados salientes si un ejecutor protegido también inyecta credenciales. Un mapa libre le permite añadir un segundo encabezado Authorization, sobrescribir un tipo de contenido esperado, adjuntar un encabezado de identidad no aprobado o influir en un proxy intermedio de formas que el revisor no vio.

Usa un contrato de solicitud con campos definidos y tipados. Por ejemplo:

{
  "credential_ref": "release-service",
  "method": "POST",
  "url": "https://api.example.test/v1/projects/alpha/releases",
  "headers": {
    "accept": "application/json"
  },
  "body": {
    "version": "2025.06.0",
    "notes": "Fix parser crash on empty input"
  }
}

El ejecutor, no el agente, convierte credential_ref en el encabezado personalizado o el procedimiento de firma del proveedor. Debe rechazar intentos de proporcionar authorization, cookie, el encabezado de credenciales del proveedor, host o una forma duplicada de cualquiera de esos nombres. También debe encargarse de Content-Length, porque el cliente HTTP debe calcularlo a partir de los bytes finales.

La respuesta que se muestra al agente necesita la misma disciplina. Una respuesta HTTP puede incluir Set-Cookie, diagnósticos o detalles repetidos de la solicitud. Devuelve el estado, los encabezados seguros seleccionados y el cuerpo necesario para la tarea. Conserva los encabezados y las trazas sin procesar en un almacenamiento de auditoría protegido cuando los operadores los necesiten.

Elige el esquema que exige el proveedor y limita el impacto

Rara vez eliges el esquema de autenticación de una API de terceros. El proveedor ya lo ha elegido. Lo que sí puedes elegir es si la credencial será amplia o limitada, dónde vivirá, qué solicitudes podrán usarla y qué ocurrirá cuando el agente se comporte de forma extraña.

Usa esta comparación al diseñar la frontera:

Las solicitudes firmadas requieren una precisión importante. Una marca de tiempo y un nonce pueden reducir la reutilización directa en la frontera de la API, pero no hacen seguro el secreto de firma dentro del contexto del agente. Un agente que pueda acceder al secreto puede firmar una solicitud maliciosa nueva. Si la implementación de firma acepta cualquier método, host, ruta y cuerpo del agente, firmará fielmente acciones que no pretendías autorizar.

El alcance debe corresponder a la acción, no a un uso futuro imaginado. Un agente que publica versiones quizá necesite permiso para crear una versión en un solo proyecto. No necesita permiso para borrar proyectos, modificar la facturación, leer todos los artefactos o invitar a usuarios. Si un proveedor no puede emitir una credencial con límites adecuados, coloca delante de su API un servicio más restringido que controles o conserva la aprobación humana para las llamadas peligrosas.

No intentes resolver unos alcances deficientes con una lista de permitidos extensa escrita en lenguaje natural. «Usa el token solo para versiones» es un consejo, no un punto de control. Aplica la restricción donde se construye la solicitud: origen esperado, método permitido, patrón de ruta, conjunto de encabezados, esquema del cuerpo y tamaño máximo de la respuesta. Esas restricciones hacen que la credencial sea menos útil fuera de su trabajo previsto.

La mediación mantiene los secretos fuera del contexto del agente

Las llamadas HTTP mediadas funcionan cuando quien guarda el secreto ejecuta la solicitud, en vez de devolver el secreto para que el agente la ejecute. La diferencia puede confundirse porque ambos diseños pueden presentar al agente una herramienta llamada http_request. El flujo de datos muestra qué diseño has construido.

En el diseño inseguro, la herramienta obtiene un token y se lo entrega al agente, quizá como una variable de entorno, una expansión de marcador o una credencial «temporal». La siguiente acción del agente envía la solicitud. El token ya ha entrado en un sistema diseñado para razonar sobre texto, transformarlo y repetirlo.

En el diseño mediado, el agente envía una solicitud estructurada a un ejecutor. El ejecutor comprueba que la solicitud tenga la forma permitida, obtiene la credencial seleccionada del almacenamiento protegido, inyecta el material de autenticación correcto, envía la solicitud, registra la acción y devuelve un resultado limitado. El agente nunca recibe el valor secreto, una forma codificada de este ni un comando de shell que lo contenga.

Esta diferencia también cambia la respuesta ante incidentes. Si sospechas que una sesión del agente ha fallado, puedes detener su capacidad de solicitar acciones sin rotar inmediatamente todas las credenciales. Si la propia credencial pudo escapar, aun así debes rotarla. Revocar una sesión y rotar una credencial resuelven problemas distintos, y los equipos pierden tiempo cuando los tratan como si fueran el mismo botón.

Un ejecutor práctico debería rechazar de forma predeterminada varias formas de solicitud:

• URL absolutas que apunten a un origen no aprobado, incluidos subdominios parecidos.
• Solicitudes con encabezados Authorization, Cookie, de proxy o específicos de credenciales proporcionados por el usuario.
• Redirecciones que puedan llevar una solicitud autenticada a otro origen.
• Métodos fuera del uso previsto de la credencial, especialmente los destructivos.
• Cuerpos que superen el tamaño esperado o no coincidan con el formato del endpoint.

Sallyport aplica este modelo de custodia en macOS: su bóveda cifrada guarda credenciales de API y SSH, mientras un agente MCP solicita a la aplicación que realice llamadas HTTP en vez de recibir los valores de las credenciales.

No confundas la mediación con un motor de políticas de propósito general. No puede determinar si «borrar recursos de prueba obsoletos» es correcto en una cuenta de producción concreta. Puede garantizar que una solicitud se mantenga dentro de una frontera técnica definida y que la credencial permanezca fuera del contexto del agente. La revisión humana, las cuentas limitadas y las protecciones específicas de la aplicación siguen decidiendo si la acción merece aprobación.

La frontera de la solicitud debe incluir redirecciones, DNS y respuestas

Aprobar únicamente https://api.example.test es demasiado amplio porque una solicitud con credenciales contiene más que un hostname. El ejecutor debe controlar cada lugar donde el agente pueda cambiar el destino efectivo o el significado de la solicitud.

Empieza con un origen exacto: esquema, hostname y puerto. Exige HTTPS para las credenciales de API normales de Internet. RFC 9110 define las reglas del destino y la autoridad de una solicitud HTTP, pero el código de la aplicación aún debe aplicar sus propias reglas de destino. No apruebes hosts solo por sufijo. Una comprobación como «el hostname termina en example.test» puede aceptar notexample.test; una comprobación por subcadena es peor. Compara los hostnames analizados con una lista exacta de permitidos o con una regla de subdominios diseñada de forma intencionada.

Después limita los métodos y las rutas. Si el agente debe crear versiones, permite la familia precisa de rutas POST que necesita. No añadas DELETE porque pueda resultar útil durante la limpieza. No permitas rutas versionadas arbitrarias sin decidir si una versión posterior de la API ofrece un comportamiento diferente. La normalización de rutas también importa. Analiza la URL antes de compararla y rechaza codificaciones inesperadas, segmentos de punto o separadores duplicados si el código de coincidencia no los maneja de forma predecible.

El comportamiento ante redirecciones requiere un tratamiento explícito. Las bibliotecas HTTP difieren y una actualización puede cambiar los valores predeterminados. Para llamadas con credenciales, la opción más segura es rechazar las redirecciones e informar de la ubicación al agente. Si un proveedor necesita realmente una redirección, permite solo el origen de destino esperado y reconstruye la solicitud bajo las mismas restricciones. Nunca supongas que un cliente elimina las credenciales de forma suficientemente uniforme como para que una redirección abierta sea inofensiva.

DNS crea una segunda comprobación de destino. Un hostname de confianza puede resolver a direcciones cambiantes, y algunos sistemas internos tienen nombres que apuntan a redes sensibles. Si el ejecutor se ejecuta en un portátil de desarrollo, el HTTP saliente arbitrario puede convertirse en una ruta hacia servicios locales de administración o endpoints de metadatos de la nube. Restringe los orígenes aprobados antes de conectarte, no aceptes configuraciones de proxy controladas por el agente y no permitas que el agente seleccione una interfaz de red o un resolvedor.

Por último, limita y filtra la respuesta. Un agente no necesita una descarga de varios megabytes para saber que la creación de una versión tuvo éxito. Los cuerpos grandes desperdician contexto y pueden transportar instrucciones copiadas de un servicio no confiable al razonamiento del agente. Cuando puedas, devuelve solo los campos necesarios para la siguiente acción. Marca el texto remoto como datos en el contrato de la herramienta y nunca permitas que el contenido de una respuesta modifique las reglas de autorización del ejecutor.

La aprobación debe identificar el proceso que llama y la acción concreta

Un clic de aprobación humana solo sirve cuando proporciona suficiente información para decidir. «Permitir acceso del agente a la API» es un permiso general disfrazado de aviso. Fomenta la fatiga de aprobación porque la persona no puede saber qué proceso local lo solicitó, qué credencial pretende usar o qué enviará.

Identifica el proceso que llama de una forma que ayude al operador a reconocerlo. En macOS, la autoridad de firma de código suele ser más útil que un nombre de proceso mutable. Un proceso llamado agent puede ser una herramienta legítima de desarrollo o un binario ajeno que eligió el mismo nombre. La relación entre procesos, la ruta del ejecutable y la información de firma ofrecen mejores indicios, aunque ninguno sustituye una solicitud de acción limitada.

La aprobación de una sesión y la aprobación de una solicitud resuelven compromisos distintos. La aprobación de sesión reduce interrupciones repetidas durante una ejecución conocida del agente. Funciona para operaciones de bajo riesgo y repetitivas cuando la credencial y la frontera de la solicitud siguen siendo limitadas. La aprobación de solicitudes encaja con operaciones irreversibles o sensibles, como publicar externamente, cambiar permisos de acceso o escribir datos que activarán otro sistema.

Evita un diseño que pida a una persona revisar un volcado HTTP extenso y sin procesar en cada llamada. Después de la tercera interrupción, la gente lo aprobará sin leerlo. Muestra un resumen conciso de la acción: la identidad de servicio, el método, el destino, la ruta, los campos relevantes del cuerpo y cualquier efecto secundario documentado por la API. Conserva los detalles sin procesar en el registro de auditoría para investigarlos más tarde.

También debes distinguir el permiso para iniciar una sesión del permiso para mantenerla activa. Si un proceso del agente termina, un proceso sustituto no debería heredar la aprobación solo porque tenga el mismo nombre. Si un usuario revoca una sesión, el ejecutor debe dejar de aceptar inmediatamente sus llamadas. Una etiqueta de interfaz que diga «revocada» mientras un cliente ya autorizado sigue enviando solicitudes es peor que no tener una función de revocación, porque crea una falsa sensación de seguridad.

Los registros de auditoría deben explicar qué ocurrió después de que el agente termine

Un registro de auditoría útil permite responder quién solicitó una llamada, qué referencia de credencial usó el ejecutor, adónde fue la solicitud, qué permitió el ejecutor y qué devolvió el servicio remoto. No necesitas registrar el secreto sin procesar para responder a esas preguntas. De hecho, hacerlo crearía un segundo almacén de secretos disfrazado de observabilidad.

Para cada llamada, conserva la identidad de la sesión o del proceso, la marca de tiempo, la referencia de credencial seleccionada, el método HTTP, el origen aprobado, la ruta, una representación protegida de los datos relevantes de la solicitud, el estado de la respuesta y la decisión que la permitió o rechazó. Registra el destino final real después de cualquier redirección permitida. Registra también los fallos. Los intentos repetidos contra una ruta inusual suelen revelar una instrucción defectuosa del agente o un intento de escapar de la frontera.

La evidencia de manipulación cambia cuánto puedes confiar en el registro. Un registro encadenado mediante hashes vincula cada entrada con las anteriores, de modo que las modificaciones o eliminaciones posteriores se vuelven detectables durante la verificación. No demuestra que el ejecutor original tomara una buena decisión de autorización ni convierte en confiable un host comprometido. Sí dificulta la edición silenciosa del historial, que es exactamente lo que se necesita revisar durante un incidente.

Mantén el registro de auditoría separado del contexto de trabajo habitual del agente. El agente puede recibir un resumen como 201 Created, release id r-4821. Un operador puede necesitar un registro más completo con la ruta y los metadatos de la decisión. Ninguna de las dos partes debe recibir el encabezado de autorización sin procesar solo porque exista un registro.

Con Sallyport, los registros de Sessions y Activity se proyectan desde un registro de auditoría cifrado y encadenado mediante hashes, y sp audit verify puede verificar esa cadena sin conexión sin desbloquear la bóveda. Es un diseño adecuado para las revisiones porque la verificación no requiere exponer las credenciales que autorizaron las llamadas.

Prueba las rutas de error antes de conceder acceso a producción

Una frontera de credenciales que solo funciona en el caso normal no ha demostrado estar preparada para producción. Construye una API de prueba o usa una cuenta que no sea de producción y haz que el ejecutor demuestre que rechaza las situaciones que filtrarían o usarían mal las credenciales.

Usa una secuencia de prueba como esta:

1. Solicita un endpoint GET aprobado y confirma que el agente recibe el cuerpo esperado, pero ningún encabezado que contenga credenciales.
2. Proporciona un encabezado Authorization desde el agente y confirma que el ejecutor lo rechaza en vez de combinarlo o reemplazar encabezados silenciosamente.
3. Cambia la URL a un host no aprobado y a una coincidencia engañosa, y confirma que ambas solicitudes fallan antes de cualquier llamada de red.
4. Devuelve una respuesta 302 entre orígenes desde la API de prueba y confirma que el ejecutor se detiene en vez de reenviar la autenticación.
5. Revoca la sesión del agente durante una ejecución y confirma que las llamadas posteriores fallan mientras la verificación de auditoría sigue funcionando.

Inspecciona los entornos de los procesos, los directorios temporales, el historial del shell, los archivos generados, los informes de errores y los registros de prueba después de la ejecución. Busca una cadena de credencial de prueba conocida. Este ejercicio detecta una cantidad sorprendente de filtraciones en scripts envolventes y modos de depuración que las pruebas a nivel de solicitud nunca ven.

Prueba también los errores del proveedor. Una API puede devolver un cuerpo que repita contenido de un encabezado no válido, un identificador de traza o consejos para reintentar con otro endpoint. Confirma que el filtro de resultados no devuelva material parecido a credenciales al agente y que la lógica de reintento no convierta una solicitud rechazada en una avalancha de intentos. Limita los reintentos a errores para los que la documentación de la API indique que son adecuados, y mantén sin cambios el método y el destino.

La primera credencial de producción debe ser lo bastante limitada como para que un fallo durante las pruebas resulte incómodo, no catastrófico. Si tu equipo no puede explicar exactamente qué formas de solicitud autoriza y cómo revocar una ejecución activa del agente, la credencial todavía es demasiado amplia para un uso autónomo.