Rotación
Rotar es cambiar el secreto sin cambiar la integración. La API genera una clave nueva con la misma configuración y deja la antigua respondiendo por un tiempo, para que usted cambie el secreto en sus sistemas sin tumbar nada.
Cuándo rotar
Sección titulada «Cuándo rotar»- Cuando alguien que tenía acceso a la clave sale del equipo o del proveedor.
- Cuando la clave pasó por un lugar que usted no controla: un ticket, una conversación, un registro, una captura de pantalla, una máquina prestada.
- Cuando usted cambia de servidor, de proveedor o de herramienta de despliegue.
- En un intervalo regular, si quiere esa rutina.
No existe un plazo obligatorio acá, y la API no fuerza ninguno. Si quiere una rutina fácil de mantener, elija un plazo de vencimiento al crear la clave (30 días, 90 días o 1 año) y trate la fecha como el recordatorio de rotar.
Si sospecha que la clave se filtró, el camino no es la convivencia: es detener la clave antigua en el acto. Vea Buenas prácticas de clave.
Qué copia la rotación
Sección titulada «Qué copia la rotación»Copia de la clave antigua: el nombre, los permisos, el miembro representado, la lista de IPs y la fecha de vencimiento.
No copia: el secreto, que es nuevo; el registro de uso; las claves de idempotencia.
El registro de uso queda con la clave que hizo cada llamada. La clave nueva empieza con la lista vacía en Ver uso, y el historial de la antigua sigue en la antigua.
La convivencia
Sección titulada «La convivencia»En el panel: menú de la clave, Rotar. El formulario pide su contraseña, y solo el OWNER y el ADMIN rotan. Usted elige por cuánto tiempo la clave antigua sigue valiendo.
| Elección | Qué pasa con la clave antigua |
|---|---|
| Detener ahora | Revocada en la misma acción. La llamada siguiente con ella recibe 401 |
| 1 hora | Sigue respondiendo por 1 hora y se detiene sola al final |
| 24 horas | Sigue respondiendo por 24 horas y se detiene sola al final |
Durante la convivencia las dos claves responden, y la antigua queda con el estado En rotación en el panel. Usted no necesita esperar a que termine el período: revoque la antigua apenas confirme el cambio.
Los endpoints de webhook suscritos con la clave antigua siguen la rotación: con 1 hora o 24 horas, pasan a la clave nueva en la misma acción y siguen recibiendo; con Detener ahora, se pausan, y el dueño y los administradores reciben por correo la lista para revisar, porque quien obtuvo la clave pudo haber registrado un endpoint. En el panel, el endpoint pausado muestra el motivo “Pausado por seguridad” (en la API, disabled_reason: "emergency_key_rotation"), y volver a activarlo pide su contraseña. Vea Webhooks.
Paso a paso
Sección titulada «Paso a paso»- Rote eligiendo el período de convivencia.
- Copie la clave nueva. Ella también se muestra una sola vez.
- Cambie el secreto en sus sistemas.
- Confirme con una llamada a
GET /public/v1/meusando la clave nueva y compare elkey.prefixde la respuesta con el prefijo que el panel muestra en la clave nueva. Así usted sabe que su sistema está usando la clave nueva, y no la antigua que quedó en algún caché. - Revoque la antigua.
Las trampas
Sección titulada «Las trampas»La clave nueva hereda la fecha de vencimiento de la antigua. Rotar una clave que vence la semana que viene devuelve una clave que también vence la semana que viene. La rotación cambia el secreto, no renueva el plazo. Para ganar plazo, cree una clave nueva.
La clave nueva ocupa un lugar en la cuota mientras la antigua no muere. La cuota de claves del plan cuenta toda clave que todavía autentica, y la antigua en convivencia todavía autentica. La rotación en sí no se bloquea por la cuota, pero crear una clave más sí, hasta que la antigua sea revocada o venza. Si la empresa ya está en el tope, elija Detener ahora o revoque la antigua apenas cambie el secreto.
La idempotencia no atraviesa la rotación. La clave de idempotencia vale por clave de API. La misma Idempotency-Key enviada con la clave nueva es una solicitud nueva, y no la repetición de la anterior: si la primera ya había creado un registro, la segunda crea otro. Termine con la clave antigua lo que esté en curso, o espere la respuesta antes de cambiar el secreto. Vea Idempotencia.
Una clave ya rotada no se rota de nuevo. Quien rota dos veces rota la clave nueva. Una clave revocada o vencida tampoco se rota: ahí el camino es crear una clave nueva.
Una fecha de vencimiento anterior al final de la convivencia le gana a la convivencia. Si la clave antigua ya vencía en 6 horas y usted eligió 24 horas, se detiene en 6 horas.
Una clave de un miembro suspendido no se rota. Reactive al miembro o cree una clave para otro miembro.
Quien quedó atrás
Sección titulada «Quien quedó atrás»Después de que la clave antigua se detiene, la llamada hecha con ella recibe el mismo 401 de clave inválida, sin decir que el motivo fue la rotación.
Quien lo dice es el panel: el intento aparece en Ver uso de la clave antigua, con la dirección desde donde vino y el horario. Así usted encuentra el sistema que se quedó con el secreto viejo.
El OWNER y el ADMIN reciben un correo en cada rotación y en cada revocación.
Próximo paso
Sección titulada «Próximo paso»- Buenas prácticas de clave: qué hacer si la clave se filtró.
- IPs permitidas: la clave nueva nace con la misma lista.
- Idempotencia: por qué la repetición no atraviesa la rotación.