Use Paperless-ngx with Your Family: Users, Groups and Permissions

A document archive for the whole family sounds simple: everyone uploads their documents, everyone finds everything. In practice one person’s tax return should not show up for another, while the insurance policy should be visible to both. Paperless-ngx can do both if you set up users, groups and permissions cleanly from the start.

Here I show how I set up Paperless-ngx for several people: one account per person, a group for shared documents, centrally managed document types, one mailbox per person for import, and protection with two-factor sign-in. The guide assumes a running Paperless installation, for example from the VPS guide.

How permissions work in Paperless

Paperless has two levels:

• Global permissions decide which areas a user may open at all: documents, tags, correspondents, workflows, settings. For each area there is view, add, change and delete.
• Object permissions decide who may see and edit a single document, tag or correspondent. Every object has an owner. Only the owner sees it until they grant view or edit access to users or groups.

Three rules follow that matter in a family:

1. New users have no global permissions at first, except those of their groups.
2. Permissions on a tag only apply to the tag itself, not to the documents with that tag.
3. Documents without an owner are visible to every user. That applies to files from the consume folder unless you assign an owner.

The third rule is the most common trap. If you connect the scanner to the consume folder and set up nothing else, you have an archive in which everyone sees everything. How to set the owner automatically is covered below under workflows.

Create users and a group

You only need the administrator for setup. In daily use everyone works with their own account.

1. Open Settings → Users & Groups → Users and click Add. Create an account for yourself and for each other person, each with their own password. Leave Staff and Superuser off. A superuser sees all documents.
2. Switch to Groups and create a group Familie. Add all users. The group stands for documents that several people should see.
3. Open the group and under Permissions enable only what you need day to day: view, add and change documents, plus tags and correspondents. Mail accounts, workflows and user management stay with the administrator.
4. Grant at least View for UISettings. Without this permission a user cannot use the web interface.

If people should only read, such as children or the tax advisor, give them only View in a separate group.

Keep document types central

The more people create document types, the messier the list gets: “Invoice”, “Invoices”, “Invoice (car)”. So I keep the types central. In the group set DocumentType to View only. Then the administrator creates the types, and everyone else can assign them to their documents but cannot invent new ones. The same goes for custom fields (CustomField).

Useful types are invoice, contract, letter, notice, manual and other. I keep tags just as short: shared tags such as Arbeit, Auto, Gesundheit, Steuern and Wohnen, plus Inbox for anything not yet reviewed. Correspondents are the concrete senders such as electricity provider, health insurer or tax office.

Who owns a document is something Paperless tracks through the owner, not through a tag. So you do not need a tag Anna.

Private and shared documents

A document is at first visible only to its owner. For shared documents open it and pick the Permissions tab. There you give the group Familie view or edit access.

To change several documents at once, select them in the document list and click Permissions.

Note that tags, correspondents and types have their own permissions. If Anna creates a tag, at first only she sees it. So that everyone can use it, share it with the group under Attributes. If someone cannot see an object, Paperless shows “Private” there.

Collect documents by email

With one mailbox per person nobody has to know how Paperless works. Anna sends her invoice to anna-papiere@yourdomain.com, and it lands in her area. One mailbox per person and one for shared documents is practical, for example papiere@yourdomain.com. You create them at your hosting provider.

1. Create the mail account: Sign in as administrator in the Django admin (https://paperless.yourdomain.com/admin) and open Mail accounts → Add. Enter user name, password, IMAP server and port. Take the server name from your hosting provider’s documents, not simply your domain name.
2. Create a mail rule: Under Mail rules create one rule per mailbox, for example Anna, Import. I only process attachments matching *.pdf,*.jpg,*.jpeg,*.png,*.tif,*.tiff. That keeps signature images out.
3. Assign the owner with a workflow: Under Workflows create one per mailbox. As trigger choose the source Mail Fetch and the matching mail rule. The action is an Assignment where you set the owner to the right user. For the shared mailbox also set the group Familie as view permission. Then everyone sees the document, and only the owner may edit it.

Labels can differ by language and version. Paperless checks the mailboxes every ten minutes by default. Test with an email with a PDF attachment: the document should appear after ten minutes at the latest, visible only to the right user.

The same pattern works for the scanner. A network scanner can send the scan by email to the respective person’s mailbox, or you use the consume folder with one subfolder per person, as in the scanner guide. For subfolders you also need a workflow that sets the owner, because files from the folder have none otherwise.

Secure the sign-in

With several accounts the risk of a weak password rises.

• Two-factor sign-in: Each user enables it under My Profile. They scan a QR code with an authenticator app and note the ten recovery codes. If someone loses phone and codes, a superuser can reset two-factor in user management.
• Password reset: The function needs a mail server. Set PAPERLESS_EMAIL_HOST and the related settings, plus PAPERLESS_URL.
• Central sign-in: If you run several services, you can connect Paperless to an identity provider such as Pocket ID. Then everyone signs in with a passkey, as described in the Pocket ID guide.

Do not forget the backup

Accounts, mail rules, types and permissions are work you do not want to repeat. They live in the database. An export with document_exporter secures documents including metadata and owners. How to automate it is covered in Paperless backup and restore.

Common mistakes

Everyone sees all documents. The documents have no owner, often because they come from the consume folder. Set an owner through a workflow and assign existing documents with bulk edit.

A user does not see the web interface. They lack the global permission UISettings → View.

A tag appears as “Private”. The tag belongs to another user and is not shared with the group. The owner or an administrator shares it.

Someone keeps creating new document types. Remove the group’s right to add document types and leave only View.

FAQ