# Caducidad, renovación y revocación de una clave Cuándo caduca una clave y cómo avisa antes, cómo renovarla sin cortar el servicio y qué pasa al revocarla o al dar de baja a su responsable. Una clave vale hasta que caduca, si le pusiste fecha, o hasta que alguien la revoca. Entre medias la puedes renovar para cambiar el secreto sin cortar tus programas. Todo se hace en **Ajustes › Claves de API**, con la sesión de una persona: una clave no se renueva ni se revoca a sí misma. ## Estados de una clave **Estados de una clave de API** 1. **Activa** (`ACTIVE`). Funciona con los permisos que marcaste. - **Sin responsable activo** (`RESPONSIBLE_INACTIVE`). Se llega desde Activa cuando: Su persona responsable deja de poder entrar. No funciona hasta que se nombra a otra persona. - **Pausada** (`PLAN_PAUSED`). Se llega desde Activa cuando: Integraciones sale del plan. No funciona, pero se ve y se puede revocar. - **Caducada** (`EXPIRED`, estado final). Se llega desde Activa cuando: Llega su fecha de caducidad. No se renueva ni se cambia: hay que crear otra. - **Revocada** (`REVOKED`, estado final). Se llega desde Activa cuando: Alguien la revoca, o se desactiva o archiva a su responsable. Deja de valer en el acto y para siempre. 2. **En transición** (`IN_TRANSITION`). Se llega desde Activa cuando: La renuevas con días de margen. Valen la nueva y la anterior hasta la fecha que elegiste. Otras transiciones: - En transición → Activa: Llega la fecha o se pulsa «Retirar la anterior ya». - Sin responsable activo → Activa: Se nombra a otra persona responsable. - Pausada → Activa: Integraciones vuelve al plan. _El estado se ve en la lista y en la ficha de cada clave, y viaja en status en la API de gestión._ Si se cumplen varios a la vez, `status` dice el primero de esta lista: revocada, caducada, sin responsable activo, pausada, en transición y activa. ## La caducidad **La caducidad es opcional.** Al crear la clave eliges **Sin caducidad**, 30, 90 o 180 días, 1 año o una fecha concreta, que vale hasta el final de ese día. Una clave caducada responde `401 API_KEY_EXPIRED` y no se puede renovar ni cambiar: hay que crear otra. Cambiar la caducidad de una clave viva depende de hacia dónde la muevas: - **Adelantarla, o ponérsela a una clave que no la tenía**, la hace más segura: basta con el permiso «Gestionar las claves de API», sin verificación en dos pasos. - **Alargarla o quitarla** le da más vida, así que solo lo hacen su persona responsable, si tiene ese permiso, o un Super Administrador, con la verificación en dos pasos si la tienen activa. Con la organización en modo restringido no se puede. Renovar una clave no cambia su caducidad: la clave nueva caduca el mismo día que la anterior. ## El aviso antes de que caduque Si la clave tiene caducidad, UTILIA OS avisa dos veces antes de que llegue: **7 días antes** y **el día antes**. Así ninguna clave con fecha se corta por sorpresa. **Avisos de una clave que caduca** 1. **7 días antes**: Primer aviso. Hay tiempo para alargarla o para cambiarla. Espera 6 días hasta el siguiente. 2. **El día antes**: Último aviso. El último momento para que no se corte. Espera 1 día hasta el siguiente. 3. **Su fecha**: La clave caduca. Responde 401 API_KEY_EXPIRED: hay que crear otra. - **Quién lo recibe:** la persona responsable de la clave y, si es otra, quien la creó, siempre que sigan activas. - **Por dónde:** por los canales que cada una tenga activados en sus [preferencias de avisos](https://os.utilia.ai/docs/guides/security/security-alerts#la-caducidad-de-las-claves-de-api), en la fila **Caducidad de las claves de API** de Seguridad. De fábrica llega en la aplicación y por correo; también puede llegar al móvil y al navegador, o apagarse. - **Adónde lleva:** a la ficha de la clave, en **Ajustes › Claves de API**, con el botón **Ver la clave**. - **Si cambias la caducidad**, los avisos se vuelven a programar para la fecha nueva. - **Si Integraciones sale del plan** o la persona responsable deja de estar activa, no hay avisos, porque la clave tampoco funciona. - **Si la clave se crea con menos de 7 días por delante**, el primer aviso sale enseguida. Una clave sin caducidad no avisa nunca: vale hasta que alguien la revoca. ## Evitar que se corte Cuando llega el aviso y el programa sigue necesitando la clave, tienes dos caminos: - **Alargar la caducidad** desde la ficha de la clave, con **Editar**. Lo hacen su persona responsable, si tiene «Gestionar las claves de API», o un Super Administrador, y pide la verificación en dos pasos a quien la tiene activa. Por la API es un `PATCH` con la fecha nueva en `expiresAt`, como en [Alargar la caducidad](https://os.utilia.ai/docs/developers/organization-api-keys/management-api#alargar-la-caducidad). - **Crear otra clave** y cambiarla en tus servidores antes de la fecha. La nueva actúa con los permisos de su propia persona responsable, que no tiene por qué ser la misma. Si la clave ya ha caducado, solo queda el segundo camino: una clave caducada no se renueva ni se edita (`409 API_KEY_NOT_MODIFIABLE`). Con la organización en modo restringido no se puede ni alargar ni crear (`403 ORGANIZATION_RESTRICTED`), así que conviene no apurar la fecha. ## Renovar una clave **Renovar** te da un secreto nuevo y te deja elegir cuánto sigue valiendo el anterior: **1 día**, **7 días (recomendado)**, **30 días** o **Deja de valer en el acto**. Sirve cuando cambia quién tiene acceso a la clave o cuando sospechas que se ha visto donde no debía. Mientras dura la transición, las peticiones con la clave anterior funcionan y su respuesta lleva la cabecera `X-Utilia-Api-Key-Expires` con la fecha en que dejará de valer (ISO 8601, en UTC). Si la ves en tus registros, algún servidor tuyo sigue con la anterior. **Renovar con 7 días de transición** 1. **Día 0**: Renuevas la clave. Ves la nueva una sola vez; la anterior sigue valiendo. Espera 7 días hasta el siguiente. 2. **Días 0 a 7**: Cambias tus servidores. Las respuestas a la anterior llevan X-Utilia-Api-Key-Expires. 3. **Día 7**: La anterior deja de valer. O antes, si se pulsa «Retirar la anterior ya». Las renovaciones no se encadenan: durante una transición, renovar con días de margen responde `409 ROTATION_IN_PROGRESS`, y renovar con **Deja de valer en el acto** corta a la vez la actual y la anterior. Renovar entrega el secreto, así que solo lo hacen la persona responsable de la clave o un Super Administrador, con la verificación en dos pasos si la tienen activa. ## Revocar una clave **Revocar** corta la clave y la anterior, si la hay, en el acto y sin vuelta atrás: la petición siguiente recibe `401 API_KEY_REVOKED`. Pueden revocarla quienes tienen «Gestionar las claves de API» y también su persona responsable, aunque no gestione claves. Revocar siempre se puede, aunque Integraciones haya salido del plan o la organización esté en modo restringido. ## Al dar de baja a alguien Al desactivar o archivar a una persona, se revocan en el acto las claves de las que es **persona responsable**, con el motivo «Revocada al dar de baja o archivar a su persona responsable.» y una anotación en la auditoría por cada clave. Las claves que esa persona **creó para otra** siguen funcionando: una clave actúa con los permisos de su responsable, no de quien la creó, así que su marcha no cambia lo que la clave puede hacer. Lo único que cambia es que deja de recibir los avisos de caducidad de esas claves. Reactivar a la persona no devuelve ninguna clave revocada: si sus programas las siguen necesitando, hay que crear otras. ## Siguiente paso - [Crear y gestionar claves de API](https://os.utilia.ai/docs/guides/security/api-keys): Renovar, retirar la anterior y revocar desde la pantalla, paso a paso. - [Avisos y No molestar](https://os.utilia.ai/docs/guides/notifications/overview): Por dónde te llega cada aviso y cómo se apaga.