Roles and Permissions
HomeStar uses role-based access control (RBAC) to manage user permissions.
Role Hierarchy
Section titled “Role Hierarchy”Roles are numeric and cumulative — each higher role inherits everything the role below it can do:
viewer (0) < agent (1) < broker (2) < brokerage_owner (3) < admin (4)Role Comparison
Section titled “Role Comparison”| Capability | Agent | Broker | Owner | Admin |
|---|---|---|---|---|
| Listings | ||||
| View own listings | ✓ | ✓ | ✓ | ✓ |
| View all listings | − | ✓ | ✓ | ✓ |
| Edit own listings | ✓ | ✓ | ✓ | ✓ |
| Edit team listings | − | ✓ | ✓ | ✓ |
| Import/export listings | − | − | − | ✓ |
| Leads | ||||
| View assigned leads | ✓ | ✓ | ✓ | ✓ |
| View all leads | − | ✓ | ✓ | ✓ |
| Respond to leads | ✓ | ✓ | ✓ | ✓ |
| Reassign leads | − | ✓ | ✓ | ✓ |
| Export lead data | − | ✓ | ✓ | ✓ |
| Tours | ||||
| View scheduled tours | ✓ | ✓ | ✓ | ✓ |
| Manage own tours | ✓ | ✓ | ✓ | ✓ |
| View all tours | − | − | ✓ | ✓ |
| Configure tour settings | − | − | ✓ | ✓ |
| Profile & Settings | ||||
| Edit own profile | ✓ (approval) | ✓ (approval) | ✓ | ✓ |
| Approve profile changes | − | ✓ | ✓ | ✓ |
| Edit brokerage profile, branding, domains | − | − | ✓ | ✓ |
| Configure MLS data feeds | − | − | ✓ | ✓ |
| Team Management | ||||
| View team members | − | ✓ | ✓ | ✓ |
| Add/remove agents | − | ✓ | ✓ | ✓ |
| Remove or promote a brokerage_owner | − | − | − | ✓ |
| Assign agents to listings | − | ✓ | ✓ | ✓ |
| View team reports | − | ✓ | ✓ | ✓ |
| API & Billing | ||||
| Generate/revoke API keys (own brokerage) | − | − | ✓ | ✓ |
| View billing / Stripe status | − | − | ✓ | ✓ |
| System Administration | ||||
| User management across brokerages | − | − | − | ✓ |
| Create/delete brokerages | − | − | − | ✓ |
| Data imports/exports | − | − | − | ✓ |
| System configuration | − | − | − | ✓ |
| Audit logs | − | − | − | ✓ |
Role Descriptions
Section titled “Role Descriptions”Standard role for real estate professionals managing their own listings and leads.
Dashboard: Shows personal listings, assigned leads, and scheduled tours.
Approval workflow: Profile changes require broker approval before going live.
Screenshot: Agent dashboard view
Broker / Team Lead
Section titled “Broker / Team Lead”For licensed brokers managing day-to-day operations of a brokerage.
Dashboard: Shows team-wide metrics, all listings, and team member activity.
Responsibilities: Hire/fire agents, manage listings, respond to leads, approve agent profile changes.
Restrictions: Cannot edit brokerage branding, MLS data feed credentials, API keys, or a brokerage_owner’s user record. Those belong to the owner.
Screenshot: Broker dashboard view
Brokerage Owner
Section titled “Brokerage Owner”For the business owner of a brokerage. Above broker, scoped to one brokerage.
Dashboard: Everything a broker sees, plus billing and API-key surfaces.
Responsibilities: Edit brokerage profile, branding, logo, custom domains; configure MLS data feeds (credentials); generate/revoke API keys scoped to the brokerage.
Restrictions: Cannot manage other brokerages, cannot create or promote users to brokerage_owner (that remains an admin/platform action), cannot delete the brokerage itself.
Use case: Joe Kroetch of Kroetch Property Group sets branding, manages MLS feed keys, and mints API keys for their integrations. His licensed broker Josh still manages day-to-day agents and listings under the broker role.
Administrator
Section titled “Administrator”Full system access for platform administrators and support staff.
Dashboard: Shows system-wide metrics, all users, and configuration options.
Direct edit access: No approval workflows; changes take effect immediately.
Screenshot: Admin dashboard view
Approval Workflows
Section titled “Approval Workflows”Agent Profile Changes
Section titled “Agent Profile Changes”- Agent edits profile
- Broker receives notification
- Broker reviews and approves/rejects
- Agent receives notification of decision
Suggest mode screenshot: Agent editing in suggest mode
Brokerage Setting Changes
Section titled “Brokerage Setting Changes”- Broker proposes changes to brokerage settings
- Admin receives notification
- Admin reviews and approves/rejects
- Broker receives notification of decision
Suggest mode screenshot: Broker editing brokerage settings
Permission Errors
Section titled “Permission Errors”Users attempting to access restricted areas see clear permission notices.
Example: Broker attempting to access admin-only Tours section:
Role Badges in Documentation
Section titled “Role Badges in Documentation”Throughout this documentation, badges indicate required roles for features:
- Agent — Available to agents, brokers, owners, and admins
- Broker — Broker, owner, and admin
- Owner — Brokerage owner and admin
- Admin — Administrator access required
Related Reference
Section titled “Related Reference”- API Authentication — Role-based API access
- Dashboard Layout — Role-specific dashboard views