Integraciones y entrada de documentos Útil

Rotar o revocar una clave de API

1:45 Tutorial 3.13

Rotar crea una clave nueva y deja la anterior activa durante 7 días. Revocar apaga la clave en el acto. Son las dos formas de retirar un secreto.

Antes de empezar

  • Rol de titular o administrador del equipo. El resto de miembros no ve el submenú de API ni puede rotar o revocar claves.
  • Una clave activa. Una clave caducada no se puede rotar; una revocada no admite ninguna acción.
  • Para rotar, un integrador que pueda sustituir la clave en su sistema durante el plazo de solape.

Paso 1. Localizar la clave

En el menú lateral, Integraciones > API y desarrolladores > Claves de API. En la ficha de la clave, al pie, están Rotar (1) y Revocar (2).

Ficha de una clave con los botones Permisos, Clientes, Rotar (1) y Revocar (2) al pie.
Nota. Sin permiso de gestión, el pie de la ficha indica que solo el titular o un administrador del equipo puede cambiar, rotar o revocar la clave.

Paso 2. Rotar la clave

  1. Pulsar Rotar (1).
  2. En el diálogo Rotar la clave «{nombre}», pulsar Sí, rotar (2).
Diálogo Rotar la clave con el texto de las consecuencias (1) y el botón Sí, rotar (2).
Importante. La clave nueva hereda los clientes y los permisos que incluye el plan; los avisos por webhook pasan a ella. La anterior sigue funcionando 7 días.
Nota. Si la clave anterior ya tenía una fecha de caducidad más próxima, se respeta: nunca se alarga su vida al rotar.

Paso 3. Copiar la clave nueva

  1. Aparece el aviso «Clave rotada. …» y el recuadro Copiar ahora con la clave completa.
  2. Pulsar Copiar y guardarla en el lugar acordado con el integrador.
  3. Entregar la clave al integrador antes de la fecha en que se apaga la anterior.
Importante. La clave solo se muestra una vez. Si se pierde, no se recupera: hay que rotar de nuevo o crear otra.
Nota. La clave anterior pasa a llamarse «{nombre} (sustituida)». La nueva conserva el nombre, el techo de clientes, la declaración de uso y la lista de direcciones IP.

Paso 4. Comprobar cuándo se apaga la anterior

En Integraciones > API y desarrolladores > Consumo, la tabla Claves que se van a apagar indica la fecha en la columna Se apaga el y el motivo «Sustituida al rotar».

Atención. Llegada esa fecha, la clave anterior deja de funcionar. Si el integrador no ha desplegado la nueva, la integración se interrumpe.

Paso 5. Revocar la clave

  1. Pulsar Revocar (1) en la ficha de la clave.
  2. En el diálogo Revocar la clave «{nombre}», pulsar Sí, revocar (2).
Diálogo Revocar la clave con el aviso de efecto inmediato (1) y el botón Sí, revocar (2).
Atención. La integración deja de funcionar en el acto y la acción no se deshace. Se revoca la autorización registrada de cada cliente y se apagan los destinos de avisos de la clave.
Nota. La ficha pasa a Revocada. Las llamadas que hizo la clave siguen en Registro de llamadas. Una clave revocada deja de ocupar plaza en el plan.

Resultado

Con la rotación, la integración se mantiene con la clave nueva mientras la anterior se apaga sola. Con la revocación, la clave queda en el listado como Revocada, sin acceso y con su rastro en el registro.

Problemas frecuentes

«La clave «{nombre}» caducó el {fecha} y ya no se puede rotar. Crear una clave nueva para esa integración.»
Una clave caducada no se rota. Crear otra desde Crear clave con los mismos permisos y clientes.
La ficha no muestra el botón Rotar.
La clave está caducada o revocada. En una clave activa, el botón solo se pinta al titular y a los administradores.
«Solo quien lleva la cuenta puede crear o revocar claves de API. …»
Error de acceso 403. La acción corresponde al titular o a un administrador del equipo.
«Esta clave ya estaba revocada desde el {fecha}.»
La revocación ya se había hecho. La fecha original no cambia.
Tras rotar, el aviso indica que el plan no incluye un permiso y no se ha pasado a la clave nueva.
El plan actual ya no concede ese permiso. Añadirlo desde Permisos si el plan vuelve a incluirlo.
La integración falla pasada la fecha de apagado.
Sigue usando la clave anterior. Entregar la clave nueva al integrador o rotar de nuevo.

Continuar con

Consejo
Rotar las claves con una periodicidad fija, y siempre que cambie la persona que las gestiona, evita tener que revocar con la integración en marcha.
Anterior Reintentar ficheros que no se han procesado Siguiente Probar la API en el sandbox

Prueba CopilotGestoria gratis

30 días gratis. Sube tu primera factura en 2 minutos.

Crear cuenta gratis