Clave Virtual de Gateway de IA (Virtual Key)
La clave virtual (Virtual Key) es una credencial emitida por el gateway de IA para acceder a los endpoints proxys del gateway. Entregas la clave virtual a tus aplicaciones y herramientas de IA, mientras que el API Key real del proveedor solo se almacena del lado del gateway. Así, evitas la dispersión de claves reales y, además, puedes gestionar por separado los permisos, límites de velocidad, rotación y revocación de cada clave virtual. En este artículo se explica la gestión completa de su ciclo de vida.
¿Por qué usar una clave virtual?
- Protege tus claves reales — Las apps y herramientas solo manejan la clave virtual, evitando exponer el API Key real del proveedor.
- Permisos segmentados según uso — Puedes crear diferentes claves virtuales para cada proyecto o herramienta, con modelos, canales y límites de velocidad personalizados.
- Revocación en cualquier momento — Si una clave se filtra o deja de usarse, basta con revocarla o rotarla, sin afectar al resto de claves.
Requisitos previos
- Haber iniciado sesión en tu cuenta de ServBay.
- Haber añadido al menos un canal disponible en la página de Canales.
Crear una clave virtual
Accede a Gateway de IA → Claves (Keys) y haz clic en Crear (Create):
- Nombre — Identifica el propósito de la clave (por ejemplo,
claude-code,my-app-dev). - Descripción (opcional) — Información complementaria.
- Fecha de expiración — Puede ser sin límite o una fecha específica.
- Canales permitidos (opcional) — Selección múltiple con etiquetas; la clave solo enrutará hacia los canales especificados. Si está en blanco, no se limita.
- Modelos permitidos (opcional) — Restringe la clave a modelos específicos. Si se deja en blanco, no hay restricción.
- Límite de velocidad (opcional):
- RPM / TPM — Número máximo de solicitudes o tokens por minuto.
- RPD / TPD — Número máximo de solicitudes o tokens por día.
El valor en texto plano solo se muestra una vez
Al crear una clave, el gateway mostrará el valor en texto plano solo una vez (formato servbay-sk-xxxxxxxx...). Cópialo y guárdalo inmediatamente. Al cerrar, solo se guardará el prefijo como referencia y no se podrá visualizar el valor completo otra vez. Si se pierde, la única opción es "rotar" la clave para generar una nueva.
Lista de claves
La lista de claves muestra, para cada clave virtual:
- Prefijo — Por ejemplo,
servbay-sk-abcd..., usado como identificador. - Estado — Activa (active), Revocada (revoked) o Expirada (expired).
- Fecha de creación / Fecha de último uso.
- Etiquetas de permisos — Modelos/canales permitidos y límites de velocidad asignados.
Gestión de claves
Desde la lista de claves, puedes realizar las siguientes acciones en cada clave:
| Acción | Descripción | Efecto |
|---|---|---|
| Editar (Edit) | Modifica nombre, descripción, modelos/canales permitidos y límites de velocidad | Se aplica de inmediato, la clave no cambia |
| Rotar (Renew) | Genera un nuevo valor en texto plano; el anterior queda inválido de inmediato y el nuevo solo se muestra una vez | Debes actualizar todas las apps y herramientas que usan esta clave |
| Revocar (Revoke) | Desactiva la clave de inmediato, pero conserva el registro de auditoría | Irreversible; las solicitudes con esta clave serán rechazadas |
| Eliminar (Delete) | Elimina definitivamente la clave | No se puede recuperar |
Rotación vs Revocación
- Rotar (Renew): la clave sigue existiendo, pero se genera un nuevo valor — ideal cuando sospechas fuga de la clave pero quieres mantener la configuración. Recuerda actualizar a los usuarios.
- Revocar (Revoke): invalida permanentemente la clave pero retiene el registro, útil para auditoría. Es la opción indicada cuando ya no se necesita la clave. Ambas acciones requieren confirmación.
Relación con la "Toma de control con un clic"
Al usar la función de Toma de control con un clic para redirigir una herramienta de IA al gateway, el gateway crea automáticamente una clave virtual dedicada y la configura en la herramienta. También puedes gestionar manualmente estas claves desde la página de claves.
Preguntas frecuentes (FAQ)
- P: ¿Qué hago si olvidé copiar el valor en texto plano de la clave?
- R: No podrás verlo de nuevo. Debes usar la opción "Rotar" para generar uno nuevo y reemplazar el valor anterior en tus aplicaciones.
- P: ¿En qué se diferencia revocación y eliminación?
- R: Revocar conserva el registro de la clave (útil para auditoría), mientras que eliminar la borra por completo. Ambas invalidan la clave instantáneamente.
- P: ¿Qué ocurre si limito los "Modelos permitidos" y la app solicita otro modelo?
- R: El gateway rechazará cualquier petición de modelos fuera de la lista. Asegúrate de que los modelos requeridos estén permitidos, o elimina la restricción.
- P: ¿Qué sucede cuando se alcanza el límite de velocidad?
- R: Las peticiones que excedan los valores de RPM/TPM/RPD/TPD serán limitadas. Puedes revisar el consumo real y ajustar los límites en la página de Estadísticas.
Resumen
Las claves virtuales te permiten conceder acceso a capacidades de IA a tus aplicaciones y herramientas bajo el principio de menor privilegio y con posibilidad de revocación inmediata. Con la configuración de modelos/canales permitidos y límites de velocidad, puedes personalizar permisos para cada caso de uso y rotar o revocar las claves cuando sea necesario, todo sin exponer el API Key real del proveedor.
