Roles & Permissions

Every workspace supports multiple members, each assigned one of four hierarchical roles. This page documents exactly what each role can access, how permissions are enforced, and the rules around member management.

Role Hierarchy

member → agent → admin → owner

Each role inherits all permissions of the roles below it. The hierarchy is enforced consistently across both apps (admin and web) using the same ordered comparison:

const ROLE_HIERARCHY: WorkspaceMemberRole[] = ['member', 'agent', 'admin', 'owner']

function hasMinimumRole(userRole, minRole): boolean {
  return ROLE_HIERARCHY.indexOf(userRole) >= ROLE_HIERARCHY.indexOf(minRole)
}

Role Definitions

Member

Typical persona: Transaction coordinator, assistant, or client with limited dashboard access.

• View the dashboard, My Listings, and Browse MLS pages
• View workspace members list
• View workspace settings (read-only)
• View sync run history and import task status
• Cannot edit listings, branding, website pages, or settings

Agent

Typical persona: Junior agent, marketing team member, or the primary listing agent.

Everything a member can do, plus:

• Create, edit, and manage listings and photos
• Edit landing pages
• Edit website pages (Home, Listings, About, Contact)
• Edit branding (logos, colors, fonts), agent profile, and SEO settings
• Manage service areas and compliance profiles
• View and test the MLS data source connection
• Upload assets (photos, videos, hero media)

Admin

Typical persona: Team lead, office manager, or tech-savvy operations person.

Everything an agent can do, plus:

• Invite, update, and remove team members (agents and members only)
• Edit workspace settings (name, slug, configuration)
• Manage custom domains
• Configure and run MLS sync operations
• Create, edit, and run import tasks
• Manage field mappings
• Cancel sync runs
• View system health
• Manage featured listings

Owner

Typical persona: The primary agent or brokerage principal who owns the workspace.

Everything an admin can do, plus:

• Modify or remove admins (admins cannot modify each other)
• Only role that cannot be removed by other workspace members
• Exactly one owner per workspace (set at creation time, transferred only by platform admins)

Dashboard Navigation Access

The web app sidebar filters navigation links based on the user's role. This table shows which sections are visible to each role:

Source: apps/web/src/components/dashboard/dashboard-shell.tsx (lines 60-103).

Admin API Permissions

All admin API routes enforce a minimum role via requireWorkspaceAccess(workspaceId, minRole). If the user does not meet the minimum role, the route returns 403 Forbidden.

Workspace Routes (minimum role: member)

These routes allow any workspace member to read data:

Workspace Routes (minimum role: admin)

These routes require admin or owner for write operations:

Web App Dashboard API Permissions

The web app uses canWrite() (agent+), isAgent() (agent+), and isAdmin() (admin+) for write operations:

Platform Admin Routes

These routes are entirely separate from workspace membership and require platform admin status:

Member Management Rules

Who Can Invite

Only admin and owner roles can send invitations, enforced by the canManageMembers() check:

function canManageMembers(role: WorkspaceMemberRole): boolean {
  return role === 'owner' || role === 'admin'
}

Invitable Roles

The owner role cannot be assigned via invitation. The invitation role constraint in the database enforces this:

CHECK (role IN ('admin', 'agent', 'member'))

Role Modification Rules

The canModifyMember() function controls who can change or remove whom:

Key constraints:

• Owners cannot modify other owners -- prevents removing the workspace owner
• Admins cannot modify other admins -- prevents lateral privilege escalation
• Nobody can self-demote below their target's role -- enforced by the actor/target comparison

Owner Protection

• There is exactly one owner per workspace (set during workspace creation)
• Owners cannot be removed or demoted through the member management API
• Ownership can only be transferred by a platform admin via the /transfer-ownership endpoint

Platform Admin

Platform admin is a separate access system, independent of workspace membership.

How It Works

• Platform admins are stored in the platform_admins table (not workspace_members)
• When a platform admin accesses any workspace, they receive owner-level permissions regardless of whether they are a workspace member
• The isPlatformAdmin flag on the auth result distinguishes platform admin access from actual workspace membership

Platform Role Hierarchy

admin < super_admin

Granting Platform Admin

Only a super_admin can grant or revoke platform admin status via the platform admins API. This prevents privilege escalation -- a platform admin cannot promote themselves to super_admin.

Related Documentation

• Security Architecture -- Authentication, RLS, token encryption, and rate limiting
• API Reference -- Full endpoint documentation
• Database Schema -- Table definitions and constraints