Skip to main content

Prácticas recomendadas para prevenir fugas de claves de API

Prevenga las fugas de claves de API desde tres niveles: acortar el tiempo de exposición de las credenciales, reducir el alcance de los permisos y configurar alertas y mitigación de pérdidas; cubre claves de API temporales, rotación periódica, lista blanca de IP, conexiones privadas, alertas de presupuesto y alertas de monitoreo de modelos.

Descripción general

Una clave de API es la credencial utilizada para llamar a los servicios de modelos de Alibaba Cloud Model Studio. Una vez filtrada, cualquier persona que la obtenga puede llamar a los modelos dentro del alcance de autorización de la clave y consumir la cuota. El impacto de una fuga puede descomponerse en cuatro factores: probabilidad de fuga, tiempo de exposición, alcance de permisos por llamada y duración de la anomalía. La probabilidad de fuga se reduce con las prácticas fundamentales que recorren todo el documento, y los otros tres factores se reducen con los tres niveles siguientes:

Nivel

Factor que reduce

Medidas clave

Acortar el tiempo de exposición

Tiempo de exposición

Claves de API temporales para el cliente, visualización única con almacenamiento controlado, rotación periódica y revocación al abandonar el puesto

Reducir el alcance de los permisos

Alcance de permisos por llamada

Una clave por negocio, aislamiento por espacio de trabajo, lista blanca de IP y alcance de modelos, conexión privada

Alertas y mitigación de pérdidas

Duración de la anomalía

Alertas de presupuesto con detención al alcanzar el presupuesto, alertas de monitoreo de modelos, detección de riesgos de la plataforma

Prácticas fundamentales que se aplican a lo largo de los tres niveles:
  • Las aplicaciones leen las credenciales desde variables de entorno o un servicio de gestión de claves en lugar de escribirlas directamente en el código; configure el análisis de información confidencial en CI/CD (con herramientas de análisis de credenciales como gitleaks), cubriendo los patrones de claves de API.
  • Mantenga un registro de claves: comience con una tabla básica con el ID de la clave, el propósito, el responsable y la fecha de la última rotación, y añada gradualmente región, espacio de trabajo, alcance de permisos y presupuesto; el registro nunca debe contener claves completas.
  • Restrinja los permisos de gestión de claves (crear, ver, editar, eliminar) a los administradores que los necesiten.

Acortar el tiempo de exposición de las credenciales

Guarde de forma segura las claves de API permanentes

Una clave de API recién creada se muestra completa una sola vez en el momento de la creación; tras cerrar el cuadro de diálogo, ya no se puede ver ni copiar el texto completo. Si no la guardó, solo puede restablecerla o volver a crearla; consulte Obtener una clave de API. Tras crearla, guarde la clave completa directamente en un almacén de credenciales controlado (un servicio de gestión de claves o la gestión de secretos de su plataforma de despliegue), sin transmitirla por capturas de pantalla, correos electrónicos, herramientas de chat o documentos ordinarios; el valor enmascarado de la lista solo sirve para identificación y comparación. No coloque las claves de API permanentes en las siguientes ubicaciones:
  • Scripts de navegador, artefactos de compilación del frontend y paquetes de instalación de aplicaciones móviles
  • Repositorios de código públicos o compartidos (añadir .gitignore no elimina por sí solo las credenciales de los commits históricos)
  • Salidas de Notebooks y código de ejemplo
  • Capturas de pantalla y grabaciones
  • Tickets, chats de grupo y documentos en línea
  • Prompts, bases de conocimiento y contextos de agentes
  • URL de solicitud y parámetros de consulta
  • Registros de acceso y trazas de excepciones
  • Complementos de terceros y servicios de retransmisión de modelos
  • Entornos compartidos y archivos de configuración, imágenes y copias de seguridad expuestos al exterior
