El documento de reglas¶

El documento de reglas contiene las reglas que valen para todo miembro activo de tu organización, además de las reglas de sus roles. Esta página muestra cómo leerlo y sustituirlo. Qué es el documento de reglas está en Roles y acceso.

Leer y sustituir el documento de reglas puede hacerlo org-admin. En pantalla lo encuentras en Gestión de usuarios > Documento de reglas; esta página muestra la API. Los ejemplos usan $OS, $TOKEN y $ORG como en Administrar grupos.

Para qué lo usas¶

Todo miembro tiene el rol integrado member, que ya permite que todos usen los modelos, agentes, conocimiento y herramientas de la organización (qué exactamente). Por eso el documento de reglas sirve sobre todo para dos cosas:

• Restringir para todos o para una parte. Un forbid deniega, permita lo que permita cualquier rol. Un forbid con una condición sobre la persona afecta solo a quien cumple esa condición, como los miembros de un grupo.
• Ampliar para todos. Un permit vale para todo miembro, por ejemplo ver las conversaciones compartidas del propio departamento.

Lo que solo vale para algunos miembros suele ser mejor ponerlo en un rol propio.

Leer el documento¶

curl -s -i "$OS/api/v1/organisations/$ORG/rules" -H "Authorization: Bearer $TOKEN"

La respuesta tiene rules, las reglas, y version, que también está en la cabecera ETag. Una organización que nunca escribió el documento tiene un documento vacío con la versión 0.

Sustituir el documento¶

Sustituyes el documento entero: envía todas las reglas que deben quedar, más tu cambio. Indica en If-Match la versión que leíste, "0" la primera vez.

curl -s -X PUT "$OS/api/v1/organisations/$ORG/rules" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -H 'If-Match: "0"' \
    -d '{"rules": [
          {"id": "no-expensive-model", "effect": "forbid", "kind": "model",
           "match": {"names": ["gpt-5*"]}},
          {"id": "interns-no-finance-agents", "effect": "forbid", "kind": "agent",
           "match": {"labels": {"department": "finance"}},
           "when": [{"atom": "attribute_has", "attribute": "group", "value": "grp_..."}]}
        ]}'

La primera regla deniega a todos cualquier modelo cuyo nombre empiece por gpt-5. La segunda deniega a los miembros de un grupo (aquí los becarios, por id) cualquier agente con la etiqueta department: finance. Cómo escribes reglas está en Tipos y acciones.

Tras una sustitución, las reglas nuevas valen de inmediato para la administración en OS. En las funciones de IA valen en cuanto OS las ha aplicado allí; eso ocurre en segundo plano, poco después de tu cambio.

Para toda la organización¶

Las reglas sobre memory_write (escribir memoria), share_link (compartir mediante un enlace), artifact_download (descargar archivos que creó una herramienta), router (enrutadores de modelos) y egress_host (direcciones externas) valen para todos a la vez. No tienen una condición sobre la persona (when) y están solo en el documento de reglas, nunca en un rol.

Los enrutadores de modelos y la descarga de archivos que creó una herramienta están por defecto al alcance de todo miembro. Escribir memoria y compartir mediante un enlace no están al alcance de nadie hasta que el documento de reglas los permite; entonces están al alcance de todos. Un permit así solo lo escribes si lo tienes tú mismo: lo tienen org-admin y operator. Así activas escribir memoria para toda la organización:

{"id": "memory-on", "effect": "permit", "kind": "memory_write"}

Incluye la regla entre las que ya tenías y sustituye el documento como arriba. Si la quitas, escribir memoria vuelve a estar desactivado.

Sin un permit sobre egress_host, las funciones de IA no llaman a ninguna dirección externa, ni para las herramientas de API ni para los conectores. Cada permit con match.names permite las direcciones que nombra: un nombre de host exacto, o *. seguido de un nombre de host para toda dirección por debajo, como máximo 200 caracteres. Un forbid quita direcciones de lo que permiten los permits. Una dirección que el entorno bloquea sigue bloqueada, aunque la permitas.

{"id": "sistema-de-tickets", "effect": "permit", "kind": "egress_host",
 "match": {"names": ["mcp.example.com"]}}

Permitir una dirección¶

Para permitir una dirección no hace falta sustituir todo el documento:

curl -s -X POST "$OS/api/v1/organisations/$ORG/allowed-hosts" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"host": "mcp.example.com"}'

OS añade un permit para esa dirección al documento de reglas (201), o no cambia nada si el documento ya permite la dirección (200). GET …/allowed-hosts lista las direcciones que el documento permite, y DELETE …/allowed-hosts/mcp.example.com quita la regla que nombra exactamente esa dirección. Solo org-admin y operator permiten una dirección. La dirección se aplica al cabo de unos segundos.

Qué comprueba OS¶

• Tienes lo que permites. Todo permit que añades debes tenerlo tú mismo (por qué). Las reglas que ya estaban en el documento no se vuelven a comprobar, de modo que puedes editar un documento con una regla que añadió otra persona. Un forbid restringe y solo exige que puedas modificar el documento.
• Ninguna denegación sobre la administración. No se puede un forbid sobre organisation, membership, invitation, group, role, rule o attribute.
• Límites. Como máximo 500 reglas y 2.000 patrones de nombre en conjunto; cada regla como máximo 200 patrones de nombre, 16 pruebas de etiqueta y 16 condiciones; cada id una sola vez.
• Atributos conocidos. Una condición nombra role, group, o un atributo que tu organización o una organización superior haya definido.
• Valores fijos. Una condición attribute_has sobre un atributo con una lista fija debe nombrar un valor de esa lista, también si una organización superior a la tuya definió el atributo.
• Lo que admite un tipo. Cada tipo de las funciones de IA admite solo ciertas acciones y partes de una regla (cuáles); OS rechaza una regla con otra parte.

Si OS rechaza¶