Custom roles and permissions

tools/powersync-dashboard.mdx

@@ -7,7 +7,7 @@ The PowerSync Dashboard is available in [PowerSync Cloud](https://www.powersync.
 
 The dashboard is available here: https://dashboard.powersync.com/
 
-### Hierarchy: Organization, Project, Instance
+## Hierarchy: Organization, Project, Instance
 
 - After successfully [signing up](https://accounts.powersync.com/portal/powersync-signup?s=docs) for PowerSync Cloud, your **PowerSync account** is created.
 - Your account is assigned an **organization** on the [Free pricing plan](https://www.powersync.com/pricing).
@@ -30,27 +30,27 @@ Here is an example of how this hierarchy might be used by a customer:
     - **Instance**: Development
     - **Instance**: Production
 
-### Dashboard Overview
+## Dashboard Overview
 
 The PowerSync Dashboard is organized into three main levels, each providing different functionality:
 
 1. **Organization Level** - Manage projects, team members, organization and billing settings
 2. **Account Level** - Manage your personal account settings and access tokens
 3. **Project & Instance Level** - Configure and monitor your PowerSync instances
 
-### Organization Level
+## Organization Level
 
 URL structure: `https://dashboard.powersync.com/org/{orgId}/projects`
 
 At the organization level, you can manage your PowerSync projects and organization-wide settings. Navigate to your organization to access:
 
 - **Projects** - View all projects in your organization, create new projects, and manage project settings
-- **Team** - Invite team members to your organization, manage user roles, and remove access
+- **Team** - Invite team members to your organization, manage their access with [roles and permissions](#roles-and-permissions), and remove access
 - **Plans & Billing** - View or update your PowerSync subscription plan and manage billing details
 - **Plan Usage** - Monitor usage metrics across all projects in your organization for the current billing cycle
 - **Settings** - Update the organization name
 
-### Account Level
+## Account Level
 
 URL structure: `https://dashboard.powersync.com/account/me`
 
@@ -60,7 +60,7 @@ At the account level, you can manage your personal account settings:
 - **Security** - Reset your password and configure multi-factor authentication (MFA)
 - **Access Tokens** - Create and manage personal access tokens for use with the [CLI](/tools/cli)
 
-### Project & Instance Level
+## Project & Instance Level
 
 URL structure: `https://dashboard.powersync.com/org/{orgId}/project/{projectId}/{instanceId}/{view}`
 
@@ -83,7 +83,7 @@ In the top bar, you'll see a "Connect" button that provides quick access to your
   ![](/images/usage/tools/dashboard-connect-button.png)
 </Frame>
 
-#### Common Tasks
+### Common Tasks
 
 Here are some of the most common tasks you'll perform in the dashboard:
 
@@ -96,10 +96,75 @@ Here are some of the most common tasks you'll perform in the dashboard:
 - **View logs** - Navigate to the **Logs** view to review replication and client sync logs
 - **Monitor metrics** - Navigate to the **Metrics** view to track usage metrics
 
-#### Advanced: Service Version Locking
+### Advanced: Service Version Locking
 
 Customers on our [Team and Enterprise plans](https://www.powersync.com/pricing) can lock their PowerSync Cloud instances to a specific version of the PowerSync Service. This option is available under your instance settings.
 
 Versions are specified as `major.minor.patch`. When locked, only new `.patch` releases will automatically be applied to the instance.
 
 **Downgrade limitations:** Not all downgrade paths are available automatically. If you need to downgrade to an older version, please [contact our team](/resources/contact-us) for assistance.
+
+## Roles and Permissions
+
+A role is a named set of permissions that controls what a member can see and do in your organization. You assign one or more roles to a member when you invite them, and you can change a member's roles at any time. The **Roles** tab on the **Team** page lists the roles available in your organization. System roles are available on every plan, and creating custom roles requires the [Team or Enterprise plan](https://www.powersync.com/pricing).
+
+<Frame caption="The Roles tab on the Team page, listing system and custom roles with their grants and assigned members">
+  ![](/images/usage/tools/dashboard-team-roles.png)
+</Frame>
+
+### System Roles
+
+Every organization includes system roles that you can assign but cannot edit or delete:
+
+- **Owner** - Full access to the organization, its projects, instances, team, and billing.
+- **Developer** - Configure and deploy projects and instances.
+
+You can see the exact grants for any role in the Roles tab. To grant access that differs from the system roles, create a custom role.
+
+### Custom Roles
+
+Custom roles are available on the [Team and Enterprise plans](https://www.powersync.com/pricing).
+
+A custom role is a set of permissions that you choose. Each permission covers one area of the dashboard and has one or more access levels. A higher level includes everything the lower level allows. A role needs at least one permission.
+
+The access levels mean the same thing across every permission:
+
+- **View** gives read-only access to that area. The member can see it but cannot change anything.
+- **Deploy** applies only to Instances. It gives View access plus the ability to deploy changes to an instance, such as updating the sync config and database connections. It does not allow creating or deleting instances.
+- **Manage** gives full access to that area, including creating, editing, and deleting. For Instances, it also includes deploying changes.
+
+The table below lists each permission, its available access levels, and what those levels grant.
+
+| Permission | Access levels | What it grants |
+| --- | --- | --- |
+| Projects | View, Manage | View projects. Manage adds creating, renaming, and deleting projects. |
+| Instances | View, Deploy, Manage | View instances. Deploy adds deploying changes such as sync config and database connections. Manage adds creating and deleting instances. |
+| Instance logs | View | View instance logs. |
+| Alert Rules | View, Manage | View Alert Rules. Manage adds creating, editing, and deleting them. |
+| Notification Rules | View, Manage | View Notification Rules. Manage adds creating, editing, deleting, and testing them. |
+| Private Endpoints | View, Manage | View Private Endpoints. Manage adds creating, editing, and deleting them. |
+| Team | View, Manage | View members. Manage adds inviting and removing members and changing their role assignments. |
+| Billing | View, Manage | View billing details and the current plan. Manage adds updating billing and changing the plan. |
+| Organization settings | Manage | Update organization configuration, such as the organization name. |
+
+Not every permission offers all access levels. Each area shows only the levels that apply to it: Instance logs are read-only (View only), and Organization settings have no separate read-only view (Manage only).
+
+Some permissions depend on others, because access to the parent area is required to reach the child. Instances, Alert Rules, and Notification Rules require at least View on Projects, and Instance logs requires at least View on Instances. The builder adds the required parent permissions for you when you select a dependent one.
+
+<Frame caption="The custom role builder, showing permission rows with access levels and the project scope picker">
+  ![](/images/usage/tools/dashboard-role-builder.png)
+</Frame>
+
+### Project Scope
+
+Permissions fall into two groups. Organization-level permissions (Private Endpoints, Team, Billing, and Organization settings) always apply across the whole organization. Project-level permissions (Projects, Instances, Instance logs, Alert Rules, and Notification Rules) can be scoped to all projects or to a specific set of projects that you choose.
+
+Project scope only applies to a role that includes project-level permissions. A role made up only of organization-level permissions, such as a Billing-only role, applies across the organization regardless of scope.
+
+A project-scoped member is granted their permissions inside the selected projects and has no access outside them. The Manage level on Projects is only available on roles scoped to all projects, since creating and deleting projects is an organization-scoped action.
+
+### How Permissions Appear in the Dashboard
+
+Members can only access the areas and perform the actions that their roles allow. Where a member lacks permission for an action, the related control stays visible but disabled. Opening a page the member cannot view shows a "You do not have permission" message rather than the page content. The dashboard reflects permissions as a convenience. Access is always enforced by the PowerSync backend.
+
+If you need finer-grained control than the current permissions allow, [reach out to us](/resources/contact-us) and describe your use case.