The rules document¶

The rules document holds the rules that apply to every active member of your organisation, beside the rules of their roles. This page shows how to read and replace it. What the rules document is, is in Roles and access.

org-admin reads and replaces the rules document. On screen you find it under User management > Rules document; this page shows the API. The examples use $OS, $TOKEN and $ORG as in Manage groups.

What you use it for¶

Every member holds the built-in role member, which already lets everyone use the organisation's models, agents, knowledge and tools (what exactly). The rules document is therefore mainly for two things:

• Narrowing for everyone or for some. A forbid refuses, whatever any role allows. A forbid with a condition on the person touches only those who meet it, such as the members of one group.
• Widening for everyone. A permit applies to every member, for example seeing the shared conversations of their own department.

What applies to some members only usually belongs in a custom role.

Read the document¶

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

The answer has rules, the rules, and version, which is also in the ETag header. An organisation that never wrote the document has an empty one with version 0.

Replace the document¶

You replace the document whole: send every rule that should stay, plus your change. Name the version you read in If-Match, "0" the first time.

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_..."}]}
        ]}'

The first rule refuses everyone every model whose name starts with gpt-5. The second refuses the members of one group (here the interns, by id) every agent labelled department: finance. How to write rules is in Kinds and actions.

After a replace the new rules apply at once to administration in OS. In the AI features they apply once OS has carried them through there; that happens in the background, shortly after your change.

For the whole organisation¶

Rules about memory_write (writing memory), share_link (sharing through a link), artifact_download (downloading files a tool produced), router (model routers) and egress_host (outside addresses) apply to everyone at once. They take no condition on the person (when) and sit only in the rules document, never in a role.

Model routers and downloading files a tool produced reach every member by default. Writing memory and sharing through a link reach nobody until the rules document allows them; then they reach everyone. You write such a permit only when you hold it yourself: org-admin and operator do. This switches memory writing on for the whole organisation:

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

Put the rule among the rules you already had, and replace the document as above. Take it out and memory writing is off again.

Without a permit about egress_host the AI features call no outside address at all, not for API tools and not for connectors either. Every permit with match.names allows the addresses it names: an exact host name, or *. followed by a host name for every address below it, at most 200 characters. A forbid takes addresses away from what the permits allow. An address the deployment blocks stays blocked, even when you allow it.

{"id": "ticket-system", "effect": "permit", "kind": "egress_host",
 "match": {"names": ["mcp.example.com"]}}

Allow one address¶

To allow one address you do not need to replace the whole document:

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 adds a permit for that address to the rules document (201), or changes nothing when the document allows the address already (200). GET …/allowed-hosts lists the addresses the document allows, and DELETE …/allowed-hosts/mcp.example.com removes the rule that names exactly that address. Only org-admin and operator allow an address. The address applies after a few seconds.

What OS checks¶

• You hold what you allow. Every permit you add you must hold yourself (why). Rules already in the document are not checked again, so you can edit a document holding a rule somebody else added. A forbid narrows and only needs you to be allowed to change the document.
• No refusal on administration. A forbid about organisation, membership, invitation, group, role, rule or attribute is not possible.
• Limits. At most 500 rules and 2,000 name patterns together; each rule at most 200 name patterns, 16 label tests and 16 conditions; every id only once.
• Known attributes. A condition names role, group, or an attribute your organisation or an organisation above it has defined.
• Fixed values. An attribute_has condition on an attribute with a fixed list must name a value from that list, also when an organisation above yours defined the attribute.
• What a kind takes. Each kind of the AI features takes only certain actions and parts of a rule (which); OS refuses a rule with another part.

When OS refuses¶