Skip to main content

Understanding Permissions in AuditSwarm

Quick guide: Learn what the different permission levels mean and how they affect user access.

Permission System Overview​

AuditSwarm uses a two-tier permission system:

┌─────────────────────────────────────────┐
│ 1. Page Access (On/Off)                │
│    Can the user see this section?       │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│ 2. Entity Permissions (View/Edit/None) │
│    What can they do with specific items?│
└─────────────────────────────────────────┘

Page Access (Tier 1)​

Binary control: User either has access to a page or doesn't.

Available Pages​

PageIconWhat It Controls
Dashboards📊View analytics, reports, and custom dashboards
Audits📋Access to all audits (view list, create new)
Issues⚠️Access to compliance issues tracking
Risks🎯Access to risk register and assessments
Controls🛡️Access to security controls management
Templates📝Access to workflow and document templates
Time⏱️Access to time tracking and timesheets
Admin⚙️System administration (user management, settings)

Example:

  • ✅ Page Access ON: User sees "Audits" in the navigation menu
  • ❌ Page Access OFF: User doesn't see "Audits" anywhere

Entity Permissions (Tier 2)​

Granular control: What can the user do with a specific audit, risk, workflow, etc.?

Permission Levels​

🔓 (No Selection) - Default State​

Meaning: No explicit permission set

Access Depends On:

  • Public entities: User can view (if they have page access)
  • Private entities: User cannot access

Use When: You want the entity visibility setting to control access

Example:

User: Jane
Entity: "Q1 Security Audit" (public)
Permission: (no selection)
Result: ✅ Jane can view (because entity is public)

👁️ View - Read-Only Access​

User Can:

  • ✅ See entity details
  • ✅ Read comments and notes
  • ✅ View attachments and linked documents
  • ✅ See workflow progress
  • ✅ View audit trail

User Cannot:

  • ❌ Edit any fields
  • ❌ Change status
  • ❌ Delete entity
  • ❌ Modify permissions
  • ❌ Archive or complete

Use When:

  • External auditors reviewing work
  • Team members who need visibility but shouldn't edit
  • Stakeholders monitoring progress
  • Compliance officers reviewing evidence

Example:

User: External Auditor
Entity: "SOC2 Type II Audit"
Permission: View
Result: ✅ Can read everything, ❌ Cannot change anything

✏️ Edit - Full Access​

User Can:

  • ✅ Everything from "View" level
  • ✅ Edit all fields
  • ✅ Change status (draft → active → completed)
  • ✅ Add/remove comments
  • ✅ Upload/delete attachments
  • ✅ Modify workflow steps
  • ✅ Archive entity (if status allows)

User Cannot:

  • ❌ Change ownership (admin only)
  • ❌ Modify permissions (admin only)
  • ❌ Delete entity (owner or admin only)

Use When:

  • Lead auditors managing audits
  • Risk managers updating risk assessments
  • Control owners maintaining control documentation
  • Workflow managers coordinating work

Example:

User: Lead Auditor
Entity: "Internal IT Audit"
Permission: Edit
Result: ✅ Full control over audit lifecycle

❌ None - Explicitly Blocked​

Meaning: User is explicitly blocked from accessing this entity

User Cannot:

  • ❌ See entity in lists
  • ❌ View details
  • ❌ Access via direct link

Use When:

  • Entity is public but specific user shouldn't see it
  • Revoking access after role change
  • Blocking access during sensitive investigations
  • Separating conflicting interests

Example:

User: John (former team member)
Entity: "Confidential HR Audit" (public)
Permission: None
Result: ❌ John cannot see it despite entity being public

How Permissions Interact​

Page Access + Entity Permission​

Both tiers must allow access:

Page AccessEntity PermissionResult
❌ OFF(any)❌ No access - User can't even reach the page
✅ ON(no selection)✅/❌ Depends on visibility - Public = view, Private = no access
✅ ONView✅ Read-only - Can view details
✅ ONEdit✅ Full access - Can modify
✅ ONNone❌ Blocked - Explicitly denied

