Permissions Best Practices

Effective permission configuration balances security (members cannot do things they shouldn't) with usability (members can do their job without constantly contacting admins). This guide covers the most common design patterns and mistakes.

Principle of least privilege

Grant the minimum access required to perform the job role. Start with the lowest role and add capabilities only when a documented business need exists.

Situation	Don't do	Do this instead
Unsure what access someone needs	Add as org_admin "just in case"	Add as member + viewer in their project; promote when needed
External contractor	Add as regular member	Use workflow_responder or a guest share
New team member onboarding	Add to all projects as initiator	Add only to the projects they are actively working on

Role design patterns

Pattern 1: Document control team

Recommended roles for a typical document control team:

Team member	Org role	Project role
Lead Document Controller	org_manager	project_admin in their projects
Document Controller	member	initiator in their projects
Administrator (data entry)	member	initiator (with manage_documents override if needed)
Senior reviewer	member	reviewer in review projects, initiator in their submission projects

Pattern 2: Construction project with external parties

Party	Org role	Notes
Client representative	member	viewer in project
Main contractor	member	initiator in their work package projects
Subcontractors	member	reviewer in the subpackage project, or workflow_responder
External design consultant	workflow_responder	Can only respond to assigned steps
Auditor (short-term)	member	viewer — remove after audit

Pattern 3: Multi-project programme

For large programmes with many projects:

Level	Role assignment
Programme level	org_manager for programme directors, member for all others
Each project	project_admin for the project manager, initiator for project team, reviewer for cross-project approvers
Shared approval panel	Add as reviewer across all projects in the programme

Managing external reviewers

External parties (not in your organisation) need access without seeing your full project content. Three options in increasing security:

Option	Access level	Best for
Guest share	Token-based, no login required	One-off document distribution, client review
workflow_responder org role	Login required, only assigned steps visible	Regular external reviewers across multiple projects
reviewer project role	Login required, full project read access	Trusted external parties who need full visibility

For external parties who respond to many approvals, workflow_responder is the most appropriate — they see only what they need to act on.

Protecting sensitive data

For projects with confidential documents:

1. Keep the Confidential toggle on documents that must be restricted.
2. Create Access Control Groups for the members who should see confidential documents in each discipline.
3. Do not rely solely on project roles for confidentiality — a viewer can see all non-confidential documents but cannot see confidential ones.
4. Audit the access control groups quarterly.

See Access Control Groups for setup.

Common mistakes

Mistake	Effect	Fix
Making everyone a Project Admin	Members can delete documents, cancel workflows, change settings accidentally	Use initiator for most team members
Using org_admin for all org-level tasks	Any compromise of the account affects the whole org	Reserve org_admin for 1–2 people; use org_manager for everyone else
Not removing access when members leave	Former employees retain access	Set a process to remove members from projects when they leave the team
No default role review	New members get too much or too little access by default	Review and set appropriate defaults in org settings
Over-using overrides	Permission matrix becomes unpredictable	Reserve overrides for genuine exceptions; use standard roles for the common case

Permission audit checklist

Review permissions at project milestones:

• Are all project_admin members still on the project team?
• Have any members left the project or organisation? (remove access)
• Are workflow_responder members still needed?
• Are all guest shares still valid and not expired?
• Are access control groups still accurate for confidential documents?
• Are permission overrides still justified?

What's next

• Organisation Roles — baseline role capabilities
• Project Roles — project-level capabilities
• Permission Overrides — how to customise defaults
• Access Control Groups — restrict confidential document access