Skip to main content
Last updated on

Grant permissions programmatically

info

Lakebase Autoscaling is available in the following regions: us-east-1, us-east-2, us-west-2, ca-central-1, sa-east-1, eu-central-1, eu-west-1, eu-west-2, ap-south-1, ap-southeast-1, ap-southeast-2.

Lakebase Autoscaling is the latest version of Lakebase with autoscaling compute, scale-to-zero, branching, and instant restore. For feature comparison with Lakebase Provisioned, see choosing between versions.

Lakebase project permissions can be managed programmatically using the standard Databricks Permissions API, the Databricks CLI, Databricks SDKs, and Terraform.

For an overview of permission types, default permissions, and how to manage permissions in the Lakebase UI, see Manage project permissions.

Permission levels​

The grantable permission levels for Lakebase projects are CAN_USE and CAN_MANAGE. CAN_CREATE is an inherited level that flows automatically from the workspace to all users and cannot be explicitly granted or revoked on a project. Attempts to grant CAN_CREATE via the API return HTTP 400.

Project IDs are UUIDs (e.g., a446ad92-e936-454b-a31c-a0742e53dd5c). Retrieve yours with databricks postgres list-projects and look at the uid field.

REST API​

Project permissions use the standard Databricks Permissions API at /api/2.0/permissions/database-projects/{project_id}.

Get current permissions​

Bash
curl -X GET "https://${DATABRICKS_HOST}/api/2.0/permissions/database-projects/${PROJECT_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Grant or update permissions (PATCH)​

Bash
curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/permissions/database-projects/${PROJECT_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "access_control_list": [
      {
        "user_name": "user@example.com",
        "permission_level": "CAN_USE"
      }
    ]
  }'

To grant permissions to a group or service principal, replace user_name with group_name or service_principal_name.

note

PATCH is additive and cannot downgrade an existing higher permission. For example, patching CAN_USE onto a user who already holds CAN_MANAGE has no effect. To downgrade or remove a permission, use PUT instead.

Replace all explicit permissions (PUT)​

warning

PUT replaces the entire explicit ACL. Any user, group, or service principal not included in the request body loses their explicitly granted permission. Inherited permissions (such as workspace admins) are not affected.

Bash
curl -X PUT "https://${DATABRICKS_HOST}/api/2.0/permissions/database-projects/${PROJECT_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "access_control_list": [
      {
        "user_name": "user@example.com",
        "permission_level": "CAN_MANAGE"
      }
    ]
  }'

For the full Permissions API reference, see Permissions API.

CLI​

Use the databricks permissions commands (which wrap the Permissions API) to manage project permissions from the command line.

Grant or update permissions​

Bash
# PROJECT_ID is a UUID. Retrieve it with: databricks postgres list-projects
databricks permissions update database-projects ${PROJECT_ID} \
  --json '{
    "access_control_list": [
      {
        "user_name": "user@example.com",
        "permission_level": "CAN_USE"
      }
    ]
  }'

Get current permissions​

Bash
databricks permissions get database-projects ${PROJECT_ID}
note

Use databricks permissions (not databricks postgres) for project ACL management. The databricks postgres subcommand manages project resources (branches, computes, etc.), not permissions.

SDK​

Use the WorkspaceClient.permissions interface in the Python, Java, or Go SDK to manage project permissions.

Python
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.iam import AccessControlRequest, PermissionLevel

w = WorkspaceClient()

# Retrieve your project UUID from: databricks postgres list-projects
PROJECT_ID = "<project-uuid>"

# Grant CAN_USE to a user (PATCH is additive and cannot downgrade)
w.permissions.update(
    request_object_type="database-projects",
    request_object_id=PROJECT_ID,
    access_control_list=[
        AccessControlRequest(
            user_name="user@example.com",
            permission_level=PermissionLevel.CAN_USE,
        )
    ],
)

# Get current permissions
permissions = w.permissions.get(
    request_object_type="database-projects",
    request_object_id=PROJECT_ID,
)
print(permissions)

# Revoke or downgrade: use set() (PUT), not update() (PATCH)
# update() with an empty list is a no-op; set() replaces the full explicit ACL
w.permissions.set(
    request_object_type="database-projects",
    request_object_id=PROJECT_ID,
    access_control_list=[
        # Include every identity that should retain explicit access
        AccessControlRequest(
            user_name="owner@example.com",
            permission_level=PermissionLevel.CAN_MANAGE,
        )
    ],
)

Terraform​

Use the databricks_permissions resource with a database_project_name attribute to manage project permissions as infrastructure-as-code. For a full Terraform workflow including project creation, group examples, and declarative behavior, see Manage project permissions with Terraform.

Hcl
resource "databricks_permissions" "project_perms" {
  database_project_name = databricks_postgres_project.app.project_id

  access_control {
    user_name        = "someone@example.com"
    permission_level = "CAN_USE"
  }
}

For the complete resource reference, see databricks_permissions on the Terraform Registry.

Next steps​