Lo que harás
- Rotar una clave sin tiempo de inactividad: emite primero la clave de reemplazo y revoca la antigua solo después de confirmar que la nueva está activa.
- Revocar de inmediato una clave filtrada: la propagación a todas las regiones tarda como máximo 60 segundos.
- Almacenar claves en variables de entorno o en un gestor de secretos, nunca en el código, y rotarlas cuando un miembro del equipo con acceso abandona el proyecto.
Las claves de API son tokens de portador de larga duración, por lo que rotarlas periódicamente —y revocarlas de inmediato cuando se filtran— es algo que vale la pena hacer correctamente. Este artículo explica ambos casos.
Rotar una clave sin tiempo de inactividad#
La rotación consiste en emitir una nueva clave antes de retirar la antigua, para que no haya un intervalo en el que su integración no esté autenticada.
- Vaya a Settings → API keys y haga clic en Generate key.
- Asigne a la nueva clave un nombre que aclare su propósito (por ejemplo,
production-v2). - Elija el mismo rol que la clave que está reemplazando.
- Copie el token; se muestra solo una vez.
- Actualice su variable de entorno o gestor de secretos con el nuevo token y realice el despliegue.
- Una vez que la nueva clave esté activa y se confirme que funciona (consulte la columna Last used; debería cambiar en cuestión de minutos), regrese a Settings → API keys y haga clic en Revoke en la clave antigua.
Mantenga la clave antigua activa hasta que esté seguro de que la nueva funciona. Si la revoca demasiado pronto y el despliegue no se ha propagado, el tráfico recibirá errores 401.
Revocar una clave filtrada inmediatamente#
Si una clave queda expuesta —se sube a un repositorio público, se filtra en los registros, se incluye en un paquete del lado del cliente— revóquela primero e investigue después.
- Settings → API keys, busque la clave por su nombre o prefijo (el prefijo es visible en la tabla aunque el token completo no lo sea).
- Haga clic en Revoke. La revocación se propaga a todas las regiones en 60 segundos.
- Emita una clave de reemplazo y actualice sus secretos.
- Verifique la marca de tiempo Last used en la clave revocada para estimar cuánto tiempo estuvo expuesta y si necesita realizar una auditoría de actividad inesperada.
Las claves revocadas se guardan en la tabla con una etiqueta revoked para que tenga un registro. No se pueden reactivar.
Actualizar secretos de forma segura#
El patrón estándar es almacenar las claves en variables de entorno, no en el código:
# .env.local (never committed)
ELIDO_API_KEY=elido_live_xxx...
import { ElidoClient } from "@elido/sdk";
const client = new ElidoClient({ apiKey: process.env.ELIDO_API_KEY! });
Para los flujos de trabajo de CI, utilice el almacén de secretos de su plataforma (GitHub Actions secrets, GitLab CI variables, etc.) y rote las claves cada vez que un miembro con acceso deje el equipo.
Qué sucede con las integraciones activas#
Cuando revoca una clave, cualquier solicitud en curso que ya haya enviado el token se completará; validamos al inicio de la solicitud, no a mitad de la respuesta. Las solicitudes que comiencen después de la revocación devolverán 401 Unauthorized. Los SDKs no reintentan tras un 401 (eso causaría un bucle), por lo que su integración comenzará a fallar de inmediato.
Planifique una breve ventana de superposición: mantenga viva la clave antigua hasta que haya confirmado que la nueva está activa en producción.
Solución de problemas#
401 en una clave que acabo de crear. El token que se muestra al momento de la creación es la clave completa, incluido el sufijo secreto. Si copió solo el prefijo de la tabla (por ejemplo, elido_abc123), no funcionará; el prefijo es solo para visualización. Emita una nueva clave y copie el token completo.
El botón Revoke no aparece. Probablemente la clave ya esté revocada. Las claves revocadas muestran una etiqueta revoked y ningún botón de acción. Verifique que esté mirando el espacio de trabajo correcto: las claves tienen alcance de workspace.
Ventana de propagación de 60 segundos. Si revocó una clave y las solicitudes aún tienen éxito por un momento, es lo esperado. Nuestros nodos de borde sincronizan la revocación a través de Redis pub/sub; el retraso en el peor de los casos es de ~60 segundos.
La clave desapareció de la lista. Mantenemos las claves revocadas en la tabla indefinidamente para fines de auditoría. Si no puede encontrarla, verifique que no haya filtrado la lista: no hay un filtro de "solo activas" por defecto, pero una búsqueda de texto en el campo de nombre ocultará las filas que no coincidan.