ACL y el principio de mínimo privilegio
En esta página
El principio de mínimo privilegio aplicado a las API
El principio de mínimo privilegio es uno de los conceptos más antiguos en ciberseguridad: cada componente de un sistema debe tener acceso únicamente a los recursos estrictamente necesarios para su funcionamiento. La idea resulta intuitiva si la trasladas al mundo físico: no le entregas la llave maestra del edificio a la persona que riega las plantas del vestíbulo. Aplicado a las claves de API de xAI, esto significa que cada clave debe limitarse exclusivamente a los endpoints y modelos que la aplicación que la porta necesita realmente. Si esta clave llega a filtrarse, el atacante heredará sus permisos: una clave restringida al chat con un único modelo causa infinitamente menos daños que una clave que abre todo el catálogo.
xAI implementa este principio mediante un sistema granular de listas de control de acceso (ACL), que detallaremos a continuación.
El sistema de ACL de xAI
Las ACL siguen el formato api-key:{type}:{value}. Dos tipos te afectan en el día a día: api-key:endpoint:{endpoint} restringe los endpoints accesibles, y api-key:model:{model_id} restringe los modelos utilizables. Existe también un comodín, api-key:endpoint:*, que otorga acceso a todos los endpoints; resulta cómodo para el desarrollo, pero está prohibido en producción, precisamente porque anula el beneficio del mínimo privilegio.
Los endpoints que puedes autorizar individualmente son: chat (finalización de chat, con diferencia el más común), embed (generación de incrustaciones), image (generación y edición de imágenes), models (consulta de la lista de modelos), tokenize (tokenización de texto), documents (gestión de documentos) y sample (muestreo).
Veamos cómo se traduce esto en un ejemplo real. Imagina un chatbot de atención al cliente que utiliza únicamente el modelo grok-4.3 en modo chat. Su clave ideal tendría este aspecto:
{
"name": "support-chatbot-prod",
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.3"
],
"qps": 5,
"qpm": 100,
"tpm": 500000,
"expireTime": "2026-12-31T23:59:59Z"
}
Lee esta configuración como un contrato: la clave solo puede acceder al endpoint de chat; sin imágenes, sin incrustaciones, por lo que no es posible un uso indebido para esos fines. Solo puede usar grok-4.3, lo que evita llamadas accidentales (o malintencionadas) a modelos más costosos. Está limitada a 5 solicitudes por segundo y 100 por minuto, y caducará en una fecha conocida. Si algún desarrollador del proyecto intenta añadir generación de imágenes sin avisar a nadie, la API lo rechazará: la restricción técnica hace cumplir la decisión arquitectónica.
Límites de tasa: una capa de seguridad adicional
Las ACL responden a la pregunta «qué», mientras que los límites de tasa responden a «cuánto». QPS (Queries Per Second) limita las solicitudes por segundo: es tu salvaguarda contra picos accidentales, como un bucle infinito introducido por una refactorización un viernes por la noche o un ataque DDoS que rebote en tu aplicación. QPM (Queries Per Minute) suaviza el tráfico durante un periodo más largo y detecta abusos que pasarían desapercibidos bajo el radar del QPS. TPM (Tokens Per Minute), finalmente, limita el volumen de tokens consumidos: protege contra solicitudes individuales muy largas, como un usuario que pega un documento de 200 páginas en tu chatbot, que agotarían tu presupuesto en minutos sin superar jamás el número autorizado de solicitudes.
Una estrategia de claves por entorno
En la práctica, no configuras una única clave, sino una familia de claves, y cada entorno tiene su propia lógica. En desarrollo, inviertes la lógica de producción: acceso amplio, límites estrictos.
{
"name": "dev-team-alpha",
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 2,
"qpm": 30,
"tpm": 100000,
"expireTime": "2026-06-30T23:59:59Z"
}
Los desarrolladores pueden explorarlo todo, pero los límites bajos evitan sorpresas en la facturación si una prueba sale mal. En staging, por el contrario, replicas exactamente las ACL de producción (api-key:endpoint:chat, api-key:model:grok-4.3, QPS 5, QPM 100, TPM 500000): esta es la única forma de detectar un problema de permisos con antelación; si el código de staging intenta una llamada que producción rechazará, es mejor descubrirlo ahora que en la primera hora de la puesta en marcha. La clave de producción, sin embargo, combina los permisos estrictos de staging con límites dimensionados para el tráfico real (por ejemplo, QPS 20, QPM 600, TPM 2000000) y una caducidad programada: "expireTime": "2027-03-31T23:59:59Z" en una clave llamada prod-chatbot-v2.
Verificar y auditar permisos
Para ver qué tiene permitido hacer realmente una clave activa, consulta la API con la propia clave:
curl https://api.x.ai/v1/api-key \
-H "Authorization: Bearer $XAI_API_KEY"
La respuesta enumera las ACL efectivas, los estados api_key_blocked y api_key_disabled, una versión enmascarada de la clave (redacted_api_key) y el team_id. Adquiere el hábito de comparar regularmente estas ACL con las necesidades reales de la aplicación: los permisos tienden a acumularse con el tiempo, nunca se reducen espontáneamente. Por el lado de los modelos, el endpoint GET /auth/teams/{teamId}/models devuelve la lista de modelos disponibles para tu equipo con sus precios; información valiosa para definir ACL de modelos relevantes y descartar modelos costosos que no utilizas.
Para consolidar todo esto, realiza una auditoría completa de tus claves. Enumera las claves activas de cada equipo y consulta cada una: ¿son sus ACL mínimas, sin comodines en producción? ¿Son razonables sus límites de tasa? ¿Tiene fijada su fecha de caducidad? ¿Identifica su nombre la aplicación y el entorno? «prod-chatbot-v2» cuenta una historia, «key-test-2» no cuenta ninguna. Elimina las claves huérfanas y documenta el resultado: este documento servirá de punto de partida para la siguiente auditoría y verás de un vistazo qué ha variado mientras tanto.
Puntos clave
- Cada clave debe tener ACL restrictivas: solo los endpoints y modelos necesarios.
- Nunca uses un comodín
*en producción. - Combina las ACL con límites de tasa (QPS, QPM, TPM) adaptados al uso real.
- Crea claves distintas por entorno (dev, staging, prod) y por aplicación; staging con las mismas ACL que prod.
- Audita regularmente los permisos de tus claves activas mediante
GET /v1/api-key.