> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage Users, Roles, and Service Accounts
export const InternalLink = ({version, path = "", children, ...props}) => {
let detectedVersion = version || "stable";
if (typeof window !== 'undefined' && !version) {
const match = window.location.pathname.match(/\/docs\/([^/]+)/);
if (match) {
detectedVersion = match[1];
}
}
const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
return
{children}
;
};
This page details procedures for managing CockroachDB Cloud access to CockroachDB Cloud. Before proceeding, it is recommended to review the concepts related to the two levels of CockroachDB Cloud access management model (the organization level and the SQL level in a cluster), which are detailed in CockroachDB Cloud Access Management Overview and FAQ.
Access management tasks for the organization level are performed in the CockroachDB Cloud console **Access Management** page, found at `https://cockroachlabs.cloud/access`. This page allows organization administrators to invite users to the CockroachDB Cloud organization, create service accounts, and manage the access roles assigned to both. Users with Cluster Admin role on a cluster can also manage the access role assignments on that cluster. Roles can be assigned at different scopes (levels) of the resource hierarchy.
Access management tasks for SQL level in a cluster are a bit distributed. SQL users on particular clusters can be created in the console's 'SQL user' page for a specific cluster, found at `https://cockroachlabs.cloud/cluster//users`, or with the `ccloud` command line utility's `cluster user create` command, or with a SQL client. However, the SQL roles that govern permissions in the cluster for SQL users must be managed with a SQL client. Furthermore, SQL users created with the console or with `ccloud` utility are granted the `admin` SQL role on the cluster by default; this makes it important from a security perspective to immediately modify this user if needed, revoking the `admin` role and replacing it with a SQL role with privileges required for its task, according to the [principle of least privilege](https://wikipedia.org/wiki/Principle_of_least_privilege).
See [Manage SQL users on a cluster](#manage-sql-users-on-a-cluster)
## Manage your organizations
An **organization** allows you to manage your clusters under a shared billing account and collaborate with team members. You can belong to multiple organizations, like a personal organization, an enterprise organization for evaluating CockroachDB Cloud, and another enterprise organization with CockroachDB Cloud credits to map to all application clusters.
To switch to a different organization:
1. Log in to the console at `https://cockroachlabs.cloud/` or your organization's custom domain.
2. From the drop-down box in the top-right corner, select the organization you want to access.
The settings and information about the organization are found on the **Information** page. The organization ID and organization label used by the `ccloud` CLI are listed on that page.
## Manage an organization's users
### Invite team members to an organization
An Organization Admin can invite team members to CockroachDB Cloud. To invite team members:
1. If you are a member of multiple organizations, navigate to the organization to which you want to invite a team member. You can navigate to the correct organization by using the drop-down box in the top-right corner.
2. On the **Access Management** page, under the *Members* tab, click **Invite**.
3. In the **Email Address** field, enter the email address of the team member you want to invite. By default, a user is assigned the Organization member role; this default role adds no permissions. After the user is invited, you will be able to [assign additional roles](#change-a-team-member’s-roles).
4. If required, you could invite multiple users at the same time by adding a row per email address using **+ Add Member**.
It is also possible to enable autoprovisioning for your organization, which removes the need to invite team members.
### Change a team member's roles
In the CockroachDB Cloud Console, users must be assigned **roles** that allow them to perform actions.
The following table describes the high level permissions given by each CockroachDB Cloud user role. Permissions are additive, so a user with multiple roles is given all permissions in each area across all assigned roles.
| | Org. Member | Org. Admin | Billing Coord. | Billing Viewer | Cluster Creator | Cluster Operator | Cluster Admin | Cluster Developer | Cluster Monitor | Metrics Viewer | Folder Admin | Folder Mover |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **User/Access Management** | | | | | | | | | | | | |
| Assign and revoke roles | — | ✓ | — | — | — | — | ✓ | — | — | — | — | — |
| Assign Cloud user and service account roles | — | — | — | — | — | — | ✓ | — | — | — | — | — |
| Manage SQL users | — | — | — | — | — | — | ✓ | — | — | — | — | — |
| Manage Cloud users and service accounts | — | ✓ | — | — | — | — | ✓ | — | — | — | — | — |
| Apply roles at the folder scope | — | — | — | — | — | — | — | — | — | — | ✓ | — |
| **Cluster & Infrastructure** | | | | | | | | | | | | |
| Create cluster or private cluster | — | — | — | — | ✓ | — | — | — | — | — | — | — |
| Create / edit / delete cluster | — | — | — | — | — | — | ✓ | — | — | — | — | — |
| Edit / delete clusters created by this user | — | — | — | — | ✓ | — | — | — | — | — | — | — |
| Create / delete / manage folders | — | — | — | — | — | — | — | — | — | — | ✓ | — |
| Move cluster between folders | — | — | — | — | — | — | — | — | — | — | — | ✓ |
| Scale nodes | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| Upgrade CockroachDB | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| Configure maintenance windows | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| Use the Cloud Terraform provider | — | — | — | — | ✓ | — | ✓ | — | — | — | — | — |
| **Monitoring & Observability** | | | | | | | | | | | | |
| View cluster details | — | — | — | — | — | — | — | ✓ | — | — | — | — |
| View audit logs | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| View insights | — | — | — | — | — | ✓ | ✓ | — | ✓ | — | — | — |
| View jobs | — | — | — | — | — | ✓ | ✓ | — | ✓ | — | — | — |
| View sql activity | — | — | — | — | — | ✓ | ✓ | — | ✓ | — | — | — |
| View metrics | — | — | — | — | — | ✓ | ✓ | — | — | ✓ | — | — |
| Send test alerts | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| Access DB console | — | — | — | — | — | ✓ | ✓ | ✓ | — | — | — | — |
| **Security** | | | | | | | | | | | | |
| Configure cluster SSO | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| Manage egress perimeter controls | — | — | — | — | — | — | ✓ | — | — | — | — | — |
| Manage network authorization | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| View PCI status | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| **Database & Data** | | | | | | | | | | | | |
| Manage databases | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| View / restore backups | — | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
| **Billing & Licensing** | | | | | | | | | | | | |
| Manage billing | — | — | ✓ | — | — | — | — | — | — | — | — | — |
| View billing details | — | — | ✓ | ✓ | — | — | — | — | — | — | — | — |
| Manage email alerts | — | ✓ | — | — | — | — | — | — | — | — | — | — |
| Manage CockroachDB Self-Hosted cluster licenses | — | ✓ | — | — | — | — | — | — | — | — | — | — |
Some roles can be assigned to users at specific levels of scope to provide more granular permission control:
| **Scope level** | **Description** | **Applicable roles** |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Organization` | Applies to the entire CockroachDB Cloud organization, including all clusters and folders | `Cluster Operator`, `Cluster Admin`, `Cluster Creator`, `Cluster Developer`, `Cluster Monitor`, `Metrics Viewer`, `Billing Coordinator`, `Billing Viewer`, `Organization Admin`, `Folder Admin`, `Folder Mover` |
| `Folder` | Applies to clusters within a specific folder. Only available as a selectable scope if folders have been created within the organization by a user with the `Folder Admin` role | `Cluster Operator`, `Cluster Admin`, `Cluster Creator`, `Cluster Developer`, `Cluster Monitor`, `Metrics Viewer`, `Folder Admin`, `Folder Mover` |
| `Cluster` | Applies to a specific cluster | `Cluster Operator`, `Cluster Admin`, `Cluster Developer`, `Cluster Monitor`, `Metrics Viewer` |
To edit a user's role, perform the following steps:
1. On the **Access Management** page, locate the team member whose role you want to change. The **Role** column lists current roles assigned to each user.
2. In the row for the target member, click the three-dots **Action** button and select **Edit Roles**.
3. A number of fine-grained roles can be assigned to a given user. Each role is represented by a row. Each row has a **scope**, which is one of **Organization**, the name of a particular folder, or the name of a particular cluster. If the role is Cluster Admin, Cluster Operator, or Cluster Developer, assigning it at the organization scope means that it applies to all clusters in the organization.
When editing roles for a group in the **Groups** tab, the fields for that group's inherited roles are read-only, because inherited roles cannot be edited directly. Instead, you must either remove the role from the parent group from which it is inherited, or remove the member from the parent group.
An Organization Admin can revoke the Organization Admin role from their own user, but cannot subsequently re-assign the administrator role to themselves.
### Remove a team member
1. On the **Access Management** page, locate the team member you want to remove.
2. In the **Action** column, click the three dots to view the allowed actions.
3. Click **Remove Member** and confirm.
### Revoke a pending invite
1. On the **Access Management** page, locate the team member whose pending invite you want to revoke.
2. In the **Action** column, click the three dots to view the allowed actions.
3. Click **Revoke Invite**.
### Delete an email address
This is not currently available through the CockroachDB Cloud Console. To remove an email address from your account, [contact Support](https://support.cockroachlabs.com/).
### Delete an organization
Deleting an organization will delete all clusters and user data within the organization. This action cannot be reversed. To delete a single cluster instead, see Cluster Management.
If you are sure you want to delete the organization, proceed with the following steps:
1. Navigate to the **Information** page for the organization you want to delete.
2. Click **Delete**.
3. Enter the name of the organization.
4. Click **Delete**.
You will be automatically logged out of your account.
## Manage service accounts
The access management model for service accounts is unified with the [user model](#manage-an-organization’s-users). This means that service accounts may have all of the same access roles. However, service accounts and users still differ in the actions they can perform: only users can access the console, and only service accounts can access the API. The console and API differ in functionality.
### Create a service account
1. On the **Access Management** page, select the **Service Accounts** tab.
2. Click **Create**.
3. Enter a **Account name** and **Description**.
4. Create and export an **API key**.
5. Confirm creation of the service account.
Service accounts, like users, are given only the **Organization Member** role by default upon creation. This role assigns no access in the organization. After it is created, you can assign additional roles to the service account.
### Edit roles on a service account
1. On the **Access Management** page, select the **Service Accounts** tab.
2. In the row for the target service account, click, click the three-dots **Action** button and select **Edit Roles**.
3. A number of fine-grained roles can be assigned to a given service account. These are the same roles that can be assigned to users. Each role is represented by a row. Each row has a **scope**, which is either **Organization** or the name of a particular cluster. If the role is Cluster Admin, Cluster Operator, or Cluster Developer, assigning it at the organization scope means that it applies to all clusters in the organization.
The fields for a group's inherited roles are read-only, because inherited roles cannot be edited directly. Instead, you must either remove the role from the parent group from which it is inherited, or remove the member from the parent group.
### API access
Each service account can have one or more API keys. API keys are used to authenticate and authorize service accounts when using the API. All API keys created by the account are listed under **API Access**.
We recommend creating service accounts with the [principle of least privilege](https://wikipedia.org/wiki/Principle_of_least_privilege), and giving each application that accesses the API its own service account and API key. This allows fine-grained access to the cluster.
#### Create API keys
To create an API key:
1. On the **Access Management** page, select the **Service Accounts** tab.
2. Click the service account for which you want to create an API key to bring up the **Service Account Details** page.
3. Click **Create API Key**.
4. Enter the **API key name** and click **Create**. The name should identify how the API key will be used. For example, you could name your API key for the application that will use the key.
5. Copy the **Secret key** and store it in a secure location. There is a **Copy** button to the right of the displayed secret key that will copy the secret key to your OS clipboard.
The secret key contains the API key and secret. It should never be shared or publicly accessible. Anyone with the secret key can use the API with the permissions of the service account.
The secret key will not be available after closing the **Create API key** dialog. If you have lost your secret key, you should [delete the API key](#delete-api-keys) and create a new one.
6. Click **Done**.
#### Delete API keys
To delete an API key associated with a service account:
1. On the **Access Management** page, select the **Service Accounts** tab.
2. Click the service account for which you want to create an API key to bring up the **Service Account Details** page.
3. Click the **Action** button for the API key ID in the **API Access** table.
4. Select **Delete**.
5. In the **Delete API key** dialog enter the name of the service account to confirm the delete operation, then click **Delete**.
#### Edit API key names
To change the API key name for an existing API key:
1. On the **Access Management** page, select the **Service Accounts** tab.
2. Click the service account for which you want to create an API key to bring up the **Service Account Details** page.
3. Find the API key ID in the **API Access** table.
4. Click the **Action** button.
5. Select **Edit**.
6. In the **Edit API key name** dialog modify the API key name and click **Save changes**.
## Manage SQL users on a cluster
* [View all SQL users in your cluster](#view-all-sql-users-in-your-cluster)
* [Change a SQL user's password](#change-a-sql-user’s-password)
* [Remove a SQL user](#remove-a-sql-user)
### Create a SQL user
By default, a new SQL user created using the UI or Cloud API is granted the SQL `admin` role. An `admin` SQL user has full privileges for all databases and tables in the cluster, and can create additional SQL users and manage their privileges. When possible, it is best practice to limit each user's privileges to the minimum necessary for their tasks, in keeping with the [Principle of Least Privilege (PoLP)](https://wikipedia.org/wiki/Principle_of_least_privilege).
Refer to: Manage SQL users on a cluster
Only Organization Admins and Cluster Admins can create SQL users using the Cloud Console or API. These SQL users default to the `Admin` role. For granular provisioning of SQL user privileges, refer to documentation on using the cluster's SQL interface.
1. Navigate to your cluster's **SQL Users** page in the **Security** section of the left side navigation.
2. In the left navigation bar, click **SQL Users**.
3. Click **Add User**. The **Add User** dialog displays.
4. Enter a username and click **Generate & Save Password**.
5. Copy the generated password to a secure location, such as a password manager.
6. Click **Close**.
Currently, all new users are created with SQL admin privileges. For more information and to change the default settings, see [Grant privileges to a SQL user](#grant-privileges-to-a-sql-user) and [Use SQL roles to manage access](#use-sql-roles-to-manage-access).
Once you have connected to the cluster's SQL client, you can create a new user.
To create a new user, use the `CREATE USER... WITH PASSWORD` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE USER WITH PASSWORD '
Be sure to create a password for each new user. Without a password, or being enrolled in cluster single sign-on (SSO), a user cannot connect to the cluster or access the DB Console. To add or change a password for a user, use the `ALTER USER` statement.
### View all SQL users in your cluster
To view a list of all of the users in your cluster, navigate to the **SQL Users** page.
On the **SQL Users** page, you can do the following:
* [Create a user](#create-a-sql-user)
* [Change a user's password](#change-a-sql-user’s-password)
* [Remove a user](#remove-a-sql-user)
To list all the users in your cluster, use the `SHOW USERS` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW USERS;
```
### Change a SQL user's password
Only users with the Organization Admin, or Cluster Admin can change a user's password. If you do not have the required permissions, ask a user with one of the required roles to change the password.
To change a user's password:
1. Navigate to the **SQL Users** page.
2. In the row of the user whose password needs to be changed, click the **...** button.
3. From the dropdown, select **Change Password**.
4. Click **Generate & save password**.
5. Copy the generated password and save it in a secure location.
To change a user's password, use the `ALTER USER` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> ALTER USER WITH PASSWORD '
### Remove a SQL user
To remove a user:
1. Navigate to the **SQL Users** page.
2. In the row of the user you want to remove, click the **...** button.
3. From the dropdown, select **Delete SQL User**.
4. Click **Delete**.
To remove a user, use the `DROP USER` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> DROP USER ;
```
All of a user's privileges must be [revoked](#revoke-a-sql-user’s-privileges) before the user can be dropped.
### Grant privileges to a SQL user
Access to the data in your cluster is controlled by privileges. When a user connects to a database, either via the CockroachDB SQL client or a PostgreSQL driver or ORM, CockroachDB checks the user's privileges for each statement executed. If the user does not have sufficient privileges for a statement, CockroachDB returns an error.
To grant a user privileges for specific databases and tables in your cluster, use the `GRANT` statement. For example, to assign a user all privileges for all tables in a database:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> GRANT ALL ON DATABASE TO ;
```
To assign a user more limited privileges for one table in a database:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> GRANT SELECT, INSERT ON TABLE . TO ;
```
For more details, see Privileges and `GRANT`.
### View a SQL user's privileges
To show privileges granted to a user, use the `SHOW GRANTS` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW GRANTS ON DATABASE FOR ;
```
### Revoke a SQL user's privileges
To revoke privileges from a user, use the `REVOKE` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> REVOKE INSERT ON TABLE . FROM ;
```
### Use SQL roles to manage access
Role-based access control lets you simplify how you manage privileges. In essence, a role is a group containing any number of other roles and users as members. You can assign privileges to a role, and all direct and indirect members of the role will inherit the privileges.
Once you have connected to the cluster, you can set up roles:
* To create a role, use the `CREATE ROLE` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE ROLE ;
```
* To grant privileges to a role, use the `GRANT ` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> GRANT ON DATABASE TO ;
```
* To add a user (or another role) to a role, use the `GRANT ` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> GRANT TO ;
```
* To revoke privileges from a role, use the `REVOKE ` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> REVOKE INSERT ON TABLE . FROM ;
```
* To remove a user (or another role) from a role, use the `REVOKE ` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> REVOKE FROM ;
```
* To list all roles in your cluster, use the `SHOW ROLES` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> SHOW ROLES;
```
* To remove a role, use the `DROP ROLE` statement:
```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> DROP ROLE ;
```
All of a role's privileges must be [revoked](#revoke-a-sql-user’s-privileges) before the role can be dropped.
## See also
* Client Connection Parameters
* Connect to Your CockroachDB Advanced Cluster