Entity Visibility + Permission​

Entity VisibilityUser PermissionResult
Public(no selection)✅ Can view (with page access)
PublicView✅ Can view
PublicEdit✅ Can edit
PublicNone❌ Blocked - Permission overrides visibility
Private(no selection)❌ Cannot access
PrivateView✅ Can view
PrivateEdit✅ Can edit
PrivateNone❌ Cannot access

Workflows and Inheritance​

Workflows can be nested under parent entities (audits, issues, risks, controls).

Independent Permissions​

Workflows have their own permissions - they do NOT inherit from parent.

Example:

📋 "NIST Assessment" (Audit)
  User Permission: View
  ├── 🔄 "Planning Workflow"
  │   User Permission: Edit ✅ Can modify workflow
  └── 🔄 "Reporting Workflow"
      User Permission: (none) ❌ Cannot see workflow

Why? Allows granular control over who can work on specific phases.

Admin Users​

Admins bypass ALL permissions.

  • 🛡️ Admin badge shown in UI
  • Can access all pages
  • Can view/edit all entities (public and private)
  • Cannot be restricted via permission system

To restrict an admin: Remove admin role first, then set permissions.

Permission Decision Flow​

User tries to access "Q4 Financial Audit"
         ↓
┌────────────────────────┐
│ Is user an Admin?      │ → YES → ✅ Allow full access
└────────────────────────┘
         ↓ NO
┌────────────────────────┐
│ Has Page Access?       │ → NO → ❌ Deny (can't reach page)
└────────────────────────┘
         ↓ YES
┌────────────────────────┐
│ Permission = None?     │ → YES → ❌ Deny (explicitly blocked)
└────────────────────────┘
         ↓ NO
┌────────────────────────┐
│ Permission = Edit?     │ → YES → ✅ Allow edit access
└────────────────────────┘
         ↓ NO
┌────────────────────────┐
│ Permission = View?     │ → YES → ✅ Allow view access
└────────────────────────┘
         ↓ NO
┌────────────────────────┐
│ Entity is Public?      │ → YES → ✅ Allow view access
└────────────────────────┘
         ↓ NO
❌ Deny (private entity, no explicit permission)

Common Scenarios​

Scenario 1: New Employee​

Setup:

  • Page Access: ✅ Dashboards, ✅ Audits, ✅ Issues
  • Entity Permissions: View on assigned audits

Result: Can see dashboards and view (but not edit) their assigned work.

Scenario 2: Lead Auditor​

Setup:

  • Page Access: ✅ All pages except Admin
  • Entity Permissions: Edit on audits they manage, View on others

Result: Full control over their audits, visibility into team's work.

Scenario 3: External Auditor​

Setup:

  • Page Access: ✅ Audits only
  • Entity Permissions: View on specific audit

Result: Can only see and read the one audit they're reviewing.

Scenario 4: Former Employee​

Setup:

  • Page Access: ❌ All pages OFF
  • Entity Permissions: None on all entities

Result: Cannot access anything, even via direct links.

Best Practices​

Use the Right Level​

  • Start with View - Safer default
  • Grant Edit only when needed - Reduces risk
  • Use None sparingly - For explicit blocks only

Document Decisions​

When granting Edit access, document why:

  • "Lead auditor for Q4 compliance"
  • "Risk owner for customer data risks"
  • "Workflow manager for SOC2 preparation"

Review Regularly​

  • Quarterly: Review all Edit permissions
  • On role change: Update permissions immediately
  • On departure: Set all to None and disable page access

Troubleshooting​

"I can't see the Audits page" → Check Page Access toggle for Audits

"I can see the list but can't open an audit" → Entity is likely Private with no permission granted

"I can view but not edit" → Permission level is View, need Edit for modifications

"Why does my permission setting not work?" → Check if user is Admin (admins bypass all permissions)