Access control

You sign in with your account and work in one active organisation at a time. Your organisation role decides what you can do across that organisation, and grants on each bot, block and asset decide who can use, edit and manage it. Grants go to people directly or to groups. The server checks every action, and the app shows sidebar sections and actions only when your permissions allow them.

Organisation rolesCopy Anchor Link

Every membership carries one of four organisation roles. The role decides which organisation permissions the person holds, and so which sidebar sections and create actions they see. The role picker lists each role's permissions.

Managing admins also needs manage_organization, so only an Admin can invite someone as Admin, give the Admin role, or change or remove an Admin. An organisation always keeps at least one Admin.

The organisation role covers organisation-wide actions. What someone may do with a particular bot, block or asset comes from the grants on it, described under Sharing. Every role, Viewer included, can chat and use the OrcAI Assistant. The Assistant acts with your own permissions and never exceeds them.

Active organisationCopy Anchor Link

Signing in activates your organisation automatically when you have only one. With several organisations you choose one on the selection page. Pending invitations keep that page in view even when one organisation is already active.

If you lose membership of the active organisation, the app clears the selection and shows the selection page, even if only one organisation remains.

The selection page (/select-organization) opens from Switch organisation in the user menu. It lists your organisations, filters them by name and loads more of them a page at a time, and you accept pending invitations there. Instance admins also get a Manage instance link to /instance.

InvitationsCopy Anchor Link

Invitations add users to organisations and are the only way to create an account, which the sign-up endpoint enforces. The first account of an instance comes from the init flow instead.

Invitations always go to the active organisation. Admins and managers see all of its invitations, whoever sent them, and can change or delete any of them, except that only admins send, change or delete an invitation for the Admin role.

Invite member on Members opens /app/members/add. One form invites a batch and sets the Role, the Expires date (seven days ahead by default) and the Email language for everyone in it. Add addresses one at a time with Add email field or paste a list with Bulk add emails, then choose Create invitations. An address that already belongs to a member, or already has a pending invitation that has not expired, gets no new invitation and no email, and the toast names it. Change a member's role instead. For an address whose pending invitation has expired, a new invitation with a new email replaces it, and the old one is listed as Rejected.

View invitations opens /app/members/invitations, a table with the columns Email, Invitation ID, Expires, Status and Role. Each row offers Copy invitation link and Delete organisation invitation. Delete selected removes the selected rows, and Download exports the table.

An invited person creates their account through the invitation's sign-up link. Signing up checks that the invitation exists, is pending and unexpired, and matches the email address, and the Create account page names the inviting organisation. Signing up accepts only the linked invitation, and other invitations stay pending until they are accepted. Your own invitations, across every organisation, appear on the account and selection pages, where you respond to them. Someone who is already a member and accepts another invitation to the same organisation keeps their current role. One active organisation opens directly when there are no pending invitations. Access does not need a verified email address.

GroupsCopy Anchor Link

A group lets you grant access to many members at once. Groups (/app/groups) lists them with search and a Type column that tells Custom groups from System groups, and Manage group opens a group at /app/groups/<group id>.

Every organisation has one system group, All members, which group lists show as All Members. Every member of the organisation belongs to it implicitly, so its member list cannot be edited, and it cannot be renamed or deleted. Granting a bot, block or asset to All members shares it with the whole organisation.

Custom groups can be created, renamed, described and deleted, and their explicit members added and removed. The member list labels each membership as implicit or explicit. All of this needs manage_groups, so the Groups pages stay with admins and managers. Reading a group does not: members and viewers see the groups they belong to, plus the All members group of their organisation. A group they are not in answers as if it were not there.

The member picker offers only organisation members who are not yet in the group, and several of them can be added at once.

Members and viewers can find colleagues by name and avatar in All members and select sharing recipients by user ID. Email fields and email search need manage_groups.

SharingCopy Anchor Link