Para la depuración local, se recomienda configurar la variable de entorno mediante una entrada oculta para evitar que el texto sin cifrar quede en el historial de comandos:
read -r -s -p "Enter API key: " DASHSCOPE_API_KEY
printf '\n'
export DASHSCOPE_API_KEY
Este ejemplo se aplica a entornos Linux/macOS.
Las variables de entorno evitan la escritura directa en el código, pero no son un almacenamiento cifrado: las credenciales aún pueden filtrarse a través de diagnósticos de procesos, configuraciones de contenedores, volcados de memoria o exportaciones de operaciones; durante la depuración, evite opciones como set -x que muestran variables confidenciales. En producción, utilice un servicio de gestión de claves o la inyección de secretos de su plataforma de despliegue.
Si ha entregado una clave de API a un servicio de retransmisión de modelos no confiable o a un complemento de terceros, deje de entregarle claves nuevas, cambie a la API oficial o a una integración del lado del servidor de confianza, y rote las claves ya entregadas.

Utilice claves de API temporales en escenarios de cliente

Los navegadores, las aplicaciones móviles y los mini programas no pueden mantener las credenciales de forma confidencial de manera fiable. En estos escenarios, haga que un backend autenticado emita claves de API temporales para que el frontend llame directamente:
  1. Conserve la clave de API permanente únicamente en su propio servidor y no la entregue nunca a ningún cliente.
  2. Cuando el frontend necesite llamar a un modelo, solicite primero una clave temporal a su backend.
  3. El backend llama a la API de generación de claves de API temporales y devuelve al frontend una clave de corta duración con prefijo st-.
  4. El frontend llama a Model Studio directamente con la clave st-.
Una clave de API temporal es válida durante 60 segundos de forma predeterminada; puede establecer entre 1 y 1800 segundos mediante expire_in_seconds (configure la duración más corta que la tarea necesite y no utilice el máximo de forma incondicional). Caduca automáticamente y no se puede eliminar por adelantado; hereda todos los permisos de la clave de API permanente que la emitió, por lo que, si necesita menos permisos, reduzca primero el alcance de la clave permanente utilizada para emitirla. La API de emisión se llama a través de OpenAPI con la clave permanente; valide los permisos del llamador y limite la frecuencia de emisión para evitar convertirla en un dispensador público de credenciales. Para más detalles de la API, consulte Generar una clave de API temporal.

Rotación periódica y revocación al abandonar el puesto

Las claves de larga duración configuradas en código o en agentes acumulan exposición con el tiempo y deben rotarse periódicamente:
  1. Cree una clave nueva y vuelva a configurar sus permisos y presupuesto según las necesidades actuales.
  2. Actualice las referencias de credenciales en los servicios de su negocio.
  3. Verifique que la clave nueva funciona correctamente.
  4. Elimine la clave antigua y confirme que ya no puede iniciar llamadas.
  5. Actualice el registro de claves.
Una clave nueva no hereda automáticamente los permisos ni el presupuesto de la antigua; debe volver a configurarlos. Cuando el personal abandone la empresa o se retire un negocio, debe inventariar, eliminar o rotar por separado las claves a su nombre: las claves de API creadas el 25 de marzo de 2026 o con posterioridad no se eliminan en cascada al eliminar el usuario RAM al que pertenecen y siguen siendo utilizables (relevante solo cuando la clave pertenece a una subcuenta RAM), por lo que no puede dar por revocadas las credenciales solo porque el usuario RAM se haya eliminado; consulte Validez de las claves de API. Si varias claves se guardan en un mismo servidor posiblemente comprometido, configuración pública, repositorio de código o entorno de terceros, rote todas las credenciales posiblemente afectadas y corrija el entorno: ni sustituya todas las claves de forma indiscriminada ni gestione solo una clave ignorando la exposición compartida del entorno. Práctica avanzada: aloje el texto sin cifrar de las claves en un servicio de gestión de claves (KMS), deje que las aplicaciones lo recuperen por nombre de credencial y utilice la rotación de claves de KMS para actualizarlo periódicamente.

Reducir el alcance de los permisos de las credenciales

Una clave por negocio y aislamiento por espacio de trabajo

