User Management API

The User Management API enables you to create, list, and manage SQL users within your CockroachDB Cloud clusters.

List SQL Users

Retrieve all SQL users in a cluster.

GET /v1/clusters/{cluster_id}/sql-users

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users \
  --header "Authorization: Bearer {secret_key}"

Path Parameters

cluster_id

string

required

Unique identifier for the cluster

The cluster ID used in the Cloud API is different from the routing ID used when connecting to clusters.

Response

{
  "users": [
    {
      "name": "admin"
    },
    {
      "name": "app_user"
    },
    {
      "name": "readonly_user"
    }
  ],
  "pagination": {
    "next_page": null
  }
}

users

array

Array of SQL user objects

Show User Object

name

string

SQL username

pagination

object

Pagination information

Show Pagination Object

Create a SQL User

Create a new SQL user in a cluster.

POST /v1/clusters/{cluster_id}/sql-users

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users \
  --header "Authorization: Bearer {secret_key}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "new_user",
    "password": "SecurePassword123!"
  }'

Path Parameters

cluster_id

string

required

Unique identifier for the cluster

Request Body

name

string

required

SQL username for the new userConstraints:

Cannot be empty
Cannot contain spaces
Should follow SQL identifier rules
Cannot be a reserved keyword

password

string

required

Password for the new userRequirements:

Minimum 12 characters recommended
Should include uppercase, lowercase, numbers, and special characters
Store securely - cannot be retrieved later

Response

{
  "name": "new_user"
}

By default, SQL users created via the API are granted the SQL admin role, which has full privileges for all databases and tables in the cluster.For production environments, follow the principle of least privilege: create users with minimal permissions and grant only the specific privileges they need.

Store the password securely after creation. Passwords cannot be retrieved later - they can only be reset.

Delete a SQL User

Permanently delete a SQL user from a cluster.

DELETE /v1/clusters/{cluster_id}/sql-users/{sql_username}

curl --request DELETE \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username} \
  --header "Authorization: Bearer {secret_key}"

Path Parameters

cluster_id

string

required

Unique identifier for the cluster

sql_username

string

required

Username of the SQL user to delete

Response

{
  "name": "deleted_user"
}

Deleting a SQL user is permanent and cannot be undone. Active sessions for the deleted user will be terminated.

Change User Password

Update a SQL user’s password.

PUT /v1/clusters/{cluster_id}/sql-users/{sql_username}/password

curl --request PUT \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username}/password \
  --header "Authorization: Bearer {secret_key}" \
  --header "Content-Type: application/json" \
  --data '{
    "password": "NewSecurePassword456!"
  }'

Path Parameters

cluster_id

string

required

Unique identifier for the cluster

sql_username

string

required

Username of the SQL user

Request Body

password

string

required

New password for the userRequirements:

Must be different from the current password
Minimum 12 characters recommended
Should include uppercase, lowercase, numbers, and special characters

Response

{
  "name": "user_with_new_password"
}

Changing a password does not terminate existing sessions. Users will need to reconnect with the new password for new sessions.

Managing User Privileges

While you create users through the Cloud API, you manage their privileges using SQL statements via a SQL client connection.

Grant Specific Database Access

To limit a user to a specific database:

GRANT ALL ON DATABASE mydb TO app_user;

Grant Table-Level Permissions

For more granular control:

GRANT SELECT, INSERT, UPDATE ON TABLE mytable TO app_user;

Create a Read-Only User

GRANT SELECT ON DATABASE mydb TO readonly_user;

Revoke Admin Privileges

If a user was created with admin privileges:

GRANT admin TO newuser;  -- User has admin by default from API
REVOKE admin FROM newuser;  -- Remove admin privilege
GRANT SELECT ON DATABASE mydb TO newuser;  -- Grant specific access

Required Permissions

Operation	Required Role
List SQL users	Cluster Developer, Cluster Admin
Create SQL user	Cluster Creator, Cluster Admin
Delete SQL user	Cluster Creator, Cluster Admin
Change password	Cluster Creator, Cluster Admin

Best Practices

Use Strong Passwords

Always use strong, unique passwords for SQL users:

Minimum 12-16 characters
Mix of uppercase, lowercase, numbers, and special characters
Avoid dictionary words and common patterns
Use a password manager to generate and store passwords

Follow Least Privilege Principle

After creating users via the API:

Connect to the cluster with an admin account
Revoke the default admin role if not needed
Grant only the minimum required privileges
Use role-based access control for groups of users

REVOKE admin FROM app_user;
GRANT SELECT, INSERT, UPDATE ON DATABASE app_db TO app_user;

