Workspace Assignment

View as Markdown

The direct assignment of a provisioned account-level principal (user, service principal, or group) to a workspace, together with the entitlements that assignment grants in the workspace.

This resource covers only principals assigned directly to the workspace. Principals that inherit workspace access through a group are not represented here. See WorkspaceAccessDetail and WorkspaceIdentityDetail for the effective, direct-or-indirect view. Creating the resource assigns the principal to the workspace, and deleting it removes the assignment.

entitlements is the only client-settable field. It holds the entitlements granted directly on this assignment, including any the principal also holds through a group. effective_entitlements is the read-only union of those and any granted through group membership.

A direct assignment always carries at least one directly-assigned entitlement, because the assignment is what grants it. Create and update both reject an empty entitlements set. To remove a principal's assignment entirely, delete the resource.

This resource replaces workspace assignment previously managed through the workspace SCIM and permission-assignment APIs, and is intended for account and workspace admins.

Get a workspace assignment for a principalGET /api/2.0/identity/{name=workspace-assignments/*}List workspace assignments for a workspaceGET /api/2.0/identity/workspace-assignmentsCreate a workspace assignment for a workspacePOST /api/2.0/identity/workspace-assignmentsUpdate a workspace assignment for a workspacePATCH /api/2.0/identity/{name=workspace-assignments/*}Delete a workspace assignment for a workspaceDELETE /api/2.0/identity/{name=workspace-assignments/*}

WorkspaceAssignment object

The direct assignment of a provisioned account-level principal (user, service principal, or group) to a workspace, together with the entitlements that assignment grants in the workspace.

This resource covers only principals assigned directly to the workspace. Principals that inherit workspace access through a group are not represented here. See WorkspaceAccessDetail and WorkspaceIdentityDetail for the effective, direct-or-indirect view. Creating the resource assigns the principal to the workspace, and deleting it removes the assignment.

entitlements is the only client-settable field. It holds the entitlements granted directly on this assignment, including any the principal also holds through a group. effective_entitlements is the read-only union of those and any granted through group membership.

A direct assignment always carries at least one directly-assigned entitlement, because the assignment is what grants it. Create and update both reject an empty entitlements set. To remove a principal's assignment entirely, delete the resource.

This resource replaces workspace assignment previously managed through the workspace SCIM and permission-assignment APIs, and is intended for account and workspace admins.

namestringBetaIDImmutable

The resource name of the workspace assignment. The format depends on the API that returned it:

• Account-scoped: accounts/{account_id}/workspaces/{workspace_id}/workspace-assignments/{principal_id}
• Workspace-scoped: workspace-assignments/{principal_id}

parentstringBetaOutput onlyImmutable

The resource name of the workspace that contains the assignment, accounts/{account_id}/workspaces/{workspace_id}. Both the account-scoped and workspace-scoped APIs return it.

principal_typestringBetaOutput only

The type of the principal (user/service principal/group) that is assigned.

Values:

• USER
• SERVICE_PRINCIPAL
• GROUP

principal_idint64BetaImmutable

The internal ID of the principal (user/sp/group) in Databricks. Set when the assignment is created and cannot be changed afterwards; to assign a different principal, create a new assignment.

workspace_idint64BetaOutput onlyImmutable

The workspace ID where the principal is assigned.

account_idstringBetaOutput onlyImmutable

The account ID parent of the workspace where the principal is assigned

entitlementsarray of stringBetaUnordered list

Entitlements granted directly to the principal on this workspace. This is the only client-settable field. Create and update manage exactly this set, including entitlements the principal also holds through a group. List responses leave this field empty. Get a single principal to read its entitlements.

Values:

• WORKSPACE_ACCESS
• WORKSPACE_CONSUME
• DATABRICKS_SQL_ACCESS
• WORKSPACE_ADMIN
• ALLOW_CLUSTER_CREATE
• ALLOW_INSTANCE_POOL_CREATE

effective_entitlementsarray of stringBetaOutput onlyUnordered list

Every entitlement the principal holds in this workspace, whether granted directly or through group membership. Get responses populate this field. List responses leave it empty.

Values:

• WORKSPACE_ACCESS
• WORKSPACE_CONSUME
• DATABRICKS_SQL_ACCESS
• WORKSPACE_ADMIN
• ALLOW_CLUSTER_CREATE
• ALLOW_INSTANCE_POOL_CREATE

View as Markdown

The WorkspaceAssignment object

{
  "name": "string",
  "parent": "string",
  "principal_type": "USER",
  "principal_id": 0,
  "workspace_id": 0,
  "account_id": "string",
  "entitlements": [
    "WORKSPACE_ACCESS"
  ],
  "effective_entitlements": [
    "WORKSPACE_ACCESS"
  ]
}

Get a workspace assignment for a principal Beta

GET /api/2.0/identity/{name=workspace-assignments/*}

Returns the assignment for a principal in the calling workspace.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the workspace assignment. Format: workspace-assignments/{principal_id}

Response

Returns the WorkspaceAssignment object.

View as Markdown

Response

{
  "name": "string",
  "parent": "string",
  "principal_type": "USER",
  "principal_id": 0,
  "workspace_id": 0,
  "account_id": "string",
  "entitlements": [
    "WORKSPACE_ACCESS"
  ],
  "effective_entitlements": [
    "WORKSPACE_ACCESS"
  ]
}

List workspace assignments for a workspace Beta

GET /api/2.0/identity/workspace-assignments

Lists workspace assignments for the calling workspace. The response omits the per-principal entitlement fields (entitlements and effective_entitlements). To read the entitlements for a single principal, get that principal's assignment.

API scopes: identity

Parameters

page_sizeint32query

The maximum number of workspace assignments to return. The service may return fewer than this value. If not provided, defaults to 1000, which is also the maximum allowed. Requests for more than the maximum are clamped to 1000.

page_tokenstringquery

A page token from a previous list call. Provide this to retrieve the subsequent page.

parentstringquery

The resource name of the workspace to list assignments of, accounts/{account_id}/workspaces/{workspace_id}. Optional: defaults to the calling workspace, and any other workspace is rejected.

Response

Returns a list of WorkspaceAssignment objects.

View as Markdown

Response

{
  "workspace_assignments": [
    {
      "name": "string",
      "parent": "string",
      "principal_type": "USER",
      "principal_id": 0,
      "workspace_id": 0,
      "account_id": "string",
      "entitlements": [
        "WORKSPACE_ACCESS"
      ],
      "effective_entitlements": [
        "WORKSPACE_ACCESS"
      ]
    }
  ],
  "next_page_token": "string"
}

Create a workspace assignment for a workspace Beta

POST /api/2.0/identity/workspace-assignments

Creates a workspace assignment for a principal in the calling workspace. Entitlements are granted one at a time rather than atomically. If the request fails partway through, the principal stays assigned to the workspace with only some of the requested entitlements. Get the assignment afterwards to confirm which entitlements were granted.

API scopes: identity

Parameters

parentstringquery

The resource name of the workspace to assign the principal to, accounts/{account_id}/workspaces/{workspace_id}. Optional: defaults to the calling workspace, and any other workspace is rejected.

Request body

Required. Workspace assignment to be created in Databricks.

namestringIDImmutable

The resource name of the workspace assignment. The format depends on the API that returned it:

• Account-scoped: accounts/{account_id}/workspaces/{workspace_id}/workspace-assignments/{principal_id}
• Workspace-scoped: workspace-assignments/{principal_id}

principal_idint64RequiredImmutable

The internal ID of the principal (user/sp/group) in Databricks. Set when the assignment is created and cannot be changed afterwards; to assign a different principal, create a new assignment.

entitlementsarray of stringUnordered list

Entitlements granted directly to the principal on this workspace. This is the only client-settable field. Create and update manage exactly this set, including entitlements the principal also holds through a group. List responses leave this field empty. Get a single principal to read its entitlements.

Values:

• WORKSPACE_ACCESS
• WORKSPACE_CONSUME
• DATABRICKS_SQL_ACCESS
• WORKSPACE_ADMIN
• ALLOW_CLUSTER_CREATE
• ALLOW_INSTANCE_POOL_CREATE

Response

Returns the WorkspaceAssignment object.

View as Markdown

Request

{
  "name": "string",
  "principal_id": 0,
  "entitlements": [
    "WORKSPACE_ACCESS"
  ]
}

Response

{
  "name": "string",
  "parent": "string",
  "principal_type": "USER",
  "principal_id": 0,
  "workspace_id": 0,
  "account_id": "string",
  "entitlements": [
    "WORKSPACE_ACCESS"
  ],
  "effective_entitlements": [
    "WORKSPACE_ACCESS"
  ]
}

Update a workspace assignment for a workspace Beta

PATCH /api/2.0/identity/{name=workspace-assignments/*}

Updates the entitlements of a directly assigned principal in the calling workspace. Changes are applied one at a time rather than atomically. If the request fails partway through, only some of the requested changes take effect. Get the assignment afterwards to confirm the final state.

API scopes: identity

Parameters

namestringRequiredIDImmutablepath

The resource name of the workspace assignment. The format depends on the API that returned it:

• Account-scoped: accounts/{account_id}/workspaces/{workspace_id}/workspace-assignments/{principal_id}
• Workspace-scoped: workspace-assignments/{principal_id}

update_maskstringRequiredquery

Required. The list of fields to update.

Request body

Required. Workspace assignment to be updated in Databricks.

principal_idint64RequiredImmutable

The internal ID of the principal (user/sp/group) in Databricks. Set when the assignment is created and cannot be changed afterwards; to assign a different principal, create a new assignment.

entitlementsarray of stringUnordered list

Entitlements granted directly to the principal on this workspace. This is the only client-settable field. Create and update manage exactly this set, including entitlements the principal also holds through a group. List responses leave this field empty. Get a single principal to read its entitlements.

Values:

• WORKSPACE_ACCESS
• WORKSPACE_CONSUME
• DATABRICKS_SQL_ACCESS
• WORKSPACE_ADMIN
• ALLOW_CLUSTER_CREATE
• ALLOW_INSTANCE_POOL_CREATE

Response

Returns the WorkspaceAssignment object.

View as Markdown

Request

{
  "principal_id": 0,
  "entitlements": [
    "WORKSPACE_ACCESS"
  ]
}

Response

{
  "name": "string",
  "parent": "string",
  "principal_type": "USER",
  "principal_id": 0,
  "workspace_id": 0,
  "account_id": "string",
  "entitlements": [
    "WORKSPACE_ACCESS"
  ],
  "effective_entitlements": [
    "WORKSPACE_ACCESS"
  ]
}

Delete a workspace assignment for a workspace Beta

DELETE /api/2.0/identity/{name=workspace-assignments/*}

Deletes a workspace assignment for a principal in the calling workspace, revoking all of its entitlements. Entitlements are revoked one at a time rather than atomically. If the request fails partway through, the principal stays assigned with some of its original entitlements. Retrying is safe.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the workspace assignment. Format: workspace-assignments/{principal_id}

View as Markdown

Response

{}