Asigne claves de API independientes a las distintas aplicaciones y entornos (producción, pruebas y depuración personal): esto reduce el impacto de la fuga de una sola clave y facilita la localización de problemas y la rotación de cada clave por separado. Cuando necesite aislamiento de permisos, control de acceso a modelos detallado o contabilidad de costos independiente, asigne al negocio un espacio de trabajo no predeterminado (un espacio de trabajo es un contenedor de Model Studio que aísla permisos y costos; toda cuenta tiene por defecto un espacio de trabajo predeterminado); el alcance básico de llamadas de una clave está limitado por el espacio de trabajo al que pertenece. Consulte Gestión de permisos. Asimismo, restrinja los permisos de gestión de claves a los administradores imprescindibles; las cuentas que pueden iniciar sesión en la consola para gestionar credenciales deben seguir el principio de mínimo privilegio y activar la autenticación multifactor conforme a lo que exija su organización.

Configurar la lista blanca de IP y el alcance de modelos

Tras establecer el permiso de una clave de API en Personalizado en el panel de creación o edición de la clave, puede reducir aún más su alcance de llamadas:
  • Lista blanca de IP: permita únicamente las IP o segmentos de salida públicos que el negocio utilice realmente, con un máximo de 20 (puede consultar la IP de salida pública con un servicio como curl ifconfig.me). De forma predeterminada se permiten todas las direcciones IPv4; crear una clave no equivale a tener las restricciones de origen activadas. Al llamar a través de NAT, un proxy o una pasarela, introduzca la dirección de salida pública que Model Studio ve realmente, no la dirección interna del servidor.
  • Alcance de modelos accesibles: una vez activado, la clave solo puede llamar a los modelos seleccionados (como máximo 30, limitado por los modelos autorizados en el espacio de trabajo), evitando que una clave filtrada se utilice con modelos de alto costo.
Tras la configuración, se recomienda verificar que la reducción del alcance surte efecto: solo las redes y modelos permitidos pueden ser llamados y los no autorizados no; no muestre la clave completa durante la verificación. Para el punto de entrada y las reglas completas, consulte Cómo gestionar los permisos de las claves de API.
La lista blanca de IP no sustituye a la confidencialidad de las credenciales: las personas o hosts comprometidos que puedan iniciar llamadas desde la misma red de salida pueden seguir haciendo un uso indebido de una clave filtrada.

Llamar a través de una conexión privada

Para escenarios con altos requisitos de seguridad de red, puede establecer una conexión privada (PrivateLink) entre su VPC y Model Studio: las llamadas no pasan por la red pública, por lo que los atacantes externos cuyas redes no estén conectadas no pueden llamar al servicio aunque la clave se filtre. Para el método de configuración, consulte Acceder a las API de Model Studio a través de una red privada.

Configurar alertas y mitigación de pérdidas

Alertas de presupuesto y detención al alcanzar el presupuesto

Configure presupuestos mensuales y umbrales de alerta para la cuenta, un espacio de trabajo o una clave de API concreta; priorice presupuestos independientes para las claves de alto riesgo, como las de desarrollo, pruebas, demostraciones e integraciones de terceros. Cuando el gasto alcanza el umbral y cuando el presupuesto se agota, se envían notificaciones mediante mensajes internos, SMS, correo electrónico o bots; tras activar "detener inmediatamente al alcanzar el presupuesto", el presupuesto agotado restringe las llamadas de pago por uso de esa dimensión y devuelve 429. Para el método de configuración, consulte Gestión de presupuestos.
La detención al alcanzar el presupuesto tarda en surtir efecto y los cargos generados durante el retraso se siguen facturando; el desbordamiento del rendimiento aprovisionado (PTU) y las llamadas generadas por las aplicaciones aún no admiten la detención automática. Para los negocios críticos en producción, no se recomienda activar la detención automática; priorice las alertas junto con una gestión controlada.

Alertas de monitoreo de modelos

El monitoreo de modelos agrega por espacio de trabajo el número de llamadas, el uso de tokens, el número de fallos, la tasa de fallos y otras métricas, admite el filtrado por clave de API y permite crear reglas de alerta a partir de plantillas de alerta predefinidas o personalizadas que notifican a contactos o grupos de contacto. Se recomienda configurar para las claves de alto riesgo alertas de picos de volumen o de número de llamadas: las anomalías son visibles en cuestión de minutos después de producirse las llamadas, y un disparo fuera del horario laboral exige intervención manual. La primera configuración de alertas requiere autorizar previamente el rol de servicio de Cloud Monitor en la entrega de datos; para el método de configuración, consulte Alertas.

