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 effect of a grant lands on a short delay: a read-confirmation policy whose audience names a role (see Who must confirm) picks up a role granted or revoked here within the hour, when the compliance sweep reconciles audiences; group and space changes apply at once.

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.

The built-in Compliance manager role (the one Delegate a section picks for Compliance) holds the four compliance permissions, compliance.program_read, compliance.program_manage, compliance.export and, from 1.14.0, compliance.team_read; from 1.13.0 the preset also records exemptions, deadline extensions and snoozes on any policy’s roster (compliance.program_manage), and from 1.14.0 the Policies and People bulk bars and POST /api/admin/compliance/bulk need compliance.program_manage too: a compliance.program_read holder sees neither the checkboxes nor the bars and is answered 403. Read team policies (compliance.team_read, 1.14.0) is the policy twin of training.team_read: see policy standing for the groups you lead. Leading a group grants it for that group while Program settings allow, and a role holding it sees every group on the Compliance section’s Team tab and opens the compliance record of anyone in a group (the policies in spaces it can read); reminding from the Team tab still takes leading the member’s group or compliance.program_manage. See Who can manage the program and Team leads.

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.

And from 1.18.0:

• Build handbooks (handbook.manage) creates, edits, publishes and deletes policy handbooks. Granted workspace-wide (the Admin preset holds it) it builds workspace handbooks from any published document the holder can see, and edits the handbooks of every space. Granted for one space it makes the holder that space’s handbook admin: handbooks owned by the space, built from documents in the spaces where they hold it. A space they can’t read is never one they manage. Custom roles don’t get it on upgrade, so add it to a role, or grant a role that holds it on a space, to let others build handbooks. Reading a handbook needs no permission: its audience decides. See Who builds handbooks.

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

Helpdesk permissions (1.19.0)

The helpdesk (Enterprise, helpdesk) adds five workspace permissions, all global:

Permission	Key	Grants	Built-in roles
Get help	helpdesk.request	Raise requests and follow your own in Get help, and decide approvals asked of you	Viewer, Editor, Approver, Admin
Work helpdesk tickets	helpdesk.agent	The desk, for the helpdesk teams you belong to, plus tickets assigned to you	Admin, Helpdesk agent, Helpdesk manager
Work every team’s tickets	helpdesk.agent_all	Every team’s queue	Admin, Helpdesk manager
Configure the helpdesk	helpdesk.admin	Teams, request types, workflows, reply targets, automations, macros, email and surveys; reports. Its holders are always desk Admin.	Admin, Helpdesk manager
Read helpdesk reports	helpdesk.reports	View and export helpdesk reports, for every team	Admin, Helpdesk manager

Two built-in roles are ready to grant, to people or groups:

• Helpdesk agent (helpdesk.agent and helpdesk.request): work tickets in the desk for the helpdesk teams you belong to. Membership of a team (Desk settings → Teams) decides which queues.
• Helpdesk manager (all five): work every team’s tickets, configure the helpdesk and read its reports.

If you had already made a custom role named “Helpdesk agent” or “Helpdesk manager”, it keeps its id, people, permissions and name (with “ (custom)“ added where it reads like the built-in’s); only its key moves, to helpdesk-agent-custom or helpdesk-manager-custom, and the move is audited.

Custom roles get none of these keys on upgrade: add Get help to a custom role whose people should raise requests.

What an agent may do inside the desk (reply directly or after review, assign, transfer, manage macros, configure) is decided by their desk role: Newbie, Agent, Team lead, Manager or Admin. The workspace permissions stay as floors: Configure the helpdesk is always desk Admin, Work every team’s tickets always sees every team, and Read helpdesk reports always reads every report.

With COMPASSDOCS_AUTHZ_LEGACY=1, Get help stays open to every role and the rest of the helpdesk is for admins only.

Notification policy permissions (1.19.0)

• View notification policies (notification.policy_read) and Change notification policies (notification.policy_manage) open Settings → Notifications → Policies (see Notification policies). The Admin preset holds both; custom roles don’t on upgrade.

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.