Skip to content

Roles and permissions ​

Two questions that used to wear one name, and are now separate:

  1. What may you do to the workspace — invite people, read the log, define roles. That is a role, and a role is a named set of capabilities.
  2. What may you open — that is an access level on a page, decided by grants and by the role's default.

admin once meant both "may invite people" and "may edit everything", and a workspace that wanted somebody to run its member list without handing them every private page had no way to say so.

Access levels ​

none → read → comment → write.

comment is a real level, not a courtesy: it is what can leave a comment and propose a change without being able to make one.

The three built-in roles ​

RoleCapabilitiesDefault page level
Adminall of themwrite
Memberlist_members, create_root_pages, manage_views, use_assistantwrite
Guestnonenone

A guest gets nothing until something is shared with them, which is what makes them a useful subject for external sharing.

The presets are constants, not rows. A workspace that has never opened the roles screen still has exactly the three roles it always had, and a preset stored in a row is a preset somebody could redefine into something else.

The capabilities ​

The list is closed — fifteen of them, and adding one is a change somebody reviews. An open list is a permission system nobody can enumerate, and one nobody can enumerate is one nobody can audit.

CapabilityWhat it permits
manage_membersChange what someone may do here, and remove them — and make the token a directory syncs members with
list_membersSee the roster: who is in this workspace at all
manage_invitationsWrite and withdraw invitations — the power to appoint, since one carries a role
manage_groupsCreate, rename and populate groups
manage_rolesDefine the roles themselves
manage_viewsMake a saved view that belongs to the workspace rather than to a page
create_root_pagesMake a page at the root, belonging to nobody in particular
read_auditRead the workspace's audit log
export_workspaceRead the whole-workspace fingerprint an export mirror runs on, and download the workspace as a zip
manage_ssoConfigure this workspace's identity provider, the domains it claims and proves, its group mappings, and the workspace's sign-in rules
manage_api_keysSee and revoke other people's API keys. Your own need no capability
manage_webhooksPoint this workspace at a URL that is told when things happen here — see webhooks
publish_sitesPublish part of the workspace as a site, and run every site it has
manage_workspaceChange the workspace's own settings: icon, who may join without an invitation and as what, the digest's time zone — and ask for a different package
manage_billingSee the workspace's invoices and keep its billing details. Its own capability because whoever pays is often not whoever runs the workspace
use_assistantAsk the assistant. It acts as the person asking and can do no more than they could; what it adds is sending what they can read to a model
manage_assistantDecide which models the assistant may send this workspace's writing to, and what it may do without asking
manage_noticesDecide how many words this workspace's notices carry into chat apps such as Telegram, whose servers read them

Two were considered and refused, and the reasons are the shape of the rule:

  • decide_proposals — accepting a proposal already requires write on the page it changes. A second answer to a question the access rule already answers is the bug this design exists to avoid.
  • delete_workspace — that is the operator's, and it lives in platform_role, on the other side of the tenant boundary.

Custom roles ​

A workspace can define its own roles: pick a name, a set of capabilities, and a default page level. Two things a custom role cannot be given:

  • Sovereignty. Only admin is beyond a grant's reach, because admin is the account that can rescue a workspace nobody can get into. If one bad grant could lock them out, there is no way back. A custom role holding every capability can still be shut out of a page — which is exactly the separation being drawn.
  • An invitation. Invitations are control plane and name an address that may not have an account yet, while a custom role id only means something inside one workspace. So an invitation carries a preset, and a custom role is one change to the membership after they arrive.

A role somebody holds cannot be deleted. Everyone holding it would quietly lose access with nothing to point at, so the refusal names how many people it would have been.

How access to a page is decided ​

One pure function over the page's ancestry, asked identically by the page tree, search, the timeline, a socket upgrade and an export. Writing the rule four times is how you get four different answers.

Nearest page wins outright. An explicit none close to a page beats a generous grant far from it — without that, a grant at the root would quietly reopen everything closed beneath it.

At a single page, the most specific statement about who you are wins:

person  →  group  →  workspace  →  everyone

A group is this workspace's own statement about particular people, so it is more specific than a statement about a whole company. everyone is the least specific thing a page can say.

Two groups that disagree at the same page take the more generous. The alternative makes adding somebody to a group able to take access away, which is not what anybody means by adding them to a group. A revocation belongs where it is meant: on the page.

"Everyone in the workspace" means members

It means everybody holding a membership here, guests included — not everybody with an account on the deployment. It did not always: a page a workspace opened to its own team was once readable by any signed-in stranger, along with its place in the tree, its search hits and a live editing socket. The membership check is now a required argument, so the compiler names every call site rather than letting a future one default to permissive.

Enforcement is not the caret ​

A read-only page opens without a caret so you find out before you type. That is the courtesy; the socket refusing what a reader sends anyway is the enforcement, and the permission filter living inside the tree, search and timeline queries is what stops the existence of what you cannot see from leaking.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.