Rotate Passwords Regularly

Implement a password rotation policy:

Change passwords every 90 days
Immediately rotate passwords if they may have been compromised
Use the password change API endpoint programmatically
Coordinate password changes with application deployments

Use Service Accounts for Applications

For application access:

Create dedicated SQL users for each application or service
Never share credentials between applications
Use descriptive names (e.g., payment_service, analytics_worker)
Document which application uses which user

Audit User Access Regularly

Periodically review SQL users:

# List all users
curl -X GET https://cockroachlabs.cloud/api/v1/clusters/{id}/sql-users \
  -H "Authorization: Bearer {key}"

# Check privileges via SQL
SHOW GRANTS FOR user_name;

Remove users that are no longer needed.

Common Workflows

Create Application User with Limited Access

Create the user via API

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users \
  --header "Authorization: Bearer {secret_key}" \
  --header "Content-Type: application/json" \
  --data '{"name": "app_user", "password": "SecurePassword123!"}'

Connect with admin user

Connect to the cluster using a SQL client with an admin account.

Revoke admin and grant specific access

REVOKE admin FROM app_user;
GRANT SELECT, INSERT, UPDATE ON DATABASE production TO app_user;
GRANT SELECT, INSERT, UPDATE ON TABLE production.orders TO app_user;
GRANT SELECT, INSERT, UPDATE ON TABLE production.customers TO app_user;

Verify permissions

SHOW GRANTS FOR app_user;

Rotate All Application Passwords

Script

#!/bin/bash

CLUSTER_ID="your-cluster-id"
API_KEY="your-api-key"

USERS=("app_user" "analytics_user" "backup_user")

for USER in "${USERS[@]}"; do
  NEW_PASSWORD=$(openssl rand -base64 32)
  
  curl --request PUT \
    --url "https://cockroachlabs.cloud/api/v1/clusters/$CLUSTER_ID/sql-users/$USER/password" \
    --header "Authorization: Bearer $API_KEY" \
    --header "Content-Type: application/json" \
    --data "{\"password\": \"$NEW_PASSWORD\"}"
  
  echo "$USER: $NEW_PASSWORD" >> passwords.txt
  
  # Update application secrets/config
  # kubectl create secret generic db-password --from-literal=password=$NEW_PASSWORD
done

Error Responses

400 Bad Request

Occurs when the request is malformed:

{
  "code": 3,
  "message": "invalid request",
  "details": ["password must be at least 1 character"]
}

409 Conflict

Occurs when trying to create a user that already exists:

{
  "code": 6,
  "message": "user already exists",
  "details": ["username 'app_user' is already taken"]
}

404 Not Found

Occurs when trying to modify or delete a non-existent user:

{
  "code": 5,
  "message": "user not found",
  "details": ["username 'nonexistent_user' does not exist"]
}

Cloud API

Cluster API

List SQL Users

Path Parameters

Response

Create a SQL User

Path Parameters

Request Body

Response

Delete a SQL User

Path Parameters

Response

Change User Password

Path Parameters

Request Body

Response

Managing User Privileges

Grant Specific Database Access

Grant Table-Level Permissions

Create a Read-Only User

Revoke Admin Privileges

Required Permissions

Best Practices

Common Workflows

Create Application User with Limited Access

Rotate All Application Passwords

Error Responses

400 Bad Request

409 Conflict

404 Not Found

Build docs developers (and LLMs) love

Cloud API

Cluster API

​List SQL Users

​Path Parameters

​Response

​Create a SQL User

​Path Parameters

​Request Body

​Response

​Delete a SQL User

​Path Parameters

​Response

​Change User Password

​Path Parameters

​Request Body

​Response

​Managing User Privileges

​Grant Specific Database Access

​Grant Table-Level Permissions

​Create a Read-Only User

​Revoke Admin Privileges

​Required Permissions

​Best Practices

​Common Workflows

​Create Application User with Limited Access

​Rotate All Application Passwords

​Error Responses

​400 Bad Request

​409 Conflict

​404 Not Found

Build docs developers (and LLMs) love

List SQL Users

Path Parameters

Response

Create a SQL User

Path Parameters

Request Body

Response

Delete a SQL User

Path Parameters

Response

Change User Password

Path Parameters

Request Body

Response

Managing User Privileges

Grant Specific Database Access

Grant Table-Level Permissions

Create a Read-Only User

Revoke Admin Privileges

Required Permissions

Best Practices

Common Workflows

Create Application User with Limited Access

Rotate All Application Passwords

Error Responses

400 Bad Request

409 Conflict

404 Not Found