Roles and access¶

This page explains how OS decides what someone may do in an organisation: roles, groups, attributes, the organisation's rules document, how a partner reaches the organisations below it, and why nobody can give away more than they hold. It has no steps; the task pages under Manage show how to set it up.

A rule decides¶

Everything a person may do in OS comes from rules. A rule says, about one kind of thing (a group, a member, an agent, a conversation), whether it allows something (permit) or refuses it (forbid), for which actions, and under which conditions.

There are four actions:

Three facts decide every case:

• Nothing is allowed without a rule that allows it. The order of the rules does not matter.
• A refusing rule wins. When a forbid matches, OS refuses, whatever any permit says.
• No action includes another. Someone who may change a thing but not see it cannot find it. What you may not see does not exist for you: OS answers as if it were not there.

A rule can set conditions on the thing (its name, or a label it carries) and on the person (an attribute they have). A rule applies only when all of its conditions hold; to allow either of two values, you write two rules. What a rule looks like exactly is in Kinds and actions.

Roles¶

A role is a named set of rules. Whoever holds a role is decided under its rules. A member gets a role directly, or through a group they are in.

Every organisation has the same built-in roles. They are the same everywhere and you do not change them.

An administrator also creates custom roles for their organisation, for example a "Team lead" role that may manage the members of their own department. An organisation has at most 100, each with at most 200 rules. See Manage roles.

What the built-in roles allow in the AI features¶

The built-in roles also hold rules about the AI features: models, agents, knowledge, files and conversations.

Every built-in role may use every model, tool, agent, prompt, skill, schedule, workflow, knowledge and file of the organisation. What the organisation's service does not hold, a built-in role may not do either. Of conversations, memory, stored files and datastore rows a member reaches their own and the shared ones, which belong to nobody in particular.

An administrator never sees a colleague's conversations, memory or files. org-admin too reaches only their own and the shared ones of those rows. To allow otherwise you write a rule for it yourself, and you can only do that if you hold that access yourself (below).

Settings for the whole organisation¶

A few things apply to everyone in the organisation at once and do not depend on the person. They are therefore not in a role but in the rules document:

• whether the AI features may write memory: for nobody by default;
• whether stored files and pages may be shared through a link: for nobody by default;
• whether files a tool produced may be downloaded: for every member by default;
• which model routers may be used: every one, for every member, by default;
• which outside addresses the AI features may reach. Without a rule about that, they are the addresses your operator allows for the organisation; a rule can narrow that.

Memory writing and sharing through a link come on once the rules document allows them, and then for everyone, never for one person. Only someone who holds them, org-admin or operator, may write such a rule (how). A custom role cannot say anything about these.

Groups¶

A group bundles members, for example a team or a department. A group can have roles and attribute values, and every member of the group then has them too. Someone who leaves the group, or whose group is deleted, loses what the group gave. See Manage groups.

Attributes¶

An attribute is a fact about a member that rules can read, such as department or office. The administrator decides which attributes the organisation knows and whether their values are free or come from a fixed list. A member has the values they were given plus those of their groups. See Manage attributes.

OS always works out three attributes itself, and you cannot create them:

• role: every role the member holds, directly or through a group;
• group: every group the member is in;
• subject: who the member is, so a rule can say "this is mine".

OS works these facts out again on every request from what the organisation has recorded. A member cannot state their own attributes.

The rules document¶

Besides roles, every organisation has one rules document: rules that apply to every active member. It holds what applies to everyone, such as "nobody uses the expensive model" or "interns use no agents of the finance department". The settings for the whole organisation are here too. See The rules document.

So for a member, these apply together: the rules of their roles, the rules document, and member.

Partners and the organisations below¶

A role is given with a reach:

• organisation (the default): the role applies in the organisation that gave it.
• descendants: the role applies in that organisation and in every organisation below it.

This is how a partner's people work in their customers' organisations without being members there. A support person who holds org-admin at the partner with reach descendants also administers the customers below the partner. Of the partner, only what was given with reach descendants counts in a customer's organisation; the partner's rules document and its roles of reach organisation do not reach down.

An organisation cannot take away the administration an organisation above it gives with reach descendants: there are no refusing rules on administration. On the AI features there are: a forbid in an organisation's rules document applies there to a partner's people too. The organisation's audit trail names, for every change, the organisation the person acted from.

The first administrator of a new organisation gets org-admin with reach descendants, so they also administer the departments they later create below their organisation.

Nobody grants more than they hold¶

Every change that can let someone do more is a grant: giving a role, putting a member in a group, giving a group a role or a value, giving an attribute value, writing the rules of a custom role or the rules document, and inviting with any of these. OS allows a grant only when you may make the change itself and you hold what you give away:

• a role you hold when you hold it yourself (with at least the same reach), or every rule of it;
• an attribute value you hold when you have it yourself, or may give that attribute (org-admin may, for every attribute);
• a group you hold when you hold every role and every value the group gives;
• a rule you hold when one of your own rules allows the same, over the same things, and no refusing rule takes part of it away.

A refused grant changes nothing, and OS names what you do not hold. An invitation is checked when it is sent and again when it is accepted.

You cannot write a refusing rule about administration (organisations, members, invitations, groups, roles, rules and attributes). Such a rule could take rights away from the administrators themselves. On the AI features you can refuse.

Inside the organisation's service¶

Everything roles, groups and rules allow applies only inside the organisation's service: what its plans and exceptions hold. A rule about something the service does not hold allows nothing. The service therefore makes roles smaller, never larger, and a refusing rule always still applies.

Whoever grants a custom role, a group or a rule that reaches beyond the service gets 403 with This is not part of your organisation's service, even before the check whether you hold what you give away (above). You can always give the built-in roles: they are the same everywhere and the service only makes them smaller. The organisation's own administration (members, invitations, groups, roles, attributes, rules, the audit trail and reading the service) is always in the service (Always in the service).

What you see in OS¶

OS shows buttons and menus exactly for what you may do, inside the organisation's service: every thing carries the actions you may take on it, and every kind the actions you may take on at least one thing of it. What you do not see, you may not do. How a program reads this is in The access API.

The audit trail¶

Every change to an organisation's people, groups, roles, attributes, rules, invitations and settings goes into its audit trail: when, who, from which organisation, and what changed. The trail holds no passwords, keys or e-mail addresses. See Read the audit trail.