> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage custom roles
> This page describes how administrators can add, modify, and remove custom roles
export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
if (link) {
return
Beta
;
}
return
Beta feature
;
};
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
This guide is intended for users with the Admin role in ClickHouse Cloud.
ClickHouse Cloud customers may select from pre-defined system roles or create custom roles to assign to users. For more information on system roles and their associated permissions, review [Console roles and permissions](/products/cloud/reference/security/console-roles). This guide provides details for managing custom roles.
Create custom roles
Custom roles can contain a combination of organization, service, and database permissions. Permissions may be applied to all or a subset of services and databases.
From the services page, select the name of your organization. Select the `Users and roles` menu item from the popup menu.
Select the Roles tab} id="roles-tab">
Select the `Roles` tab from the top middle of the screen.
Select Create new role from the upper right} id="create-new-role">
Select the `Create new role` button in the upper right of the screen.
Enter a descriptive role name. This will be the name you will see when assigning roles to users and API keys.
Click Allow and select permission scope} id="scope-permissions">
Click the `Allow` button and select from Organization, Service, and/or Database permissions. For a description of all permissions, see [Console roles and permissions](/products/cloud/reference/security/console-roles).
Ensure users who will log into the console have a minimum of Organization > Access organization permissions.
**Data Sources tab access**
To access the **Data Sources** tab, the role currently requires the `Manage and Delete Selected Services` permission.
Review permissions assigned to your new role before finalizing. Click `Create role` when done.
Manage database roles (beta)
In addition to console permissions, custom roles can include data permissions that control access to the databases of selected services. This lets you manage console and database access in one place instead of maintaining separate roles in each database.
This feature is in beta and is available for services running ClickHouse version 26.4 and above.
When you add data permissions to a custom role, ClickHouse Cloud creates a matching role in each selected service, prefixed with `cloud:`. For example, a custom role named `readonly` appears in the database as `cloud:readonly`. Members of the custom role receive these database permissions when they connect to the service through SQL console passwordless authentication.
Roles assigned manually in the database using the [`sql-console-role:` naming convention](/products/cloud/guides/security/cloud-access-management/manage-database-users#sql-console-users-and-roles) take precedence over roles assigned through the console.
[Create a custom role](#create-custom-role) or edit an existing one. In the role dialog, click the `Allow permissions` button and select `Data`.
Select the service the permissions apply to. Add more services to apply permissions across multiple services.
Select `Read-only`, `Admin`, or `Custom` access. With `Custom` access, define specific data access permissions using ClickHouse [`GRANT` statements](/reference/statements/grant).
Click `Create role`. The database roles are created in the selected services.
Verify database roles
Roles managed through the console are created in the database with the `cloud:` prefix and the `cloud` storage type. To list them, query the `system.roles` table in the service:
```sql theme={null}
SELECT * FROM system.roles;
```
```response theme={null}
┌─name───────────┬─id───────────────────────────────────┬─storage─┐
│ cloud:readonly │ 9a4910f4-abcf-4904-466a-717c8c75ac42 │ cloud │
└────────────────┴──────────────────────────────────────┴─────────┘
```
Update custom roles
Custom roles may be updated after they're created. Users will lose any permissions removed from the role and will gain any permissions added.
User permissions are additive. If a user has permission to perform an operation as part of multiple roles, they may not immediately lose access if permission is removed from only one role.
1. Access organization settings and select `Users and roles`
2. Select the `Roles` tab
3. Select the three dots next to the role you would like to update
4. Select `Edit`
5. Modify the permissions
6. Select `Edit role`
Delete custom roles
Custom roles may be deleted at any time.
You must have at least one user in the organization with administrative permissions. If deleting the role removes administrative permissions from the last user, you can't delete it. To resolve this, assign at least one user the Admin system role before deleting the custom role.
1. Access organization settings and select `Users and roles`
2. Select the `Roles` tab
3. Select the three dots next to the role you would like to delete
4. Review the users and API keys that will lose access when the role is removed. Adjust assignments as needed.
5. Select `Delete role` to complete the process