> ## 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.
# CockroachDB Cloud Access Management (Authorization) Overview
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 covers the essential concepts related to access management (authorization) in CockroachDB Cloud. Procedures for managing access are covered in Managing Users, Roles, and Service Accounts in CockroachDB Cloud.
## Overview of the CockroachDB Cloud authorization model
**The CockroachDB Cloud console**, found at `https://cockroachlabs.cloud/`, is a 'single pane of glass' for managing users, billing, and all functions for administering clusters in CockroachDB Cloud. When accessing the console, users must sign in to a CockroachDB Cloud **organization** (or create a new one).
You can also execute many administrative commands using the `ccloud` command-line utility and the CockroachDB Cloud API:
* `ccloud` allows human users to authenticate their terminal via a browser token from the CockroachDB Cloud console.
* The CockroachDB Cloud API allows [service accounts](#service-accounts) to authenticate via API keys, which are issued through the console.
* You can use Terraform to provision users and other aspects of your CockroachDB Cloud clusters. However, note that currently Terraform can only be used to provision admin SQL users, as this is a current limitation of the API, on which Terraform depends.
In CockroachDB Cloud, an organization corresponds to an authorization hierarchy linked to a billing account. Within each CockroachDB Cloud organization, the unit of database functionality is the *CockroachDB cluster*, which corresponds to a networked set of CockroachDB cluster nodes. SQL operations and data storage are distributed over a cluster. Every cluster belongs to an organization.
CockroachDB Cloud has a hierarchical authorization model, where roles can be assigned at different scopes:
1. Organization: A CockroachDB Cloud organization assigns permissions based on [roles](#organization-user-roles) assigned to a Cloud Console user account, which allow these accounts to perform administrative tasks relating to the management of clusters, Console user management, SQL user management, and billing.
2. Folder: Cloud Console [roles](#organization-user-roles) can be assigned to a folder containing a group of clusters. Role inheritance is transitive; a role applied with the organization or folder scope is inherited by descendent resources.
Organizing clusters using folders is available in Preview. To learn more, refer to Organize Clusters Using Folders.
3. Cluster: Each CockroachDB cluster defines its own set of SQL users and SQL user roles which manage permission to execute SQL statements on the cluster.
The levels within the hierarchy intersect, because administering SQL-level users on specific clusters within an organization is an organization-level function.
SQL users are granted a distinct set of roles and privileges that are specific to data management on the cluster, independent of the Cloud user roles and permissions described on this page. For the main pages covering users and roles at the SQL level within a specific database cluster, refer to the main Authorization in CockroachDB documentation
. The GRANT SQL statement cannot be used to assign Cloud roles and permissions.
## Organization user roles
When a user or service account is first added to an organization, they are assigned the default Console role, **Organization Member**, which adds no permissions and only indicates membership in the organization. Users with the Organization or Cluster Admin role may edit the roles assigned to organization users in the CockroachDB Cloud Console's [**Access Management** page](https://cockroachlabs.cloud/access), or using the CockroachDB Cloud API or Terraform Provider.
The user who creates a new organization is assigned the following roles at the organization scope:
* Organization Admin
* Billing Coordinator
* Cluster Admin
* Folder Administrator
Any of these roles may subsequently be removed by a user with both the Organization Admin role and the Cluster Admin role at the organization scope. This is to ensure that at least one user has both of these roles.
To learn more, refer to Manage organization users.
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` |
The following sections describe the available CockroachDB Cloud roles in more detail:
### Organization Member
The **Organization Member** role is assigned by default to all organization users when they are invited or provisioned. This role gives no additional permissions.
### Organization Admin
The **Organization Admin** role allows users to perform the following actions:
* Invite users to join that organization.
* Create service accounts.
* Assign and revoke Cloud roles for both users and service accounts.
Organization Admins automatically receive email alerts about planned cluster maintenance and when CockroachDB Cloud detects that a cluster is overloaded or experiencing issues. In addition, Organization Admins can subscribe other members to the email alerts, and configure how alerts work for the organization.
This role can be assigned only at the organization scope.
### Billing Coordinator
The **Billing Coordinator** role allows users to manage and view billing details, invoices, and usage for that organization through the CockroachDB Cloud console billing page at [`https://cockroachlabs.cloud/billing/overview`](https://cockroachlabs.cloud/billing/overview).
### Billing Viewer
The **Billing Viewer** role allows users to view billing details, invoices, and usage for that organization through the CockroachDB Cloud console billing page at [`https://cockroachlabs.cloud/billing/overview`](https://cockroachlabs.cloud/billing/overview).
### Cluster Operator
The **Cluster Operator** role allows actions that are dependent on whether it is assigned to a user or a service account.
* *Users* with this role can perform the following *console operations*:
* View a cluster's Overview page, which displays its settings, attributes and statistics, including cloud provider, region topography, and available and maximum storage and request units.
* Manage a cluster's databases from the Databases Page.
* Scale a cluster's nodes.
* View and configure a cluster's authorized networks from the Networking Page.
* Manage network authorization for a cluster.
* View backups in a cluster's Backup and Restore Page.
* Restore a cluster from a backup.
* View a cluster's Jobs from the Jobs page.
* View a cluster's Metrics from the Metrics page.
* View a cluster's Insights from the Insights page.
* Upgrade a cluster's major version of CockroachDB.
* View a cluster's PCI-readiness status (Advanced clusters with Security add-on only).
* Send a test alert from the Alerts Page.
* Configure single sign-on (SSO) enforcement.
* Access the DB Console.
* Configure a cluster's maintenance window.
* Edit a cluster's labels.
* *Service accounts* with this role can perform the following *API operations*:
* Read a cluster summary.
* Manage Customer-Managed Encryption Keys (CMEK) for Advanced Clusters
* Export a cluster's logs.
* Export a cluster's metrics.
* Manage network authorization for a cluster.
* View and configure a cluster's Egress Rules.
* Configure the export of metrics to DataDog or Amazon CloudWatch.
This role can be considered a more restricted alternative to [Cluster Admin](#cluster-admin), as it gives all of the permissions of that role but does **not** allow users to:
* Manage cluster-scoped roles on organization users.
* Manage SQL users from the cloud console.
* Create or delete a cluster.
This role can be assigned at the scope of the organization, on an individual cluster, or on a folder. If assigned to a folder, the role is inherited on the folder's clusters, descendent folders, and their descendants.
### Cluster Admin
The **Cluster Admin** role allows users to perform all [Cluster Operator](#cluster-operator) actions, as well as the following:
* Provision SQL users for a cluster using the console.
* Create Service Accounts.
* Edit cluster-scope role assignments (specifically, the Cluster Admin, Cluster Operator, and Cluster Developer roles) on users, and service accounts.
* Edit or delete a cluster.
* Cluster Admins for the whole organization (rather than scoped to a single cluster) can create new clusters.
* Access the DB Console.
* Configure a cluster's maintenance window.
This role can be assigned at the scope of the organization, on an individual cluster, or on a folder. If assigned to a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.
### Cluster Creator
The **Cluster Creator** role allows users to create clusters in an organization. A cluster's creator is automatically assigned the [Cluster Admin](#cluster-admin) role for that cluster upon creation.
This role can be assigned at the scope of the organization or on a folder. If assigned to a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.
### Cluster Developer
The **Cluster Developer** role allows users to view cluster details and access the DB Console, allowing them to export a connection string from the cluster page UI, although they will still need a Cluster Admin to provision their SQL credentials for the cluster.
This role can be assigned at the scope of the organization, on an individual cluster, or on a folder. If assigned to a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.
### Cluster Monitor
The **Cluster Monitor** role provides read‑only visibility into SQL activity and workload health without broader administrative privileges. Users with this role can view the SQL Activity pages (Sessions, Statements, and Transactions), the Jobs page, and the Insights page.
This role can be assigned at the scope of the organization, on an individual cluster, or on a folder. If assigned to a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.
### Metrics Viewer
The **Metrics Viewer** role grants read‑only access to observability metrics for a cluster without any administrative or data‑manipulation privileges.
* Users with this role can view a cluster's Metrics from the Metrics page.
* Service accounts with this role can access the metrics export API and the log export API to integrate with external observability systems.
This role can be assigned at the scope of the organization, on an individual cluster, or on a folder. If assigned to a folder, it is inherited on the folder's clusters, descendent folders, and their descendants.
To give a developer the ability to both connect to a cluster and monitor performance with least privilege, combine [**Cluster Developer**](#cluster-developer) with **Metrics Viewer** (and optionally [**Cluster Monitor**](#cluster-monitor)).
### Folder Admin
The **Folder Admin** role allows users to create, rename, move, delete, and manage access to folders where they are assigned the role. Users can also edit folder labels. This role can be assigned at the level of the organization or on a specific folder. If assigned at the level of the organization, the role allows users to view all users and service accounts in the organization. If assigned to a specific folder, the role is inherited by descendant folders.
A user with the [Organization Admin](#organization-admin) role can assign themselves, another user, or a service account the Folder Admin role.
To create or manage clusters in a folder, a Folder Admin also needs the [Cluster Admin](#cluster-admin) or [Cluster Creator](#cluster-creator) role on that folder directly or by inheritance. To delete a cluster, the Cluster Admin role is required on the cluster directly or by inheritance.
### Folder Mover
The **Folder Mover** role allows users to rename or move descendant folders, and move clusters within the folder hierarchy where they have the role. However, a Folder Mover cannot create or delete folders or clusters and cannot assign roles. A Folder Mover can move clusters within the folder hierarchy even if they do not have a role that allows them to connect to the cluster, such as [Cluster Creator](#cluster-creator) or [Cluster Operator](#cluster-operator).
A cluster inside a folder cannot be renamed.
A user with the [Organization Admin](#organization-admin) or [Folder Admin](#folder-admin) role can assign another user or a service account the Folder Mover role. Because the Folder Admin role is a superset of Folder Mover, there is no need for a Folder Admin to assign themselves the Folder Mover role.
## Service accounts
Service accounts authenticate with API keys to the CockroachDB Cloud API, rather than to the CockroachDB Cloud Console UI.
Service accounts operate under a unified authorization model with organization users, and can be assigned all of the same [roles](#organization-user-roles) as users, but note that some actions are available in the console but not the API, or vice versa (For example, in the [Cluster Operator Role](#cluster-operator)).
Refer to Manage Service Accounts.
## Cluster roles for organization users using Cluster SSO
Cluster Single Sign-On (SSO) for CockroachDB Cloud allows authorized organization users to directly access clusters within the organization via `ccloud`, the CockroachDB Cloud command line interface.
However, because organization users and cluster SQL users are logically separate, a corresponding SQL user must be created for each SSO organization user, on each particular cluster.
This correspondence lies in the SQL user name, which must be in the format `sso_{email_name}`. Replace `(email_name}` with the portion of the user's email address before `@`. For example, the SQL username of a user with the email address `docs@cockroachlabs.com` is `sso_docs`. If the role is not set up correctly, `ccloud` prompts you to create or add it. Only an SQL admin can manage SQL users.