Detección de riesgos de la plataforma

La plataforma analiza periódicamente entornos públicos como los repositorios de código públicos para identificar claves de API filtradas y notificarlo de forma proactiva; los canales concretos dependen de lo que esté realmente activado (pueden incluir SMS, correo electrónico, mensajes internos, etc.). Asimismo, identifica comportamientos anómalos como inicios de sesión desde IP poco habituales, picos de tráfico nocturnos o aumentos bruscos de los costos. La detección de riesgos de la plataforma y sus alertas son una capacidad de detección de anomalías y aviso preventivo que la plataforma ofrece de forma proactiva para mejorar la experiencia de uso; no está incluida en el alcance de los servicios acordado en el SLA; debido a la complejidad de los escenarios de riesgo, no se garantiza una cobertura absoluta de las alertas, y tanto la identificación como la entrega de las alertas pueden presentar retrasos. La custodia segura y el uso conforme de credenciales como las claves de API corresponden a su ámbito de responsabilidad; tome como línea de defensa principal las alertas de presupuesto configuradas por usted, las alertas de monitoreo de modelos y la rotación periódica; no recibir alertas de la plataforma no significa que no exista riesgo de fuga. Al detectar una fuga sospechosa o recibir una alerta, localice y gestione el problema siguiendo Investigación de fugas de claves de API.

Lista de comprobación antes del lanzamiento

Los desarrolladores individuales o los equipos pequeños pueden empezar con lo mínimo: configurar un presupuesto con notificaciones de alerta para la clave, mantener la credencial solo en variables de entorno y rotarla periódicamente. La lista de comprobación completa es la siguiente:
  • Producción, pruebas e integraciones de terceros no comparten la misma clave de API; el responsable y el propósito de cada clave están claros.
  • Se han verificado la región, el espacio de trabajo, el alcance de modelos y las IP de salida de las solicitudes a las que pertenece la clave, con permisos que cubren solo el alcance necesario.
  • Las claves permanentes se guardan solo en backends controlados y nunca entran en clientes, código fuente, prompts, documentos compartidos ni registros.
  • Las claves no se han entregado a servicios de retransmisión de terceros no confiables ni a entornos de complementos; si se entregaron, se ha detenido la entrega y se han rotado.
  • Las credenciales se inyectan mediante variables de entorno o secretos; los archivos confidenciales y los artefactos de compilación no contienen texto sin cifrar.
  • Los escenarios de conexión directa desde el cliente utilizan claves de corta duración emitidas por un backend autenticado, y la clave permanente utilizada para emitirlas tiene el alcance de permisos reducido.
  • Las claves nuevas se han guardado de forma controlada; se han verificado las claves antiguas, las claves inactivas y las claves del personal que ha abandonado la empresa.
  • Se han configurado presupuestos y alertas a nivel de cuenta, espacio de trabajo y clave, con canales de notificación y responsables claros.
  • Se han evaluado el impacto en la disponibilidad y el retraso de efectividad de la detención al alcanzar el presupuesto.
  • Los procedimientos de rotación y de respuesta a fugas están definidos; los pasos de investigación se describen en Investigación de fugas de claves de API.

Preguntas frecuentes

No. Una clave de API temporal hereda todos los permisos de la clave de API permanente que la emitió; solo su periodo de validez es más corto. Para tener menos permisos, reduzca primero la clave de API permanente utilizada para emitirla.
Sí. La lista blanca de IP solo restringe la red de origen de las llamadas; una clave filtrada dentro de la misma red de salida puede seguir utilizándose de forma indebida. Combínela con el principio de mínimo privilegio, las alertas de presupuesto y la rotación periódica.
Deje de entregar claves nuevas a ese servicio, rote las claves ya entregadas y cambie a la API oficial o a una integración del lado del servidor de confianza. Para los pasos de gestión de las claves filtradas, consulte Investigación de fugas de claves de API.