RBAC and Permissions

RBAC and Permissions

Matrix 1: Role Levels & Scopes

Role Level	Scope	What It Controls	Example Use Cases	Can See/Manage
App-level	Entire application	All tenants, all data	Surkyl employees, support team	Everything across all tenants
Tenant-level	Single tenant	All workspaces in tenant	Company admins, billing managers	All workspaces/users in their tenant
Workspace-level	Single workspace	Single workspace & its content	Project editors, content creators	Only their specific workspace

Matrix 2: System Roles (Pre-defined)

App-Level System Roles

Role Name	Scope	Description	Key Permissions	Typical User
Super Admin	App	Full system access	app.admin.full, app.users.manage, app.tenants.manage	Surkyl founders, CTO
Support Agent	App	View-only for support	app.support.view, tenant.workspaces.view	Customer support team
Platform Engineer	App	Manage infrastructure	app.tenants.manage, app.users.view	DevOps team

Tenant-Level System Roles

Role Name	Scope	Description	Key Permissions	Typical User
Tenant Owner	Tenant	Full tenant control	tenant.admin.full, all tenant permissions	Company founder/CEO
Tenant Admin	Tenant	Admin without billing	tenant.members.manage, tenant.workspaces.view, tenant.settings.manage	Company CTO/admin
Billing Manager	Tenant	Billing only	tenant.billing.manage, tenant.billing.view	Finance team
Tenant Member	Tenant	Basic access	tenant.workspaces.view, workspace.view	Regular employees

Workspace-Level System Roles

Role Name	Scope	Description	Key Permissions	Typical User
Workspace Owner	Workspace	Full workspace control	workspace.admin.full, all workspace permissions	Project lead
Workspace Editor	Workspace	Edit all content	project.*, page.* (create/read/update/delete)	Content team
Workspace Viewer	Workspace	Read-only access	workspace.view, project.read, page.read	Stakeholders, clients
Content Creator	Workspace	Create & edit own content	project.create, page.create, page.update (own)	Freelancers, contractors
Publisher	Workspace	Can publish to production	project.publish, page.publish	QA team, senior editors

Matrix 3: Permission Structure

App-Level Permissions

Permission Code	Name	Resource	Action	Description	Used By Roles
app.admin.full	Full App Admin	ALL	admin	Complete system access	Super Admin
app.users.manage	Manage All Users	user	manage	CRUD any user	Super Admin
app.tenants.manage	Manage All Tenants	tenant	manage	CRUD any tenant	Super Admin, Platform Engineer
app.tenants.view	View All Tenants	tenant	read	View any tenant	Super Admin, Support Agent
app.support.view	Support View	ALL	view	View for support	Support Agent
app.analytics.view	View Analytics	analytics	read	Global analytics	Super Admin, Support Agent

Tenant-Level Permissions

Permission Code	Name	Resource	Action	Description	Used By Roles
tenant.admin.full	Tenant Admin	ALL	admin	Full tenant access	Tenant Owner
tenant.settings.manage	Manage Settings	tenant	manage	Edit tenant settings	Tenant Owner, Tenant Admin
tenant.members.invite	Invite Members	member	invite	Invite users to tenant	Tenant Owner, Tenant Admin
tenant.members.manage	Manage Members	member	manage	Edit member roles	Tenant Owner, Tenant Admin
tenant.members.view	View Members	member	read	View team members	All tenant roles
tenant.workspaces.create	Create Workspaces	workspace	create	Create new workspaces	Tenant Owner, Tenant Admin
tenant.workspaces.view	View All Workspaces	workspace	read	View all workspaces	Tenant Owner, Tenant Admin, Tenant Member
tenant.workspaces.manage	Manage All Workspaces	workspace	manage	Edit/delete any workspace	Tenant Owner, Tenant Admin
tenant.billing.view	View Billing	billing	read	View billing info	Tenant Owner, Billing Manager
tenant.billing.manage	Manage Billing	billing	manage	Update payment methods	Tenant Owner, Billing Manager
tenant.roles.manage	Manage Custom Roles	role	manage	Create/edit custom roles	Tenant Owner, Tenant Admin

