Skip to main content
CockroachDB Cloud uses a hierarchical authorization model with roles that can be assigned at organization, folder, and cluster scopes.

​
Authorization Model Overview

CockroachDB Cloud has a two-level authorization hierarchy:
  1. Organization Level: Roles for Cloud Console, API, and cluster management
  2. Cluster Level: SQL roles for database operations
This page focuses on organization-level authorization. For cluster-level SQL authorization, see the CockroachDB Authorization documentation.

​
Organization User Roles

Organization roles control what users and service accounts can do in CockroachDB Cloud.

​
Role Hierarchy

Roles can be assigned at three scopes:
  1. Organization: Applies to all resources in the organization
  2. Folder: Applies to folder and all its clusters and subfolders
  3. Cluster: Applies to a specific cluster only
Role inheritance is transitive - roles assigned at organization or folder level are inherited by child resources.

​
Available Roles

Organization Admin
  • Full administrative access to the organization
  • Invite and manage users
  • Create and manage service accounts
  • Assign roles to users and service accounts
  • Manage billing and payments
  • Configure organization settings and SSO
  • Create, modify, and delete clusters
Scope: Organization onlyUse Case: Organization administrators

​
Role Permissions Matrix

PermissionOrg AdminCluster AdminCluster OperatorCluster DeveloperMetrics Viewer
Create clusters✓✓ (org scope)✗✗✗
Delete clusters✓✓✗✗✗
Scale clusters✓✓✓✗✗
Manage SQL users✓✓✗✗✗
View connection info✓✓✓✓✗
Configure networking✓✓✓✗✗
View metrics✓✓✓✓✓
Manage backups✓✓✓✗✗
Access DB Console✓✓✓✓✗
Invite users✓✗✗✗✗
Manage billing✓✗✗✗✗

​
Manage Organization Users

Add and manage users in your organization.

​
Invite Users

1

Access User Management

  1. Click Access Management in the Cloud Console
  2. Click Users tab
2

Send Invitation

  1. Click Invite User
  2. Enter email address
  3. Select roles to assign
  4. Choose scope (Organization, Folder, or Cluster)
  5. Click Send Invitation
3

User Accepts

User receives email invitation and creates account
New users are automatically assigned the Organization Member role, which grants no permissions beyond organization membership.

​
Change User Roles

1

Find User

Go to Access Management > Users
2

Edit Roles

  1. Click on the user
  2. In Roles section, click Edit
  3. Add or remove roles
  4. Select appropriate scope for each role
  5. Click Save

​
Remove User

1

Select User

Go to Access Management > Users and select the user
2

Remove from Organization

  1. Click action menu (•••)
  2. Select Remove from organization
  3. Confirm removal
Removed users immediately lose all access to the organization and its clusters.

​
Service Accounts

Service accounts are used for automated access via the Cloud API.

​
Create Service Account

1

Navigate to Service Accounts

Go to Access Management > Service Accounts
2

Create Account

  1. Click Create Service Account
  2. Enter name and description
  3. Assign roles and scopes
  4. Click Create
3

Generate API Key

  1. Click on the new service account
  2. Click Create API Key
  3. Copy and securely store the API key
  4. The key is shown only once

​
Manage API Keys

1

View Keys

  1. Go to Service Accounts
  2. Click on service account
  3. View API Keys section
2

Rotate Keys

  1. Create new API key
  2. Update applications with new key
  3. Delete old key after migration
3

Revoke Key

  1. Find key to revoke
  2. Click Delete
  3. Confirm deletion
API Key Security:
  • Treat API keys like passwords
  • Never commit keys to version control
  • Use environment variables
  • Rotate keys regularly
  • Delete unused keys immediately

​
Organize with Folders

Folders help organize clusters and manage permissions hierarchically.

​
Create Folders

1

Create Folder

  1. On Clusters page, click New Folder
  2. Enter folder name
  3. Select parent folder (optional)
  4. Click Create
2

Move Clusters

  1. Select cluster
  2. Click Move to folder
  3. Select destination folder
  4. Click Move

​
Assign Folder Roles

Roles assigned to folders are inherited by all clusters and subfolders:
1

Access Folder

Click on folder name in Clusters page
2

Manage Roles

  1. Click Access tab
  2. Click Add user or service account
  3. Select user/service account
  4. Assign roles
  5. Click Save
Folder Benefits:
  • Organized cluster management
  • Inherited permissions
  • Grouped billing reports
  • Team-based access control