Access & groups opens the access dialog on a bot's page (/app/library/bots/<bot id>), a behaviour's or repository's page (/app/library/behaviours/<block id>, /app/library/repositories/<block id>) and an asset's page (/app/library/assets/<asset id>). The bot editor's Sharing and access step embeds the same controls. New people and groups are added from the People and Groups tabs, each granted one of three roles:

• Can view can find, use and read it.
• Can edit can also edit it.
• Can manage can also delete it and manage its access.

The owner of a bot, block or asset holds all of these. Whoever creates it owns it until it is handed over. Listing a bot or block in the Catalogue and taking it out both ask for confirmation.

Hand overCopy Anchor Link

The owner gives a bot, behaviour, repository or Library asset to another member with Hand over in its … menu. The dialog lists the members of the organisation who can own content, that is Members, Managers and Admins who are not banned. The new owner holds every action on it, and you keep Can manage. Listings and grants stay as they are. Only the owner sees Hand over, and it works only while the item's own organisation is your active organisation. Something added from the Catalogue has no Hand over, and an item opened from another organisation refuses it with the reason in the dialog. A chat upload stays with whoever uploaded it.

Removing a member, making one a Viewer and deleting an account hand their content over as well, as Administration describes.

The access dialog holds the group grants, the direct grants and a summary of the access inherited from the bots and blocks above. For a bot or block it also holds the Catalogue listing.

Managing access to a bot, block or asset, in its access dialog or through the API, needs manage_access on it, which you have when you own it or hold a Can manage grant on it. Listing a bot or block in the Catalogue needs the same. Organisation admins have no override. An admin who neither owns nor manages it cannot see its grants or share it, nor list a bot or block in the Catalogue, and its access dialog is not offered to them.

Whoever holds manage_access on a bot, block or asset shares it. Among them, organisation admins and managers may grant to every group of the organisation. Members and viewers may grant to the groups they belong to and to All members, which only ever receives a Can view grant. Other groups are neither offered in the access dialog nor accepted by the API. The picker leaves out anyone who already holds a direct grant. Several people and groups can be selected and granted the same role together. If any of them cannot be granted, none of them are, and the error names each one that failed.

Each grant belongs to the organisation it was issued in. The access dialog lists and changes the grants of your active organisation, and only that organisation's members and groups receive them. A person who leaves an organisation loses the grants issued there and keeps those from elsewhere.

A bot, block or asset with Can manage grants keeps at least one, so a grant or revoke that would take away the last one is refused. A person or group that leaves still loses its grants, even the last Can manage grant, when they are removed from the organisation, their account is deleted or the group is deleted. The owner keeps managing it.

A bot, block or asset that is not listed in the Catalogue is readable only by its owner, the people and groups it was granted to, and those with inherited access. You use one in your active organisation, when you start a chat with a bot, attach a block to a chat or link a block into a bot. That needs it to belong to the organisation and a grant issued there to you, to one of its groups you are in, or to All members. Owning it counts in its own organisation. Access does not travel with the person, so someone who belongs to two organisations uses in each only what is shared there.

The CatalogueCopy Anchor Link

Bots, behaviours and repositories can be listed in the Catalogue. A listed bot or block can be previewed by every signed-in user of the instance, but using it needs the organisation to add it and a grant issued there. Only the configuration and its blocks are shared, because a bot or block runs with the providers, models and quota pools of the organisation it is used in. Assets are not listed on their own. A listed repository lets everyone preview its assets, and the repository editor says so, including for assets added later.

A listed bot contains only listed blocks. Listing a bot lists its unlisted behaviour and repositories with it. The confirmation names them, and the listing is refused unless you manage access to each of them. Saving a listed bot with a block that is not listed asks the same before it saves. The OrcAI Assistant never lists anything, so a change it makes to a listed bot that needs a block listed fails and points you to the app.