Workspace-Level Permissions

Permission Code	Name	Resource	Action	Description	Used By Roles
workspace.admin.full	Workspace Admin	ALL	admin	Full workspace access	Workspace Owner
workspace.settings.manage	Manage Settings	workspace	manage	Edit workspace settings	Workspace Owner
workspace.view	View Workspace	workspace	read	View workspace	All workspace roles
workspace.members.invite	Invite Members	member	invite	Invite to workspace	Workspace Owner, Workspace Editor
workspace.members.manage	Manage Members	member	manage	Edit member roles	Workspace Owner
project.create	Create Projects	project	create	Create new projects	Workspace Owner, Editor, Content Creator
project.read	View Projects	project	read	View projects	All workspace roles
project.update	Edit Projects	project	update	Edit project details	Workspace Owner, Editor, Content Creator
project.delete	Delete Projects	project	delete	Delete projects	Workspace Owner, Editor
project.publish	Publish Projects	project	publish	Publish to production	Workspace Owner, Publisher
page.create	Create Pages	page	create	Create new pages	Workspace Owner, Editor, Content Creator
page.read	View Pages	page	read	View pages	All workspace roles
page.update	Edit Pages	page	update	Edit page content	Workspace Owner, Editor, Content Creator
page.delete	Delete Pages	page	delete	Delete pages	Workspace Owner, Editor
page.publish	Publish Pages	page	publish	Publish pages	Workspace Owner, Publisher

Matrix 4: User-Defined Role Examples

Example 1: Marketing Agency Roles

Custom Role Name	Scope	Permissions	Use Case
Client Manager	Tenant	tenant.members.invite, tenant.workspaces.view, workspace.view	Agency staff who manage clients
Designer	Workspace	page.create, page.read, page.update, project.read	Create designs, can’t publish
Copywriter	Workspace	page.create, page.read, page.update (text only)	Write content
Account Manager	Workspace	workspace.view, project.read, page.read, workspace.members.invite	Client-facing, read-only + invite
Production Lead	Workspace	All workspace permissions except billing.*	Manages production team

Example 2: SaaS Company Roles

Custom Role Name	Scope	Permissions	Use Case
Engineering Lead	Tenant	tenant.workspaces.create, tenant.workspaces.view, workspace.admin.full	Create workspaces for projects
Product Manager	Workspace	project.*, page.read, workspace.members.invite	Manage product workspace
QA Tester	Workspace	project.read, page.read, project.publish, page.publish	Test and approve releases
Documentation Writer	Workspace	page.create, page.read, page.update, page.publish	Technical docs
External Contractor	Workspace	project.create, project.read, project.update, page.create, page.read, page.update	Temporary access, no delete

Example 3: Education Platform Roles

Custom Role Name	Scope	Permissions	Use Case
Course Instructor	Workspace	workspace.admin.full (within their course workspace)	Manages their course
Teaching Assistant	Workspace	page.create, page.read, page.update, project.read	Helps with course content
Student	Workspace	workspace.view, page.read	View course materials
Guest Lecturer	Workspace	page.create, page.read (limited time)	Create guest content

Matrix 5: Role → Permission Mapping

Super Admin (App-Level)

Permission Category	Permissions Granted
App	app.admin.full, app.users.manage, app.tenants.manage, app.support.view, app.analytics.view
Tenant	All tenant permissions (can access any tenant)
Workspace	All workspace permissions (can access any workspace)
Total Permissions	~50+ permissions

Tenant Owner (Tenant-Level)

Permission Category	Permissions Granted
App	None
Tenant	tenant.admin.full, tenant.settings.manage, tenant.members.manage, tenant.members.invite, tenant.workspaces.create, tenant.workspaces.view, tenant.workspaces.manage, tenant.billing.view, tenant.billing.manage, tenant.roles.manage
Workspace	Can access all workspaces in their tenant (inherited)
Total Permissions	~15-20 permissions

