Skip to content

Kinds and actions

This page is for looking things up: what a rule looks like, which kinds of thing a rule can name and what each action means on each kind. What rules and roles are is in Roles and access.

A rule

{"id": "own-department", "effect": "permit", "kind": "membership",
 "actions": ["see", "write"],
 "match": {"labels": {"office": "utrecht"}},
 "when": [{"atom": "label_among", "label": "department", "attribute": "department"}]}
Part Meaning
effect permit allows, forbid refuses
kind the kind of thing the rule is about (OS, AI features)
actions see, use, write, delete; left out is every action the kind takes
match.names patterns the thing's name must match one of: *, ? and [a-z], case-sensitive; left out is every name
match.labels labels the thing must carry, each with this value among its values; at most 16
when conditions on the person, all of which must hold; at most 16
id optional: a name of your own for the rule, lowercase letters, digits and -, starting with a letter, unique in the document; a refusal names the rule by this id

A condition in when is one of three:

Condition Holds when
{"atom": "label_is_subject", "label": "subject"} the person themselves is among that label's values on the thing: "this is mine"
{"atom": "label_among", "label": "department", "attribute": "department"} at least one of the label's values on the thing is also one of the person's values for the attribute
{"atom": "attribute_has", "attribute": "role", "value": "org-admin"} the person's attribute has that value; it reads nothing of the thing

The attributes a condition can read are role (a built-in role's name or a custom role's id rol_...), group (a group's id grp_...) and every attribute the organisation or an organisation above it has defined. OS refuses a condition on any other attribute.

How OS decides

  • Nothing is allowed without a permit that matches; a forbid that matches always refuses. The order does not matter.
  • A rule matches when all of its match holds for the thing and all of its when for the person. There is no "or" and no "not": two possible values are two rules.
  • Labels and attributes are sets of values. A thing without the label fails every test of that label.
  • No action includes another. OS asks see first; what the person may not see does not exist for them (404).
  • Creating something is a write, decided on the labels in the request. Changing labels is decided on the old labels and on the new ones.

Limits and restrictions

Where Limit
rules document at most 500 rules and 2,000 name patterns together
custom role at most 200 rules, each at most 15 conditions
one rule at most 200 name patterns, 16 label tests, 16 conditions
organisation at most 100 custom roles and 16 attributes; everything the organisation and the organisations above it give together, at most 500 rules in the AI features; the organisation and every organisation below it at most 32 attributes and labels that rules read (409 past that)

OS also refuses:

  • a forbid about organisation, membership, invitation, group, role, rule or attribute: on administration you write only what is allowed;
  • a rule about placement outside the top organisation;
  • an attribute_has with a value outside the attribute's fixed list, also when an organisation above defined it;
  • a condition on an attribute nobody defined;
  • a rule about an OS kind with an action the kind does not take: each kind takes only the actions in its row, so use on group or membership, for example, is not possible;
  • a rule about the AI features with a part the kind does not take (below);
  • in a custom role: a rule about router, egress_host, artifact_download, share_link or memory_write.

Each of these refusals is a 422 on writing; nothing changes.

A rule allowing what the organisation's service does not hold is refused 403 (This is not part of your organisation's service.): in a custom role, in the rules document, and when you give a custom role or a group with such a role. You can always give a built-in role; the service only makes it smaller.

In the service

A plan or an exception names kinds with their actions, like a rule, but without match and when. These kinds are in every service and in no plan: organisation, membership, invitation, group, role, rule, attribute, audit_event, service, webhook, event, export and notification_channel, and also placement and service_plan, which only Artific manages. OS refuses a plan or exception naming one of these kinds with 422. Every other kind is in the service only when a plan or exception gives it, and so are the kinds of your company's sign-in, domain and sign_in.

An item names only actions the kind takes: for OS's kinds those in its row, for the AI features' kinds those in their table. So thread takes no use. The kinds without actions (router, egress_host, artifact_download, share_link, memory_write) are in the service whole or not at all: an item about them names no actions. Otherwise OS refuses the plan or exception with 422.

OS's kinds