Admins and managers add a listed bot or block to their organisation (add_from_catalogue). It then appears in that organisation's Library marked "From" its home organisation, and nobody there can use it until they share it. In an organisation that added it, its access dialog shares it for use only, so the grants issued there are always Can view grants, to that organisation's members and groups, and neither listing nor inherited access is shown. Only the home organisation edits, lists or deletes it. The organisation that added it sets a bot's model there and removes it again with Remove from …, which ends its grants, its bot setup and its links in that organisation, so chats with a removed bot become read-only until it is added and shared again. Adding something twice changes nothing.

Taking a bot or block out of the Catalogue removes it from every organisation that added it, and the confirmation names them. There, the grants issued for it end, their bots and chats lose the block, and a bot's bot setup is deleted, so their chats with the bot become read-only. A block that a listed bot contains cannot be taken out of the Catalogue until that bot is taken out too or drops the block. Either way, nothing added to it afterwards reaches those organisations.

Inherited accessCopy Anchor Link

Access cascades downwards as read-only. Sharing a bot lets its audience read the blocks it links and the assets those blocks carry. So a bot, block or asset can be widely readable while its own grant list is empty, and the access dialog says so. It reports the bots and blocks whose grants reach it, how many groups and people arrive that way, and whether one of them is listed in the Catalogue.

Edit rights do not cascade. Can edit or Can manage on a bot does not give Can edit on its blocks, and editing a block or an asset needs a grant on it. When you give someone Can edit or Can manage on a bot, the access manager offers to give them Can edit on the bot's blocks too, for the blocks you can share. Because linking passes read on, a bot links only blocks of its own organisation that its editor may use there, and a repository attaches only assets its editor can read. A chat with a bot uses the bot's blocks without a grant on each of them, and a chat without a bot attaches only blocks of the chat's organisation.

Inherited access is shown, not edited. manage_access does not cascade, so a grant that arrives from a bot is changed on that bot, which is where the summary's links lead. Bots and blocks the viewer cannot read are counted rather than named. Inherited access lasts only as long as the link above it. Detaching a block from a bot ends the access that came through that bot, and direct grants and access through other bots remain.

Deleting a bot, block or asset removes its grants, its Catalogue listing and the access it passed on through its links. Deleting an organisation deletes the bots, blocks and assets it is home to, including listed ones that other organisations added.

Permission-gated organisation sectionsCopy Anchor Link

The sidebar's Your organisation group holds the OrcAI Assistant (/app/assistant), the Library (/app/library), the Catalogue (/app/catalogue) and Administration. The Assistant, the Library and the Catalogue show for every role. Administration shows when at least one of its items is allowed:

• Members (/app/members): manage_members
• Groups (/app/groups): manage_groups
• Quota pools (/app/quota-pools): manage_quota_pools
• Analytics (/app/analytics): view_analytics
• Providers (/app/providers): manage_providers
• Models (/app/models): manage_models
• Organisation (/app/organization): manage_organization

Opening one of these paths without the permission leads away from it. Administration describes the pages.

Practical guidanceCopy Anchor Link

Share through groups, so access follows membership, and keep direct grants for one-off exceptions. Provider, model and quota pool management comes only with the Admin role, so give that role to few people.

Why someone cannot see a bot or assetCopy Anchor Link

Work through these in order:

1. Check that the person is a member of the bot's or asset's organisation. Grants go only to members and groups of that organisation, and the access dialog offers no one else.
2. Open Access & groups on the bot or asset. Unless it is listed in the Catalogue, it is visible only to its owner, to the people granted it directly, to the members of the groups granted it, and to those who inherit access. With none of these, only its owner sees it.
3. Check group membership. A grant to a group reaches only its members, and All members reaches everyone in the organisation.
4. For a bot, check that it is published. Drafts appear in the Library only for those who can edit them, and a new chat offers published bots only.
5. An admin or manager can open the person's page under Members (/app/members/<user id>/edit). Its Effective access table lists every bot, block and asset the person reaches, and its Origin column says where the access comes from: a direct grant, a group, All members, inheritance from a bot, a block or the organisation, or a Catalogue listing.