El control de acceso basado en roles (RBAC) te permite decidir quién puede hacer qué en tu organización y tus proyectos, tanto a través de la API como en el panel. Los mismos permisos rigen ambos entornos: si alguien puede llamar a un punto de acceso (por ejemplo, /v1/chat/completions), puede usar la página equivalente del panel, y la falta de permisos deshabilita los elementos relacionados de la interfaz (como el botón Subir en Playground). Con RBAC puedes:
- Agrupar usuarios y asignar permisos a escala
- Crear roles personalizados con los permisos exactos que necesitas
- Definir el alcance del acceso a nivel de organización o proyecto
- Aplicar permisos coherentes tanto en el panel como en la API
Conceptos clave
- Organización: tu cuenta de nivel superior. Los roles de organización pueden otorgar acceso a todos los proyectos.
- Proyecto: un espacio de trabajo para claves, archivos y recursos. Los roles de proyecto otorgan acceso únicamente dentro de ese proyecto.
- Grupos: conjuntos de usuarios a los que puedes asignar roles. Los grupos se pueden sincronizar desde tu proveedor de identidad (mediante SCIM) para mantener actualizada automáticamente la lista de miembros.
- Roles: conjuntos de permisos (como Solicitudes a modelos o Escritura de archivos). Puedes crear roles para la organización en Configuración de la organización, o para un proyecto específico en la configuración de ese proyecto. Una vez creados, los roles de organización o proyecto se pueden asignar a usuarios o grupos. Los usuarios pueden tener varios roles, y su acceso es la unión de esos roles.
- Permisos: las acciones específicas que permite un rol (por ejemplo, realizar solicitudes a modelos, leer archivos, escribir archivos o administrar claves).
Permisos
La siguiente tabla muestra los permisos disponibles, qué roles predefinidos los incluyen y si se pueden configurar para roles personalizados.
| Área | Qué permite | Permisos del propietario de la organización | Permisos del lector de la organización | Permisos del propietario del proyecto | Permisos del miembro del proyecto | Permisos del observador del proyecto | Disponible para roles personalizados |
|---|---|---|---|---|---|---|---|
| Listar modelos | Listar los modelos a los que tiene acceso esta organización | Read | Read | Read | Read | Read | ✓ |
| Grupos | Ver y administrar grupos | Read, Write | Read | Read, Write | Read, Write | Read | |
| Roles | Ver y administrar roles | Read, Write | Read | Read, Write | Read, Write | Read | |
| Administración de la organización | Administrar usuarios, proyectos, invitaciones, claves de la API de administración y límites de solicitudes de la organización | Read, Write | |||||
| Uso | Ver el panel de uso y exportar datos | Read | ✓ | ||||
| Claves externas | Ver y administrar claves para Enterprise Key Management | Read, Write | |||||
| Lista de direcciones IP permitidas | Ver y administrar la lista de direcciones IP permitidas | Read, Write | |||||
| mTLS | Ver y administrar la configuración de TLS mutuo | Read, Write | |||||
| OIDC | Ver y administrar la configuración de OIDC | Read, Write | |||||
| Capacidades de los modelos | Realizar solicitudes para completar chats, procesar audio, generar embeddings y generar imágenes | Request | Request | Request | Request | ✓ | |
| Assistants | Crear y recuperar Assistants | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Hilos | Crear y recuperar hilos/mensajes/ejecuciones | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Evaluaciones | Crear, recuperar y eliminar evaluaciones | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Ajuste fino | Crear y recuperar trabajos de ajuste fino | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Archivos | Crear y recuperar archivos | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Almacenes de vectores | Crear y recuperar almacenes de vectores | Read, Write | Read, Write | Read, Write | Read, Write | ✓ | |
| API Responses | Crear respuestas | Read, Write | Read, Write | Read, Write | Read, Write | ✓ | |
| Prompts | Crear y recuperar prompts para usarlos como contexto en la API Responses y Realtime API | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Webhooks | Crear y ver webhooks en tu proyecto | Read, Write | Read | Read, Write | Read, Write | Read | ✓ |
| Conjuntos de datos | Crear y recuperar conjuntos de datos | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Apps | Crear, administrar y enviar apps a revisión en el panel | Read, Write | ✓ | ||||
| Túneles | Inspeccionar, usar y administrar túneles con alcance de organización | Read, Use, Manage | ✓ | ||||
| Claves de API del proyecto | Permiso para que un usuario administre sus propias claves de API | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Administración del proyecto | Administrar usuarios, cuentas de servicio, claves de API y límites de solicitudes del proyecto mediante la API de administración | Read, Write | Read, Write | ||||
| Procesamiento por lotes | Crear y administrar trabajos de procesamiento por lotes | Read, Write | Read, Write | Read, Write | Read, Write | Read | |
| Cuentas de servicio | Ver y administrar las cuentas de servicio del proyecto | Read, Write | Read, Write | ||||
| Videos | Crear y recuperar videos | Read, Write | Read, Write | Read, Write | Read, Write | ||
| Voces | Crear y recuperar voces | Read, Write | Read, Write | Read, Write | Read, Write | Read | |
| Agent Builder | Crear y administrar agentes y flujos de trabajo en Agent Builder | Read, Write | Read | Read, Write | Read, Write | Read | ✓ |
Implicaciones de los permisos de procesamiento por lotes
Los permisos de procesamiento por lotes incluyen el acceso necesario para preparar los archivos de entrada de los lotes, ejecutar solicitudes y recuperar resultados. Este acceso efectivo es independiente de los puntos de acceso que se pueden incluir en un lote, enumerados en la guía de la API de procesamiento por lotes.
| Permiso de procesamiento por lotes | Acceso adicional otorgado |
|---|---|
Lectura (api.batch.read) | Lectura de archivos (api.files.read) para /v1/files |
Escritura (api.batch.write) | Lectura de procesamiento por lotes Listar modelos ( api.model.read y model.read) para /v1/modelsLectura y escritura de archivos ( api.files.read y api.files.write) para /v1/filesSolicitudes a las capacidades de los modelos ( api.model.request y model.request) para /v1/audio, /v1/chat/completions, /v1/embeddings, /v1/images, /v1/moderations, /v1/realtime y /v1/responsesLectura y escritura de videos ( api.videos.read y api.videos.write) para /v1/videos |
Configuración de RBAC
Los cambios de roles y la sincronización de grupos pueden tardar hasta 30 minutos en propagarse.
-
Crea grupos Agrega grupos para los equipos (por ejemplo, “Ciencia de datos”, “Soporte”). Si usas un IdP, habilita la sincronización SCIM para mantener actualizada la membresía de los grupos.
-
Crea roles personalizados Comienza con el mínimo de privilegios. Por ejemplo:
- Evaluador de modelos: lectura de modelos, solicitudes a las capacidades de los modelos, evaluaciones
- Ingeniero de modelos: solicitudes a las capacidades de los modelos, lectura/escritura de archivos, ajuste fino
- Publicador de apps: lectura de apps, escritura de apps
-
Asigna roles
- Los roles a nivel de organización se aplican en todas partes (en todos los proyectos de la organización).
- Los roles a nivel de proyecto se aplican solo en ese proyecto. Puedes asignar roles a usuarios y grupos. Los usuarios pueden tener varios roles; el acceso es la unión de sus permisos.
-
Verifica Usa una cuenta sin rol de propietario para confirmar el acceso esperado (API y panel). Ajusta los roles si los usuarios pueden ver más de lo que necesitan.
Aplica el principio de privilegio mínimo. Comienza con los permisos mínimos necesarios para una tarea y agrega más solo cuando sea necesario.
Ejemplos de configuración de acceso
Equipo pequeño
- Asigna al equipo principal un rol a nivel de organización con permisos de solicitud de capacidades del modelo y de lectura/escritura de archivos.
- Crea un proyecto para cada aplicación; agrega a los contratistas únicamente a esos proyectos, con roles a nivel de proyecto.
Organización más grande
- Sincroniza los grupos de tu IdP (por ejemplo, “Investigación”, “Soporte”, “Finanzas”).
- Crea roles personalizados para cada función y asígnalos a nivel de organización; o asigna únicamente roles específicos del proyecto cuando este necesite controles más estrictos.
Contratistas y proveedores
- Crea un grupo “Contratistas” sin roles a nivel de organización.
- Agrégalos a proyectos específicos con roles de proyecto de alcance limitado (por ejemplo, acceso de solo lectura).
Cómo se evalúa el acceso de los usuarios
En el panel, combinamos:
- los roles de la organización (asignados directamente + mediante grupos)
- los roles del proyecto (asignados directamente + mediante grupos)
Los permisos efectivos son la unión de todos los roles asignados.
Si se realiza una solicitud con una clave de API dentro de un proyecto, tomamos los permisos asignados a la clave de API y comprobamos que el usuario tenga algún rol de proyecto que le otorgue esos permisos. Por ejemplo, al realizar una solicitud a /v1/models, la clave de API debe tener asignado api.model.read y el usuario debe tener un rol de proyecto con api.model.read.
Prácticas recomendadas
- Representa tu organización mediante grupos: refleja los equipos en tu IdP y asigna roles a grupos, no a personas.
- Separa las responsabilidades: lectura de modelos, carga de archivos y administración de claves.
- Límites entre proyectos: coloca los experimentos, la preproducción y la producción en proyectos separados.
- Revisa periódicamente: elimina los roles y las claves que no se usan; rota las claves sensibles.
- Prueba con una cuenta sin rol de propietario: verifica que el acceso sea el esperado antes de implementar la configuración de forma generalizada.