​
SQL User Management

Manage SQL users for database access.

​
Create SQL Users

Only users with Cluster Admin or Organization Admin can create SQL users:
1

Navigate to SQL Users

  1. Select cluster
  2. Click SQL Users
2

Add User

  1. Click Add User
  2. Enter username
  3. Set password
  4. Click Create

​
Grant SQL Privileges

Control database access with SQL privileges: 
-- Create read-only user
CREATE USER readonly_user;
GRANT SELECT ON DATABASE mydb TO readonly_user;

-- Create application user
CREATE USER app_user;
GRANT ALL ON DATABASE mydb TO app_user;

-- Create admin user
CREATE USER admin_user;
GRANT admin TO admin_user;

-- Grant specific table access
GRANT SELECT, INSERT, UPDATE ON TABLE customers TO app_user;

​
SQL Roles

Use SQL roles to group permissions: 
-- Create role for analysts
CREATE ROLE analyst;
GRANT SELECT ON DATABASE analytics TO analyst;

-- Assign role to users
GRANT analyst TO user1, user2;

-- Create role for developers
CREATE ROLE developer;
GRANT ALL ON DATABASE dev TO developer;
GRANT developer TO dev_team_user;

​
SSO Integration

Integrate with your identity provider for centralized access control.

​
Configure SSO

1

Access SSO Settings

Go to Organization Settings > SSO
2

Add Identity Provider

  1. Click Configure SSO
  2. Select IdP type (SAML 2.0)
  3. Upload IdP metadata
  4. Configure attribute mappings
3

Enable SSO

  1. Test SSO configuration
  2. Toggle Enable SSO
  3. Optionally enforce SSO

​
SCIM Provisioning

Automate user provisioning with SCIM:
1

Enable SCIM

Go to Organization Settings > SCIM
2

Generate Token

  1. Click Enable SCIM
  2. Copy SCIM endpoint URL
  3. Generate and copy SCIM token
3

Configure IdP

Configure SCIM in your identity provider with:
  • SCIM endpoint URL
  • SCIM token
  • Attribute mappings
SCIM Benefits:
  • Automatic user provisioning
  • Automatic deprovisioning
  • Role synchronization
  • Reduced administrative overhead

​
Best Practices

​
Principle of Least Privilege

Grant Minimum Necessary Access

  • Start with least privileged role
  • Grant additional permissions as needed
  • Review permissions regularly
  • Remove unused access immediately

​
Role Assignment Strategy

Organization Scope:
  • Use for organization-wide administrators
  • Limit number of Organization Admins
  • Use service accounts for automation
Folder Scope:
  • Use for team-based access
  • Organize by environment (dev, staging, prod)
  • Organize by department or project
Cluster Scope:
  • Use for cluster-specific access
  • Grant to individual developers
  • Use for temporary access

​
Access Reviews

Regularly review and audit access:
1

Monthly Reviews

  • Review new users and roles
  • Check for unused accounts
  • Verify role assignments
2

Quarterly Audits

  • Full access review
  • Update role assignments
  • Remove inactive users
  • Rotate service account keys
3

Annual Reviews

  • Comprehensive security audit
  • Review folder structure
  • Update policies and procedures

​
Service Account Management

Service Account Best Practices

  • One service account per application
  • Descriptive names and documentation
  • Rotate API keys every 90 days
  • Delete unused service accounts
  • Monitor API usage

​
Troubleshooting

​
Permission Denied

Issue: User cannot perform action Solutions:
  1. Check user’s assigned roles
  2. Verify role scope (org, folder, cluster)
  3. Confirm role provides necessary permission
  4. Check if user is in correct organization
  5. Contact Organization Admin

​
Cannot Invite User

Issue: Invitation fails Solutions:
  1. Verify you have Organization Admin role
  2. Check email address is correct
  3. Confirm user doesn’t already exist
  4. Check organization user limits
  5. Try different email address

​
SQL User Cannot Connect

Issue: SQL authentication fails Solutions:
  1. Verify SQL user exists on cluster
  2. Reset password if forgotten
  3. Check network authorization
  4. Verify SQL privileges granted
  5. Confirm connection string is correct

​
Next Steps

Authentication

Learn about authentication methods

Network Security

Configure network authorization

Compliance

Security compliance and certifications

Organization Settings

Detailed access management guide

Build docs developers (and LLMs) love

Get started for freeTalk to us