Tenant Admin (Tenant-Level)

Permission Category	Permissions Granted
App	None
Tenant	tenant.settings.manage, tenant.members.manage, tenant.members.invite, tenant.members.view, tenant.workspaces.create, tenant.workspaces.view, tenant.workspaces.manage, tenant.roles.manage
Workspace	Can access all workspaces in their tenant (inherited)
Total Permissions	~10-12 permissions

Workspace Owner (Workspace-Level)

Permission Category	Permissions Granted
App	None
Tenant	None
Workspace	workspace.admin.full, workspace.settings.manage, workspace.view, workspace.members.invite, workspace.members.manage, project.*, page.* (all CRUD + publish)
Total Permissions	~12-15 permissions

Workspace Editor (Workspace-Level)

Permission Category	Permissions Granted
App	None
Tenant	None
Workspace	workspace.view, project.create, project.read, project.update, project.delete, page.create, page.read, page.update, page.delete
Total Permissions	~8-10 permissions

Workspace Viewer (Workspace-Level)

Permission Category	Permissions Granted
App	None
Tenant	None
Workspace	workspace.view, project.read, page.read
Total Permissions	3 permissions

Matrix 6: Permission Inheritance & Resolution

User Has	Checking Permission On	Result	Why
App-level Super Admin	Any tenant	✅ GRANTED	App-level roles can access anything
App-level Support Agent	Workspace in Tenant A	✅ GRANTED	Has app.support.view which allows viewing
Tenant-level Tenant Owner	Workspace in their tenant	✅ GRANTED	Tenant admins inherit workspace access
Tenant-level Tenant Owner	Workspace in different tenant	❌ DENIED	Tenant roles are scoped to their tenant
Workspace-level Workspace Editor	Project in their workspace	✅ GRANTED	Has project.update permission
Workspace-level Workspace Editor	Project in different workspace	❌ DENIED	Workspace roles are scoped to their workspace
Workspace-level Workspace Viewer	Publish a page	❌ DENIED	Viewer role doesn’t have page.publish
User with permission override DENY	Even with role granting permission	❌ DENIED	Overrides take precedence over roles
User with permission override ALLOW	Without any role	✅ GRANTED	Overrides grant direct access

Matrix 7: Real-World User Journey Examples

Example 1: Marketing Agency - “Digital Spark Agency”

User	Email	App Role	Tenant Role	Workspace Roles	What They Can Do
Sarah (Agency Owner)	[email protected]	None	Tenant Owner	Owner on all workspaces	Everything in Digital Spark tenant
Mike (Account Manager)	[email protected]	None	Tenant Admin	None (can access all via tenant role)	Manage team, view all client workspaces
Lisa (Designer)	[email protected]	None	Tenant Member	Editor on “Nike Campaign” workspace	Design pages for Nike only
John (Copywriter)	[email protected]	None	Tenant Member	Editor on “Nike Campaign” & “Adidas Campaign”	Write content for both clients
Client: Nike CMO	cmothenike.com	None	None	Viewer on “Nike Campaign”	View Nike workspace only (read-only)

Example 2: SaaS Startup - “BuildFast Inc”

User	Email	App Role	Tenant Role	Workspace Roles	What They Can Do
Emma (CEO)	[email protected]	None	Tenant Owner	Owner on all	Everything in BuildFast tenant
Alex (CTO)	[email protected]	None	Tenant Admin	Owner on “Engineering” workspace	Manage engineering workspace fully
Priya (PM)	[email protected]	None	Tenant Member	Editor on “Product” workspace	Manage product specs
Dan (Engineer)	[email protected]	None	Tenant Member	Editor on “Engineering”, Viewer on “Product”	Code in Engineering, view Product roadmap
Amy (Contractor)	[email protected]	None	None	Content Creator on “Marketing”	Create marketing content only

