El 29 de agosto de 2026, OpenAI marcó como disponibles de forma general (GA) dos funciones de seguridad para la API: Mutual TLS (mTLS) y federación de identidad de workload con X.509. Se complementan, pero no son lo mismo. mTLS añade la verificación de un certificado de cliente a la autenticación normal de la API. La federación X.509 permite que un workload intercambie una identidad verificada mediante certificado por un token de acceso de corta duración, reemplazando la clave de API sin eliminar la obligación de presentar el certificado en las llamadas protegidas.
Para los equipos que quieren adoptar la función sin convertir un cambio de seguridad en una caída del servicio, el punto clave es el alcance: el certificado de confianza puede activarse por proyecto o para la organización. La ruta más segura es empezar con un proyecto no crítico, validar los workloads y solo después ampliar el alcance.
Qué cambió con el GA del 29 de agosto de 2026
Las notas de lanzamiento de OpenAI indican que, el 29 de agosto de 2026, mTLS y la federación X.509 pasaron a GA para la OpenAI API. La documentación actual para desarrolladores también presenta ambos flujos como funciones disponibles de la API y detalla su configuración, alcance, rotación y autenticación.
Sin embargo, existe una discrepancia documental que conviene señalar: una página del Help Center sobre el “programa beta” de Mutual TLS todavía afirma que la función está en beta, aunque fue actualizada pocos días antes del anuncio de GA. Eso entra en conflicto con las notas de lanzamiento fechadas y con la documentación actual para desarrolladores. Para decisiones de despliegue, la referencia más consistente hoy es combinar el anuncio de GA con las guías actuales de Mutual TLS y federación X.509, y volver a comprobar el estado antes de un cambio en producción.
Antes de activar: permisos, certificados y plan de recuperación
OpenAI usa control de acceso basado en roles para administrar mTLS. El permiso api.mtls.read permite listar, ver y probar la configuración de certificados. El permiso api.mtls.write permite cargar, actualizar, activar, desactivar y eliminar certificados. El rol de propietario de la organización incluye estos permisos, que también pueden concederse mediante un rol personalizado.
Antes de activar cualquier certificado, prepara cuatro elementos:
- un certificado de cliente y su clave privada para cada workload;
- los certificados intermedios necesarios para construir la cadena de confianza;
- un ancla de confianza estable codificada en PEM que pueda activarse a nivel de proyecto u organización;
- un proyecto no crítico y una ruta de recuperación ya probada por si la política bloquea tráfico válido.
Las claves privadas deben mantenerse fuera del control de versiones y de los logs. La misma precaución se aplica al contenido de los certificados y a las credenciales bearer.
Cómo activar mTLS por proyecto
El detalle operativo que evita más sorpresas es sencillo: cargar el certificado no activa mTLS. La carga solo almacena el certificado de confianza. El comportamiento de las solicitudes cambia cuando el certificado se activa para un proyecto o para la organización.
- Abre Organization settings > Security > Mutual TLS en la plataforma.
- Carga un ancla de confianza PEM por objeto de certificado y usa un nombre que identifique la autoridad y la generación de rotación.
- Si es necesario, añade un filtro CEL para restringir qué certificados de cliente verificados puede aceptar esa ancla.
- Activa primero el certificado en un proyecto no crítico.
- Mueve los workloads de ese proyecto a un host mTLS y envía solicitudes representativas desde todos los clientes esperados.
- Después de validar, activa el mismo certificado en los demás proyectos previstos o a nivel de organización.
La administración también puede automatizarse mediante la API:
| Acción | Endpoint |
|---|---|
| Cargar un certificado | POST /v1/organization/certificates |
| Listar certificados de la organización | GET /v1/organization/certificates |
| Consultar, actualizar o eliminar un certificado | GET, POST o DELETE /v1/organization/certificates/{certificate_id} |
| Activar o desactivar para la organización | POST /v1/organization/certificates/activate o /deactivate |
| Listar, activar o desactivar en un proyecto | GET o POST /v1/organization/projects/{project_id}/certificates |
Estas operaciones requieren una credencial administrativa con el permiso de lectura o escritura correspondiente.
Proyecto u organización: cómo se aplica el alcance
El alcance define dónde el certificado pasa a ser obligatorio. La documentación actual indica que OpenAI comprueba los certificados activos a nivel de proyecto antes que los certificados activos a nivel de organización. Si ninguno de los dos alcances tiene un certificado activo, mTLS no añade una verificación de certificado a la solicitud.
En la práctica, la activación por proyecto es la mejor opción para un despliegue gradual: permite probar un servicio, equipo o entorno sin imponer inmediatamente la misma política a todos los proyectos. La activación a nivel de organización es más amplia y solo debería realizarse cuando los workloads afectados ya estén preparados para presentar certificados aceptados.
Este diseño también ayuda con la rotación y el aislamiento de incidentes. Un proyecto puede adoptar una nueva ancla de confianza antes que los demás mientras la organización mantiene otro certificado activo durante la transición.
Requisitos del certificado y de la cadena X.509
La configuración acepta un ancla de confianza PEM por objeto de certificado. El certificado cargado debe ser válido y expirar más de un día después de la carga. Para verificar solicitudes, el certificado del cliente debe incluir un Authority Key Identifier (AKI).
Una solicitud protegida por mTLS solo se acepta cuando:
- el certificado del cliente es válido en el momento de la solicitud y apto para autenticación TLS de cliente;
- la cadena del cliente llega a un ancla de confianza activa a nivel de proyecto u organización;
- el cliente presenta todos los certificados intermedios necesarios durante el handshake TLS;
- la cadena supera la validación X.509 estándar y, cuando existe, el filtro CEL asociado.
OpenAI indica que no obtiene intermediarios faltantes desde URLs AIA y no realiza comprobaciones CRL u OCSP en este flujo. Por tanto, el cliente debe presentar la cadena completa necesaria, y la respuesta ante incidentes debe apoyarse en la rotación, la desactivación y los controles propios del ciclo de vida de certificados.
También pueden añadirse filtros CEL con atributos del subject y de los Subject Alternative Names. Esto permite, por ejemplo, aceptar solo certificados de una unidad organizativa concreta o de un namespace DNS esperado.
Cómo llamar a la API después de la activación
Una vez activado mTLS para el alcance, el tráfico debe usar un host mTLS. Los hosts documentados son:
- mtls.api.openai.com — host mTLS predeterminado;
- mtls-us.api.openai.com — host mTLS regional de Estados Unidos;
- mtls-eu.api.openai.com — host mTLS regional de la Unión Europea.
La ruta /v1 sigue siendo la misma que en la superficie de API correspondiente, pero OpenAI recomienda probar cada API y modelo utilizado por el workload porque la disponibilidad de rutas y modelos puede variar entre hosts regionales.
mTLS no sustituye la autenticación bearer normal. En una prueba con curl, por ejemplo, la llamada debe enviar la cadena del cliente con --cert, la clave privada con --key y seguir enviando el encabezado Authorization: Bearer .... El archivo de cadena debe comenzar con el certificado del cliente y después incluir los intermediarios necesarios.
Cuándo usar federación de identidad X.509
La federación de identidad de workload con X.509 resuelve un problema distinto: eliminar una clave de API de larga duración del workload. El flujo reutiliza el trust store de mTLS, pero añade un proveedor de identidad X.509 y un mapeo hacia una cuenta de servicio de un proyecto.
- La organización carga y activa la raíz de confianza en la configuración de Mutual TLS.
- Un proveedor X.509 deriva atributos openai.* del certificado verificado y debe producir un openai.subject no vacío.
- Un mapeo asocia esa identidad con una cuenta de servicio dentro de un proyecto y concede solo los permisos de API necesarios.
- El workload presenta el certificado a POST https://mtls.auth.openai.com/oauth/token y recibe un bearer token de corta duración.
- El workload llama a la API en un host mTLS enviando tanto el token como un certificado aceptado.
El token sustituye la clave de API, pero no sustituye el certificado. Expira en un máximo de una hora y nunca dura más que el certificado verificado. No existe refresh token: el workload repite el intercambio X.509 para obtener otro token.
La documentación actual también indica que este flujo X.509 es para la OpenAI API y no es compatible con Codex; para Codex, la recomendación es usar OIDC o SPIFFE JWT-SVID según la guía correspondiente de workload identity.
Rotación, errores y limitaciones que deben estar en el runbook
La rotación debe hacerse con solapamiento. Carga la nueva ancla de confianza sin desactivar la anterior, actívala en los alcances previstos, migra los workloads y prueba. Solo después desactiva y, finalmente, elimina el certificado antiguo. Los intermediarios pueden rotarse sin cambiar la raíz configurada siempre que la cadena completa actualizada se presente en las nuevas conexiones.
| Código | Qué comprobar |
|---|---|
| certificate_required | Hay un certificado activo para el alcance, pero la solicitud no presentó material de certificado de cliente. |
| invalid_certificate | El certificado no pudo leerse o no incluye el AKI requerido. |
| certificate_verification_failed | La cadena presentada no llega a un ancla de confianza activa. |
| certificate_attribute_verification_failed | La cadena se verificó, pero el filtro CEL rechazó el certificado. |
| authentication_temporarily_unavailable | Se produjo un fallo temporal del verificador o evaluador CEL; trátalo como transitorio y aplica la política normal de reintentos. |
Entre las limitaciones documentadas están un máximo de 50 objetos de certificado por organización, la ausencia de comprobaciones CRL/OCSP, la incompatibilidad entre mTLS y Private Link y el hecho de que mTLS no ofrece autorización solo mediante certificado. La autenticación bearer sigue siendo necesaria, ya sea con una clave de API tradicional o con el token corto de la federación X.509.
Checklist para desplegar sin bloquear producción
- Confirma que el administrador dispone de api.mtls.read y, para cambios, api.mtls.write.
- Registra el ancla de confianza y valida caducidad, AKI y cadena completa.
- Empieza con un proyecto no crítico y mantén una ruta de rollback ya probada.
- Haz que el workload use el host mTLS correcto y conserva la credencial bearer requerida.
- Prueba todos los modelos, rutas, regiones y clientes que se usarán realmente.
- Usa filtros CEL solo después de validar que los atributos del certificado sean estables y previsibles.
- Planifica la rotación con solapamiento y mantén la clave privada fuera de repositorios y logs.
- Si quieres eliminar claves de API de larga duración, configura federación X.509 con una cuenta de servicio y un mapeo por proyecto.
- Antes de un cambio amplio, vuelve a revisar las notas de lanzamiento y las guías actuales, especialmente mientras la página antigua del Help Center siga mostrando la etiqueta beta.
El valor práctico del GA no es tanto “un botón nuevo” como la posibilidad de tratar la identidad del workload y el transporte mTLS como controles operativos de producción. La activación por proyecto permite reducir el radio de impacto: validar primero, ampliar después y separar claramente quién administra certificados de quién simplemente consume la API.
