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.
Actualizado el . 6 min de lectura
Incluido en todos los planes. Ver precios
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
Activa
ACTIVE
Funciona con los permisos que marcaste.Se llega desde Activa cuando: Su persona responsable deja de poder entrar
Sin responsable activo
RESPONSIBLE_INACTIVE
No funciona hasta que se nombra a otra persona.Se llega desde Activa cuando: Integraciones sale del plan
Pausada
PLAN_PAUSED
No funciona, pero se ve y se puede revocar.Se llega desde Activa cuando: Llega su fecha de caducidad
Caducada
EXPIRED
Estado final
No se renueva ni se cambia: hay que crear otra.Se llega desde Activa cuando: Alguien la revoca, o se desactiva o archiva a su responsable
Revocada
REVOKED
Estado final
Deja de valer en el acto y para siempre.
Se llega desde Activa cuando: La renuevas con días de margen
En transición
IN_TRANSITION
Valen la nueva y la anterior hasta la fecha que elegiste.
Otras transiciones
- En transición pasa a Activa: Llega la fecha o se pulsa «Retirar la anterior ya».
- Sin responsable activo pasa a Activa: Se nombra a otra persona responsable.
- Pausada pasa a Activa: Integraciones vuelve al plan.
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
7 días antes
Primer aviso
Hay tiempo para alargarla o para cambiarla.Espera de 6 días hasta el siguiente.
El día antes
Último aviso
El último momento para que no se corte.Espera de 1 día hasta el siguiente.
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, 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
PATCHcon la fecha nueva enexpiresAt, como en 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
Día 0
Renuevas la clave
Ves la nueva una sola vez; la anterior sigue valiendo.Espera de 7 días hasta el siguiente.
Días 0 a 7
Cambias tus servidores
Las respuestas a la anterior llevan X-Utilia-Api-Key-Expires.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
Ponlo en práctica
Lo encontrarás en Claves de API. Para abrirlo, entra con tu cuenta de UTILIA OS.