Roles & Permissions

Papermerge uses a role-based access control (RBAC) system to manage what users can do. Roles bundle permissions together, and users are assigned roles that grant them the necessary access.

How It Works

The permission system has three layers:

1. Permissions — Individual actions (e.g., “create tag”, “delete document”)
2. Roles — Collections of permissions (e.g., “Editor”, “Viewer”)
3. Users — People who are assigned one or more roles

Permissions

A permission (also called a scope) represents a single action in the system. Permissions follow a consistent naming pattern:

entity.action

Examples:

Permission	Description
document.create	Upload new documents
document.read	View documents
document.update	Edit document metadata
document.delete	Delete documents
tag.create	Create new tags
tag.delete	Delete tags
user.create	Create user accounts
role.update	Modify roles

Permission Categories

Permissions are organized by entity:

• Document — document.create, document.read, document.update, document.delete
• Folder — folder.create, folder.read, folder.update, folder.delete
• Tag — tag.create, tag.read, tag.update, tag.delete
• Metadata — customfield.create, customfield.read, customfield.update, customfield.delete
• Category — documenttype.create, documenttype.read, documenttype.update, documenttype.delete
• User — user.create, user.read, user.update, user.delete
• Group — group.create, group.read, group.update, group.delete
• Role — role.create, role.read, role.update, role.delete

Roles

A role is a named collection of permissions. Instead of assigning individual permissions to each user, you assign roles.

Example Roles

Viewer

• document.read
• folder.read
• tag.read

Can view documents and folders but cannot make changes.

Editor

• document.create, document.read, document.update
• folder.create, folder.read, folder.update
• tag.create, tag.read, tag.update

Can create and edit documents, folders, and tags, but cannot delete.

Manager

• All document, folder, tag, metadata, category permissions
• user.read

Full control over documents and organizational features.

Administrator

• All permissions

Complete system access including user and role management.

Creating Roles

To create a new role:

1. Navigate to Settings → Roles
2. Click New Role
3. Enter a name (e.g., “Accountant”)
4. Select the permissions to include
5. Save the role

Tip

Start with minimal permissions and add more as needed. It’s easier to grant additional access than to revoke excess permissions.

Assigning Roles to Users

To assign a role to a user:

1. Navigate to Settings → Users
2. Select the user
3. In the Roles section, add the appropriate role(s)
4. Save changes

A user can have multiple roles. Their effective permissions are the union of all permissions from all assigned roles.

Role Design Principles

Principle of Least Privilege

Give users only the permissions they need to do their job:

• A receptionist who only uploads documents needs document.create
• An accountant who reviews invoices needs document.read and document.update
• A manager who organizes the archive needs broader permissions

Separation of Duties

Use different roles for different responsibilities:

• Document roles — For people who work with documents
• Organization roles — For people who manage tags, categories, metadata
• Admin roles — For people who manage users and system settings

Role Hierarchy

Design roles that build on each other:

• Viewer < Editor < Manager < Administrator

This makes it easy to upgrade a user’s access as their responsibilities grow.

Editing Roles

To modify an existing role:

1. Navigate to Settings → Roles
2. Select the role to edit
3. Add or remove permissions
4. Save changes

Caution

Changing a role affects all users who have that role. Be careful when removing permissions from widely-used roles.

Deleting Roles

When you delete a role:

1. Users lose the permissions that came from that role
2. Users are not deleted — only the role assignment is removed
3. If a user had only that role, they may lose significant access

Before deleting a role, check which users have it assigned and ensure they have alternative roles if needed.

Common Role Configurations

Small Office

• Admin — Full access (1-2 people)
• Staff — Create, read, update documents and tags
• Viewer — Read-only access for occasional users

Department-Based

• Department Editor — Full document access within department folders
• Cross-Department Viewer — Read access across departments
• IT Admin — System and user management

Compliance-Focused

• Document Creator — Upload and initial metadata entry
• Reviewer — Read and update, cannot delete
• Approver — Can archive documents
• Deletion Approver — Can approve deletion of expired documents
• Auditor — Read-only access to all documents and audit logs

Best Practices

1. Name roles clearly — Use descriptive names like “Invoice Processor” rather than generic names like “Role 1”.

2. Document role purposes — Use the description field to explain what each role is for and who should have it.

3. Review regularly — Periodically audit role assignments. Remove roles from users who no longer need them.

4. Avoid per-user permissions — If you find yourself creating roles for single users, reconsider your role design.

5. Test before deploying — When creating new roles, test them with a test user before assigning to real users.

6. Keep admin access limited — Only a few trusted users should have full administrative access.