Example 3: Surkyl Internal - Platform Team

User	Email	App Role	Tenant Role	Workspace Roles	What They Can Do
You (VivinMeth)	[email protected]	Super Admin	N/A	N/A	Everything everywhere
Support Agent	[email protected]	Support Agent	N/A	N/A	View any tenant/workspace for support
DevOps Engineer	[email protected]	Platform Engineer	N/A	N/A	Manage infrastructure, create tenants

Matrix 8: Permission Check Decision Tree

Step	Question	If YES	If NO
1	Is there a permission override for this user+resource?	Use override (ALLOW/DENY)	Continue to step 2
2	Does user have app-level role with this permission?	✅ GRANT	Continue to step 3
3	Is this a tenant-scoped resource?	Continue to step 4	Continue to step 5
4	Does user have tenant-level role with this permission in this tenant?	✅ GRANT	Continue to step 5
5	Is this a workspace-scoped resource?	Continue to step 6	❌ DENY
6	Does user have workspace-level role with this permission in this workspace?	✅ GRANT	❌ DENY

Matrix 9: Custom Role Creation Scenarios

Scenario: Agency wants “Client Reviewer” role

Step	Action	Details
1	Choose scope	Workspace-level (client-specific)
2	Name role	”Client Reviewer”
3	Select permissions	workspace.view, project.read, page.read, page.update (add comments)
4	Save role	Role ID created in tenant
5	Assign to users	Assign client contacts to their workspace with this role

Scenario: SaaS wants “Limited Engineer” role

Step	Action	Details
1	Choose scope	Workspace-level
2	Name role	”Junior Developer”
3	Select permissions	project.read, project.update, page.read, page.update (no delete, no publish)
4	Save role	Role ID created
5	Assign to users	Assign junior developers
6	Set expiration	Optional: Set 3-month probation period

Matrix 10: Permission Code Naming Convention

Pattern	Example	Breakdown
{scope}.{resource}.{action}	workspace.project.create	Workspace scope, project resource, create action
{scope}.admin.full	tenant.admin.full	Full admin at tenant scope
{scope}.{resource}.manage	tenant.members.manage	Multiple actions (CRUD) on resource

Naming Examples

Permission Code	Scope	Resource	Action	Meaning
app.admin.full	app	(all)	admin	Complete app access
tenant.settings.manage	tenant	settings	manage	Edit tenant settings
workspace.view	workspace	workspace	read	View workspace
project.create	workspace	project	create	Create projects
page.publish	workspace	page	publish	Publish pages to production
tenant.billing.view	tenant	billing	read	View billing information

Summary: How It All Connects

USER
  │
  ├─[has]→ APP ROLE(s)
  │         └─[contains]→ APP-LEVEL PERMISSIONS
  │                        (access to all tenants)
  │
  ├─[has]→ TENANT ROLE(s) in Tenant A, B, C...
  │         └─[contains]→ TENANT-LEVEL PERMISSIONS
  │                        (access to all workspaces in that tenant)
  │
  ├─[has]→ WORKSPACE ROLE(s) in Workspace X, Y, Z...
  │         └─[contains]→ WORKSPACE-LEVEL PERMISSIONS
  │                        (access to that specific workspace)
  │
  └─[has]→ PERMISSION OVERRIDES (optional)
            └─[grants/denies]→ SPECIFIC PERMISSIONS on SPECIFIC RESOURCES
                                (highest priority)

PERMISSION CHECK FLOW:
1. Check permission overrides first (if exists, use that)
2. Check app-level roles (if granted, allow)
3. Check tenant-level roles (if granted in this tenant, allow)
4. Check workspace-level roles (if granted in this workspace, allow)
5. Otherwise, deny

This system gives you maximum flexibility while remaining performant and easy to understand. Users can have multiple roles at different scopes, and custom roles can be created at any scope level! 🎯