Política de versionado y obsolescencia de la API

Esta página explica cómo KeenAuth versiona sus API, cómo se anuncia una eliminación y durante cuánto tiempo los SDK, la CLI, el proveedor de Terraform/OpenTofu y el servidor MCP reciben correcciones de seguridad. Cada anuncio se publica en el registro de cambios.

Versiones de la API

La API de gestión lleva su versión principal en la ruta (/v1). Dentro de v1 solo se hacen cambios aditivos:

• un nuevo endpoint;
• un nuevo campo de solicitud opcional;
• un nuevo campo de respuesta;
• un nuevo valor de enumeración;
• un nuevo código de error;
• un nuevo tipo de evento.

Escriba su integración de modo que acepte estas incorporaciones.

Un cambio incompatible solo se hace en una nueva versión principal (/v2). Los cambios incompatibles son: eliminar o renombrar un campo, cambiar un tipo, añadir un campo obligatorio, cambiar el comportamiento predeterminado y cambiar la paginación, la ordenación o el valor predeterminado de limit. v1 sigue disponible al menos 24 meses después de la disponibilidad general de v2.

KeenAuth no usa encabezados de versión basados en fechas; la versión principal en la ruta y la regla de solo cambios aditivos constituyen todo el contrato.

Operaciones beta y GA

Cada operación está marcada con x-idp-stability: beta o x-idp-stability: ga en el documento OpenAPI. Una operación beta puede cambiar durante una beta privada o pública y no está sujeta a las reglas de obsolescencia que siguen; sus respuestas llevan el encabezado Idp-Stability: beta. Una operación ga está congelada: solo cambia según las reglas de esta página.

Eventos y claims del token

• Los tipos de evento para clientes llevan una versión de esquema (v<n>). Un cambio incompatible en una carga útil crea una nueva versión de esquema; ambas versiones se entregan en paralelo durante 365 días y cada endpoint de webhook elige la versión que recibe.
• Añadir un claim al token es un cambio aditivo. Eliminar un claim o cambiar su significado se anuncia con 365 días de antelación, y se actualiza claims_supported en el documento de descubrimiento.

Obsolescencia y eliminación

La eliminación de un endpoint, un parámetro, un claim, un scope, un tipo de evento, un algoritmo de firma u otra superficie se anuncia en el registro de cambios al menos 365 días antes de la fecha de eliminación. Cada obsolescencia tiene un identificador con el formato dep-<YYYY>-<NN>, una fecha de obsolescencia, una fecha de eliminación (sunset), un sustituto si existe y una guía de migración.

Excepción de seguridad: para corregir una vulnerabilidad de seguridad, el comportamiento dentro de v1 puede cambiar sin el preaviso de 365 días. Un cambio así se publica en el registro de cambios con la etiqueta security, y se notifica por correo electrónico a los entornos afectados.

Señales en las respuestas de la API

La respuesta de una operación que se va a eliminar lleva:

• Deprecation: @<unix_epoch>: la fecha de obsolescencia como fecha estructurada RFC 9745;
• Sunset: <IMF-fixdate>: la fecha de eliminación (RFC 8594);
• Link: <doc_url>; rel="deprecation" y Link: <doc_url>; rel="sunset": la guía de migración.

Después de la fecha de eliminación, la operación responde 410 con el código de problema endpoint_sunset. Las eliminaciones del protocolo OAuth y OpenID Connect (un algoritmo de firma, un método de autenticación del cliente, un parámetro) no pueden llevar encabezados; se cuentan por cliente y pasan por las mismas notificaciones.

Dónde ve su uso

• Registro del entorno: un registro deprecation_notice, como máximo una vez por hora, con deprecation_id, client_id y sunset_at.
• Panel: la página Obsolescencias muestra los últimos 30 días por obsolescencia, cliente y versión del SDK; desde 90 días antes de la fecha de eliminación aparece un aviso.
• API: GET /v1/reports/deprecation-usage?from=&to= (permiso reports:read).
• Correo electrónico: a los roles owner y admin de la cuenta y al contacto técnico del entorno, el día del anuncio (cada entorno que usa la superficie) y 180, 90, 30 y 7 días antes de la fecha de eliminación (entornos que la usaron en los últimos 30 días).

Los SDK oficiales, la CLI, el proveedor y el servidor MCP envían Idp-Client: <package>/<version> (<runtime>/<version>) con cada solicitud. El encabezado no es una autenticación; solo se usa para contar, y un valor mal formado se ignora. Los recuentos de uso no almacenan direcciones IP, User-Agent ni identificadores de usuarios finales.

Política de soporte de SDK y herramientas

Los SDK, la CLI, el proveedor de Terraform/OpenTofu y el servidor MCP siguen el versionado semántico. Una versión principal solo aumenta con un cambio incompatible en el propio lenguaje o con una nueva versión principal de la API.

• La línea de productos en su conjunto recibe soporte de seguridad durante al menos 5 años, contados desde su disponibilidad general.
• Las correcciones de seguridad se publican en la última versión principal de cada paquete, y actualizar a ella es gratuito.
• La versión principal anterior recibe correcciones de seguridad y de errores críticos durante 12 meses después de la disponibilidad general de la nueva versión principal; después llega al fin de su vida útil.
• Cada actualización de seguridad publicada sigue disponible durante al menos 10 años, o durante el resto del periodo de soporte si este es más largo.
• Desde 90 días antes del fin de la vida útil, un SDK escribe en el registro de su aplicación una advertencia con el encabezado Deprecation del servidor y su propia fecha de fin de vida útil.
• El servidor no bloquea las versiones del SDK que han llegado al fin de su vida útil; el panel y el correo electrónico le avisan.
• El fin del soporte se anuncia en el registro de cambios y en el registro de paquetes (npm deprecate; en PyPI una descripción, la versión no se retira).

Compatibilidad con entornos de ejecución

Los SDK son compatibles con las versiones de entorno de ejecución que sus proveedores siguen manteniendo con correcciones de seguridad: Node.js LTS, Python según el calendario de soporte de origen, las dos últimas versiones de Go, Java 17 y 21, .NET LTS, PHP 8.2 y posteriores, Ruby 3.2 y posteriores, iOS 16 y posteriores, Android API 26 y posteriores. La matriz mínima de entornos de ejecución se publica con cada versión principal. Un entorno de ejecución que pierde el soporte de su proveedor se abandona en una versión menor, que se anuncia en el registro de cambios con 90 días de antelación.