Kind The thing see use write delete
organisation the organisation, its settings, and an organisation below it see it, see the organisations below — change its settings; create an organisation below delete it
membership a member see members — invite, deactivate, reactivate, give attributes remove
invitation a pending invitation see — send again revoke
group a group see — create, rename, add and remove members, give roles and values delete
role a built-in or custom role see give it to a member or group, or take it back create or change a custom role delete a custom role
rule the rules document read — replace —
attribute an attribute see give its values to others define or change delete
audit_event a row of the audit trail read the trail — — —
placement where an organisation's data is kept — — set it —
domain a proved e-mail domain see — add and prove give up
sign_in your company's sign-in see — add and link unlink
service the organisation's service: its plans, exceptions, trials and a demo's end date read it — give and remove plans and exceptions, set a demo's end date; decided in the organisation above —
service_plan a plan of Artific's see — create, change delete
webhook one of the organisation's webhooks and its deliveries see, never the secret — register, change, replace the secret, enable, test, deliver again remove
event the organisation's events read the feed, and receive a delivery — — —
export an export of the organisation or of one member see the organisation's exports download them ask for one —
notification_channel a Slack channel the organisation connected see, never the address — connect, change, test disconnect
direct_chat the desk of chats handed over to a colleague; the built-in role consultant holds it see the desk and read a chat on it take a chat over, answer, release it, hand it back — close a waiting request
improvement the organisation's suggested improvements, their settings and the analyses read the settings, the analyses and every suggestion — change the settings, start an analysis, accept, dismiss or reopen a suggestion —

A kind takes only the actions in its row: service only see and write, and organisation, membership, invitation, group, domain and sign_in no use. OS refuses a rule, plan or exception naming another action with 422. A rule without actions applies to the actions the kind takes, and allowed_actions never names another.

OS decides placement and service_plan only for someone acting from the top organisation. OS decides a write on service in the organisation above, for someone who holds org-admin there with reach descendants (how).

What match reads on a thing of OS:

Kind match.labels reads match.names reads
membership the member's facts: role, group, every attribute, and subject, the member themselves —
group, role the labels on it (at most 32); every built-in role carries builtin: true the name
organisation its labels, which the organisation above sets the name
attribute — the name

The AI features' kinds

These kinds are about what members do in the AI features. They are listed in CoreAccessKind.

Kind What a rule decides Actions
model which models a conversation uses see, use
tool which tools the model is offered and may call see, use, write, delete
prompt, skill, agent, schedule, workflow which prompts, skills, agents, schedules and workflows someone reaches see, use, write, delete
knowledge_collection, knowledge_index, knowledge_graph, knowledge_table_set which knowledge collections, indexes, graphs and table sets someone reaches see, use, write, delete
file, datastore which files and datastores someone reaches by name see, use, write, delete
thread which conversations someone reaches see, write, delete
memory_record which memory someone reaches see, write, delete
knowledge_source which knowledge sources a search finds see, write, delete
stored_file which stored files and uploads someone reaches see, write, delete
datastore_record which rows of a datastore someone reaches see, write, delete
router which model routers are used none
egress_host which outside addresses can be reached none
artifact_download whether files a tool produced may be downloaded none
share_link whether stored files and pages may be shared through a link none
memory_write whether the AI features may write memory none

A kind without actions takes no actions: the rule is about the kind as a whole.

Not every kind takes every part of a rule. OS refuses with 422, when you write it, a rule with a part the kind does not take or an action it does not know:

  • Rows (thread, memory_record, knowledge_source, stored_file, datastore_record) have no name, so no match.names. The label subject is who made the row; an empty subject ("") is a shared row. Of the AI features, only rows have the label subject.
  • file and datastore carry no labels, so no match.labels, and as a condition only attribute_has.
  • For the whole organisation (router, egress_host, artifact_download, share_link, memory_write): no condition on the person (when), and therefore only in the rules document, never in a role (how). They take no labels; egress_host takes match.names for the addresses. Model routers and downloads reach every member by default; writing memory and sharing through a link reach nobody until the rules document allows them.