Account Workspace Assignment

View as Markdown

A principal's direct assignment to a workspace, and the entitlements it grants there.

Only principals assigned directly to the workspace have an assignment. A principal that gets access only through a group doesn't. Creating an assignment gives the principal access to the workspace, and deleting it removes that direct access. These APIs replace managing workspace assignments through SCIM and the permission assignment APIs. They require a workspace with identity federation enabled. You can't assign, change, or unassign principals that Databricks manages.

entitlements is the only field you set. effective_entitlements also includes the entitlements the principal gets through its groups. An assignment must grant at least one entitlement. To remove a principal's direct access, delete the assignment.

Get a workspace assignment for a principalGET /api/2.0/identity/{name=accounts/*/workspaces/*/workspace-assignments/*}List workspace assignments for a workspaceGET /api/2.0/identity/{parent=accounts/*/workspaces/*}/workspace-assignmentsCreate a workspace assignmentPOST /api/2.0/identity/{parent=accounts/*/workspaces/*}/workspace-assignmentsUpdate a workspace assignmentPATCH /api/2.0/identity/{name=accounts/*/workspaces/*/workspace-assignments/*}Delete a workspace assignmentDELETE /api/2.0/identity/{name=accounts/*/workspaces/*/workspace-assignments/*}

WorkspaceAssignment object

A principal's direct assignment to a workspace, and the entitlements it grants there.

Only principals assigned directly to the workspace have an assignment. A principal that gets access only through a group doesn't. Creating an assignment gives the principal access to the workspace, and deleting it removes that direct access. These APIs replace managing workspace assignments through SCIM and the permission assignment APIs. They require a workspace with identity federation enabled. You can't assign, change, or unassign principals that Databricks manages.

entitlements is the only field you set. effective_entitlements also includes the entitlements the principal gets through its groups. An assignment must grant at least one entitlement. To remove a principal's direct access, delete the assignment.

namestringIDImmutable

The resource name of the assignment, in one of these formats:

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

parentstringOutput onlyImmutable

The resource name of the workspace, in the format accounts/{account_id}/workspaces/{workspace_id}. Workspace APIs return the same format.

principal_typestringOutput only

Whether the assigned principal is a user, service principal, or group.

Values:

• USER
• SERVICE_PRINCIPAL
• GROUP

principal_idint64Immutable

The Databricks ID of the assigned user, service principal, or group. It can't be changed after the assignment is created.

workspace_idint64Output onlyImmutable

The ID of the workspace.

account_idstringOutput onlyImmutable

The ID of the account that contains the workspace.

entitlementsarray of stringUnordered list

The entitlements granted directly by this assignment. Create and update set exactly this list, even if the principal also gets some of these entitlements through a group. List responses leave it empty.

Values:

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

effective_entitlementsarray of stringOutput onlyUnordered list

Every entitlement the principal has in the workspace, granted directly or through a group. 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 GA

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

Gets a principal's direct assignment to a workspace, including its effective entitlements. Returns an error if the principal isn't assigned directly.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the assignment, in the format accounts/{account_id}/workspaces/{workspace_id}/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 GA

GET /api/2.0/identity/{parent=accounts/*/workspaces/*}/workspace-assignments

Lists the principals assigned directly to a workspace. The response leaves entitlements and effective_entitlements empty. To read a principal's entitlements, get its assignment.

API scopes: identity

Parameters

parentstringRequiredpath

The resource name of the workspace, in the format accounts/{account_id}/workspaces/{workspace_id}.

page_sizeint32query

The maximum number of assignments to return, up to 1000. The default is 1000. A page can contain fewer assignments.

page_tokenstringquery

The next_page_token from a previous response, to get the next page.

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 GA

POST /api/2.0/identity/{parent=accounts/*/workspaces/*}/workspace-assignments

Assigns a user, service principal, or group directly to a workspace with the given entitlements. Returns an error if the principal is already assigned directly.

Entitlements are granted one at a time. If the request fails partway through, the principal stays assigned with only some of the entitlements. Get the assignment afterwards to check which were granted.

API scopes: identity

Parameters

parentstringRequiredpath

The resource name of the workspace, in the format accounts/{account_id}/workspaces/{workspace_id}.

Request body

The assignment to create. Set its principal_id and entitlements.

namestringIDImmutable

The resource name of the assignment, in one of these formats:

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

principal_idint64RequiredImmutable

The Databricks ID of the assigned user, service principal, or group. It can't be changed after the assignment is created.

entitlementsarray of stringUnordered list

The entitlements granted directly by this assignment. Create and update set exactly this list, even if the principal also gets some of these entitlements through a group. List responses leave it empty.

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 GA

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

Replaces the entitlements of a principal's direct assignment to a workspace. The new list can't be empty.

Entitlements are changed one at a time. If the request fails partway through, only some of the changes take effect. Get the assignment afterwards to check the result.

API scopes: identity

Parameters

namestringRequiredIDImmutablepath

The resource name of the assignment, in one of these formats:

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

update_maskstringRequiredquery

The fields to update. The only supported field is entitlements.

Request body

The assignment to update. Its name identifies the assignment.

principal_idint64RequiredImmutable

The Databricks ID of the assigned user, service principal, or group. It can't be changed after the assignment is created.

entitlementsarray of stringUnordered list

The entitlements granted directly by this assignment. Create and update set exactly this list, even if the principal also gets some of these entitlements through a group. List responses leave it empty.

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 GA

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

Removes a principal's direct assignment to a workspace and revokes the entitlements it granted. The principal keeps any access it gets through groups.

Entitlements are revoked one at a time. If the request fails partway through, the principal stays assigned with some of its entitlements. You can retry the request.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the assignment, in the format accounts/{account_id}/workspaces/{workspace_id}/workspace-assignments/{principal_id}.

View as Markdown

Response

{}