Claves virtuales de la puerta de enlace de IA (Virtual Key)
Una clave virtual (Virtual Key) es una credencial emitida por la puerta de enlace de IA para acceder a los endpoints del proxy de la puerta de enlace. Tú distribuyes las claves virtuales a las aplicaciones y herramientas de IA, mientras que la API Key real del proveedor solo se conserva en el lado de la puerta de enlace. Así se evita que la clave real se disperse por todas partes y, además, se pueden limitar permisos, limitar velocidad, rotar y revocar de forma individual cada clave virtual. Este artículo describe la gestión completa del ciclo de vida de las claves virtuales.
Por qué usar claves virtuales
- Protege la clave real — Las aplicaciones y herramientas solo entran en contacto con la clave virtual; la clave real del proveedor no se filtra.
- Permisos detallados según el uso — Puedes crear diferentes claves virtuales para distintos proyectos/herramientas, cada una con sus propios límites de modelos disponibles, canales disponibles y velocidad.
- Se pueden retirar en cualquier momento — Si una clave se filtra o deja de usarse, se revoca o rota directamente, sin afectar a las demás claves.
Requisitos previos
- Haber iniciado sesión en la cuenta de ServBay.
- Haber añadido al menos un canal disponible en la página Canales.
Crear una clave virtual
Ve a la página Puerta de enlace de IA → Claves (Keys) y haz clic en Crear (Create):
- Nombre — Sirve para identificar el uso de la clave (p. ej.,
claude-code,my-app-dev). - Descripción (opcional) — Información adicional.
- Fecha de caducidad — Se puede establecer como sin caducidad o en una fecha concreta.
- Canales permitidos (opcional) — Selección múltiple mediante etiquetas para limitar que esta clave solo se enrute a los canales especificados; si se deja vacío, no hay restricción.
- Modelos permitidos (opcional) — Limita que esta clave solo pueda invocar los modelos especificados; si se deja vacío, no hay restricción.
- Límites de velocidad (opcional):
- RPM / TPM — Límite de solicitudes / tokens por minuto.
- RPD / TPD — Límite de solicitudes / tokens por día.
El texto plano se puede recuperar en cualquier momento
Una vez creada la clave correctamente, la puerta de enlace mostrará la clave en texto plano (con el formato servbay-sk-xxxxxxxx...). La puerta de enlace guarda el texto plano localmente, por lo que después aún se puede recuperar en los detalles de la clave; solo las claves históricas creadas antiguamente mediante hash no tienen texto plano recuperable (al solicitar su recuperación se devuelve 409). Si sospechas que la clave se ha filtrado, usa directamente «Rotar».
Lista de claves
La lista de claves muestra, para cada clave virtual:
- Prefijo — p. ej.,
servbay-sk-abcd..., para identificarla. - Estado — activa (active), revocada (revoked), caducada (expired).
- Fecha de creación / fecha de último uso.
- Etiquetas de permisos — modelos/canales permitidos y límites de velocidad.
Gestionar claves
En la lista de claves, puedes realizar las siguientes operaciones con cada clave:
| Operación | Descripción | Impacto |
|---|---|---|
| Editar (Edit) | Modifica el nombre, la descripción, los modelos/canales permitidos y los límites de velocidad | Surte efecto de inmediato; la clave en sí no cambia |
| Rotar (Renew) | Vuelve a generar el texto plano; el texto plano anterior deja de ser válido de inmediato | Es necesario actualizar todas las aplicaciones y herramientas que usan esta clave |
| Revocar (Revoke) | Desactiva la clave de inmediato, pero conserva el registro de auditoría | No se puede recuperar; las solicitudes con esta clave serán rechazadas |
| Eliminar (Delete) | Elimina la clave por completo | No se puede recuperar |
Rotar vs. revocar
- Rotar (Renew): la clave en sí sigue existiendo, solo cambia su texto plano. Es adecuado cuando sospechas que la clave se ha filtrado pero quieres seguir usando la misma configuración de clave; recuerda actualizar también a quienes la usan.
- Revocar (Revoke): deja la clave permanentemente inválida pero conserva el registro, lo que facilita la auditoría. Es adecuado cuando confirmas que una clave ya no se necesita. Tanto la rotación como la revocación requieren una confirmación adicional.
Relación con la toma de control con un clic
Cuando usas la toma de control con un clic para apuntar una herramienta de IA a la puerta de enlace, esta crea automáticamente una clave virtual exclusiva para esa herramienta y la escribe en la configuración de la herramienta. También puedes gestionar manualmente estas claves creadas automáticamente desde la página de claves.
Preguntas frecuentes (FAQ)
- P: ¿Qué hago si olvidé copiar la clave en texto plano?
- R: Puedes recuperar el texto plano en los detalles de la clave; solo las claves históricas creadas antiguamente mediante hash no se pueden recuperar. En ese caso, usa «Rotar».
- P: ¿Cuál es la diferencia entre revocar y eliminar?
- R: Revocar conserva el registro de la clave (útil para auditoría), mientras que eliminar la borra por completo. Ambas acciones invalidan la clave de inmediato.
- P: Después de limitar los «modelos permitidos», ¿qué pasa si la aplicación solicita otros modelos?
- R: La puerta de enlace rechazará las solicitudes de modelos fuera de los permisos de esa clave. Asegúrate de que los modelos que usa la aplicación estén en la lista de permitidos, o elimina la restricción.
- P: ¿Qué pasa si se alcanza el límite de velocidad?
- R: Las solicitudes que superen RPM/TPM/RPD/TPD serán limitadas por la puerta de enlace. Puedes consultar el uso real en la página de Estadísticas y ajustar los límites superiores.
Resumen
Las claves virtuales te permiten distribuir capacidades de IA a aplicaciones y herramientas con privilegios mínimos y de forma revocable. Junto con las restricciones de modelos/canales permitidos y los límites de velocidad, puedes crear credenciales a medida para cada caso de uso y rotarlas o revocarlas en cualquier momento cuando sea necesario, sin tocar la API Key real del proveedor.
