Roles & Permissions

The four built-in roles — Viewer, Editor, Approver, Admin — cover most workspaces. When they don’t, Settings → Roles & permissions lets you build a role out of individual permissions and grant it to whoever needs it.

This is what makes “let Priya run the launchpad” possible without making Priya an administrator.

How the model works

Three ideas, and nothing else:

• A role is a named set of permissions. There are around 200 permissions, each one a single thing CompassDocs can do — “create a group”, “restore a backup”, “revoke a share link”.
• An assignment grants a role to a person or a group, either across the whole workspace or within one space.
• What someone can do is the union of every assignment that applies.

There are no deny rules and no inheritance. A permission is held or it isn’t. That is a deliberate limitation: deny precedence is where access systems become impossible to reason about, and the restrictive posture is available by granting narrowly instead.

Granting a role to a group is usually what you want. The role follows the group, so people joining or leaving pick it up and lose it without anyone coming back to this page.

What a custom role can reach

Since 1.0, everything. There is no part of CompassDocs left that decides access by built-in role instead of by permission — which was not true before: until 1.0 a custom role granting Read drafts saw no drafts anywhere (search, the space list, the page tree, the command palette, the document page), and one granting Publish document still had its work queued for review, because those two questions were still answered by the person’s rung.

Two consequences worth knowing if you already use custom roles:

• A role that looked broken should now work. Nobody gains access they were not granted; the grant stops being ignored.
• A per-space grant is enough on its own. Giving someone Author in space for one space lets them write there even if their built-in role is Viewer — no promotion needed, and no access anywhere else. The Spaces screen offers every active account for this, not only editors.

Your existing roles still work

Viewer, Editor, Approver, and Admin are now presets — real roles, holding exactly the permissions they always did. Upgrading changes nobody’s access.

Presets are read-only, and that’s on purpose: their permission sets are re-derived from the catalog every time CompassDocs starts, which is how an upgrade that adds a new capability grants it to the right roles without anyone having to notice. An edit here would quietly revert on the next restart.

To customise one, use Duplicate and edit the copy.

Creating a role

1. Go to Settings → Roles & permissions.
2. New role, give it a name. It grants nothing until you tick something.
3. Tick permissions in the matrix. They’re grouped by what they act on, each group collapses, and the filter box searches names, descriptions, and permission keys at once. Select all works per group.
4. Save. It applies to the next request anyone makes — no sign-out needed.

Permissions marked per space apply within a space. Granted workspace-wide they apply everywhere; granted for one space they apply only there.

Granting a role

On the Assignments tab, pick the role, choose a person or a group, and optionally a space. Leave the space blank to grant across the whole workspace.

The table below lists every assignment, filterable, with a revoke button.

One entry you can’t revoke here: each person’s built-in role appears as an assignment, because that’s exactly what it is. Change it in Users & roles so both move together.

Per-space grants appear here too

Since 0.99, granting a group access to a private space — or giving someone edit rights on a single space — creates an assignment of a seeded role, scoped to that space:

Role	What it grants	Where you’d normally set it
Space member	Read a private space	Spaces → Who can see it
Space author	Create and edit documents in a space	Spaces → Who can edit

Nothing about the Spaces screens changed, and existing grants moved across on upgrade. What’s new is that a per-space grant is now visible in one place with everything else — including Explain access and the audit log, which previously couldn’t see it at all. You can assign these roles directly here if you’d rather work role-first.

Why can this person do that?

The Explain access tab answers it. Pick someone and you get everything they effectively hold, with the role — and, where relevant, the group — that gave them each one.

This is the fastest way to check that a role you just built does what you intended, before someone finds out the hard way.

Health

The fourth tab answers the three questions worth asking about the model itself:

• Can anyone still let people back in? At least one active person must be able to change other people’s access. CompassDocs enforces this: any change that would take it to zero — editing a role, deleting one, revoking a grant — is applied, checked, and rolled back with an explanation. The workspace cannot be locked out of itself.
• Does the model agree with the old role ladder? Every request evaluates both and records whether they matched, with the route and permission for each differing pair. Disagreements are expected once you start using custom roles — they’re where a custom role has genuinely changed someone’s access. Since 1.0 nothing else consults the ladder, so this is a regression detector rather than a migration scoreboard: a pair that starts differing with no role edit behind it is worth reporting.
• Does everyone have a role? Should always read zero; it’s checked and repaired every time CompassDocs starts.

Delegation and the newsletter are roles too

Granting someone Announcements, Compliance, or Training under Settings → Section access, or making them a newsletter contributor or approver, creates a role grant. Those pages work exactly as they always did — the difference is that the grant shows up here, can be given to a group, and can be explained like anything else.

A person who reaches a section through a custom role won’t be listed on the Section access page, and shouldn’t be: that page didn’t grant it, so it doesn’t offer to take it away. This page is where the whole picture lives.

Granting a role in one space

Leave the space blank and a role applies workspace-wide. Name a space and its per-space permissions apply only there — including read access to a private space, which previously could only come from a group.

Two permissions are worth knowing:

• Member of a space (space.member) is what space membership is. Granted for one space, it lets someone read that private space.
• Author in space (space.author) lets them create and edit documents there, regardless of the org-wide “editors edit everything” switch.

A third is worth knowing since 1.0:

• Read drafts (document.read_draft) granted for one space reveals that space’s unpublished work — in search, the space list, the page tree, the command palette’s recents — and reveals nothing anywhere else.

Space-scoped grants are added to whatever access someone already has through groups and per-space edit rights — they never take access away.

Settings sections follow permissions

Each settings section has its own permission, so someone granted (say) audit access sees the Audit log section in Settings and nothing else. The navigation lists only what you can open.

If something goes wrong

Setting COMPASSDOCS_AUTHZ_LEGACY=1 in the environment and restarting reverts to the previous behaviour, where the four built-in roles decide access and custom roles grant nothing. It’s an environment variable rather than a setting precisely because the situation it exists for is “nobody can sign in to change the setting”. The console shows a banner while it’s active.

Custom roles and assignments are untouched while it’s set, so removing it and restarting picks up exactly where you left off.