Users & Roles

Every visitor to CompassDocs must sign in, and what they can do is governed by the permissions they hold. Four built-in roles bundle those permissions into the shapes most workspaces need, ordered from least to most privileged: Viewer, Editor, Approver, Admin.

Assign one of these and you’re done. Need something in between — someone who publishes but administers nothing, or edits one space only — build a custom role instead.

Permissions at a glance

Action	Viewer	Editor	Approver	Admin
Read / search / ask AI	✓	✓	✓	✓
Submit a suggestion	✓	✓	✓	✓
Create & edit drafts	–	✓	✓	✓
Publish / push a change live	–	–¹	✓	✓
Review queue (approve edits & suggestions)	–	–	✓	✓
Manage users, roles & settings	–	–	–	✓

These four are presets rather than the whole story: you can build custom roles from individual permissions and grant them for the whole workspace or one space — see Roles & permissions. The table describes what each preset grants, and upgrading changed nobody’s access.

Since 1.0 the table is a description rather than the mechanism. Every row is a permission the preset happens to hold, and a custom role holding the same permission does the same thing — including the two that used to be special cases. “Create & edit drafts” is document.read_draft plus document.update; “Publish” is document.publish. Before 1.0, a custom role granting either of those was ignored in favour of the person’s rung.

¹ In open approval mode, anyone who can edit publishes directly. In strict mode (the default) those changes become pending change requests for someone who can review them — see Approval workflow.

Delegated section access

The operational sections in the main navigation — Announcements, Compliance, and Training (“Create training decks, assign them, and track completion — everyone always sees their own assignments”) — are admin-only by default, but don’t have to be. Under Settings → Section access, grant any of them to individual people or groups (searchable pickers, so this stays quick even with thousands of accounts):

• Grants apply immediately: the section appears in the person’s sidebar, and its pages and APIs accept them.
• Each section is independent — the comms lead gets Announcements, the HR manager gets Compliance, the L&D lead gets Training, and none can touch the others (or anything else under Settings).
• Group grants follow membership, including Entra-synced groups: joiners gain access, leavers lose it, automatically.
• Every change is audited.

The Admin console

Admins manage everyone else from Settings → Users:

• Create users with a username, name, email, role, and a temporary password (the user is asked to set a new one on first sign-in, before anything else). They can sign in with the username or, since 1.16.0, the email address. An email another account already uses, as its email or its username, is refused.
• Change roles from a dropdown. This sets the built-in role; custom roles are granted on Roles & permissions, and the column here shows any a person holds beyond their rung.
• Email… sets an account’s email, or confirms it (1.16.0). Below the username each row shows the email, and one the person typed on their own profile is marked Unconfirmed: single sign-on won’t link to it, group sync won’t match it by email and the directory won’t link a profile by it until you save it here. Check that the address belongs to that person first, because single sign-on gives the account to whoever signs in with it: save it unchanged if it is theirs, and change or clear it if it isn’t (a colleague’s address, typed in to receive their sign-in). An email another account already uses, as its email or its username, is refused.
• Reset passwords to a new temporary value.
• Enable / disable accounts (a disabled user can’t sign in but is kept).
• Reset 2FA for a user who lost their authenticator and recovery codes.
• Delete accounts. With the helpdesk, deleting someone also anonymises their tickets (1.19.1), in the same step, except tickets on legal hold.
• Compliance record (1.14.0, when read confirmation is licensed): opens that person’s compliance record.
• Download personal data (1.19.1): a JSON file of what CompassDocs holds that is the person’s to receive: in 1.19.1, their name, username and email and their helpdesk requests with the public conversation. It needs Delete a user (user.delete) and is in the audit log.

From 1.19.1, Email…, Reset password and Disable stay on each row, and the rest (Reset 2FA…, Compliance record, Anonymise compliance record…, Download personal data and Delete…) are in the row’s ⋯ menu (“More actions for Sam Lee”), so the table fits without scrolling sideways.

Last-admin guard

CompassDocs won’t let you remove the last active admin — you can’t delete, disable, or demote the final admin account. This prevents locking yourself out of the console.

First-run setup

On a fresh install, CompassDocs shows a setup wizard where you create the first admin account in the browser — no default password. From there you add everyone else in Settings → Users. (To provision the admin without the wizard, set COMPASSDOCS_ADMIN_USER / COMPASSDOCS_ADMIN_PASSWORD — see Environment variables.)

Beyond passwords

Local accounts use passwords hashed with Node’s scrypt and secure HTTP-only cookie sessions — no external services required. On top of that:

• Single sign-on (Enterprise) lets people sign in with your identity provider — Microsoft Entra ID or any OIDC provider, or any SAML 2.0 IdP (Okta, OneLogin, Google Workspace, ADFS) — with optional auto-provisioning. The sign-in page then asks for an email first and sends each person to SSO or to a password (Email-first sign-in), without ever saying whether an account exists.
• Two-factor authentication — each user can enroll a TOTP authenticator; admins can clear a locked-out user’s 2FA from the user list (Reset 2FA, audited).
• Groups control who can see private spaces — membership is managed by hand or synced from Microsoft Entra.