coder · stirby · Oct 30, 2024 · Oct 30, 2024
diff --git a/docs/admin/users/groups-roles.md b/docs/admin/users/groups-roles.md
@@ -31,6 +31,30 @@ Roles determine which actions users can take within the platform.
 A user may have one or more roles. All users have an implicit Member role that
 may use personal workspaces.
 
+## Custom Roles (Premium) (Beta)
+
+Starting in v2.16.0, Premium Coder deployments can configure custom roles on the
+[Organization](./organizations.md) level. You can create and assign custom roles
+in the dashboard under **Organizations** -> **My Organization** -> **Roles**.
+
+> Note: This requires a Premium license.
+> [Contact your account team](https://coder.com/contact) for more details.
+
+![Custom roles](../../images/admin/users/roles/custom-roles.PNG)
+
+Clicking "Create custom role" opens a UI to select the desired permissions for a
+given persona.
+
+![Creating a custom role](../../images/admin/users/roles/creating-custom-role.PNG)
+
+From there, you can assign the custom role to any user in the organization under
+the **Users** settings in the dashboard.
+
+![Assigning a custom role](../../images/admin/users/roles/assigning-custom-role.PNG)
+
+Note that these permissions only apply to the scope of an
+[organization](./organizations.md), not across the deployment.
+
 ### Security notes
 
 A malicious Template Admin could write a template that executes commands on the

diff --git a/docs/images/admin/users/roles/assigning-custom-role.PNG b/docs/images/admin/users/roles/assigning-custom-role.PNG
diff --git a/docs/images/admin/users/roles/creating-custom-role.PNG b/docs/images/admin/users/roles/creating-custom-role.PNG
diff --git a/docs/images/admin/users/roles/custom-roles.PNG b/docs/images/admin/users/roles/custom-roles.PNG