Workspace Group

View as Markdown

A group in your Databricks account.

Get a group in the accountGET /api/2.0/identity/{name=groups/*}List groups in the accountGET /api/2.0/identity/groupsCreate a group in the accountPOST /api/2.0/identity/groupsUpdate a group in the accountPATCH /api/2.0/identity/{name=groups/*}Delete a group in the accountDELETE /api/2.0/identity/{name=groups/*}Resolve an external group in the Databricks accountPOST /api/2.0/identity/groups/resolve-by-external-id

Group object

A group in your Databricks account.

namestringIDImmutable

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

• Account APIs: accounts/{account_id}/groups/{group_id}
• Workspace APIs: groups/{group_id}

parentstringOutput onlyImmutable

The resource name of the account that contains the group, in the format accounts/{account_id}. Workspace APIs return the same format.

account_idstringOutput onlyImmutable

The ID of the account that contains the group.

group_idstringOutput onlyImmutable

The Databricks ID of the group.

external_idstring

The ID of the group in your identity provider (IdP).

group_namestring

The name of the group.

View as Markdown

The Group object

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "group_id": "string",
  "external_id": "string",
  "group_name": "string"
}

Get a group in the account GA

GET /api/2.0/identity/{name=groups/*}

Gets a group in the account that contains this workspace by its Databricks ID.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the group, in the format groups/{group_id}.

Response

Returns the Group object.

View as Markdown

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "group_id": "string",
  "external_id": "string",
  "group_name": "string"
}

List groups in the account GA

GET /api/2.0/identity/groups

Lists the groups in the account that contains this workspace, sorted by Databricks ID. Groups in your identity provider that haven't been added to Databricks aren't included.

API scopes: identity

Parameters

page_sizeint32query

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

page_tokenstringquery

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

filterstringquery

Filters groups by group_name or external_id, for example group_name eq "Data engineers". Put the value in quotes.

parentstringquery

The resource name of the account to list groups in, in the format accounts/{account_id}. Defaults to the account that contains this workspace. Any other account is rejected.

Response

Returns a list of Group objects.

View as Markdown

Response

{
  "groups": [
    {
      "name": "string",
      "parent": "string",
      "account_id": "string",
      "group_id": "string",
      "external_id": "string",
      "group_name": "string"
    }
  ],
  "next_page_token": "string"
}

Create a group in the account GA

POST /api/2.0/identity/groups

Creates a local group in the account that contains this workspace. A local group is a group that isn't synced from your identity provider (IdP). You become a manager of the new group.

If automatic identity management is on, you can't set external_id. To add a group from your IdP, get it as an external group instead.

API scopes: identity

Parameters

parentstringquery

The resource name of the account to create the group in, in the format accounts/{account_id}. Defaults to the account that contains this workspace. Any other account is rejected.

Request body

The group to create.

namestringIDImmutable

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

• Account APIs: accounts/{account_id}/groups/{group_id}
• Workspace APIs: groups/{group_id}

external_idstring

The ID of the group in your identity provider (IdP).

group_namestring

The name of the group.

Response

Returns the Group object.

View as Markdown

Request

{
  "name": "string",
  "external_id": "string",
  "group_name": "string"
}

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "group_id": "string",
  "external_id": "string",
  "group_name": "string"
}

Update a group in the account GA

PATCH /api/2.0/identity/{name=groups/*}

Updates a group in the account that contains this workspace. Only the fields in update_mask change.

If automatic identity management is on and the group has an external_id, you can only update external_id. The group's other fields come from your identity provider. If your account also has group visibility filters, a new external_id must match them. You can always clear external_id.

API scopes: identity

Parameters

namestringRequiredIDImmutablepath

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

• Account APIs: accounts/{account_id}/groups/{group_id}
• Workspace APIs: groups/{group_id}

update_maskstringRequiredquery

The fields to update, separated by commas. You can update group_name and external_id.

Request body

The group to update. Its name identifies the group.

external_idstring

The ID of the group in your identity provider (IdP).

group_namestring

The name of the group.

Response

Returns the Group object.

View as Markdown

Request

{
  "external_id": "string",
  "group_name": "string"
}

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "group_id": "string",
  "external_id": "string",
  "group_name": "string"
}

Delete a group in the account GA

DELETE /api/2.0/identity/{name=groups/*}

Deletes a group from the account that contains this workspace and removes it from the workspaces it's assigned to.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the group, in the format groups/{group_id}.

View as Markdown

Response

{}

Resolve an external group in the Databricks account Beta

POST /api/2.0/identity/groups/resolve-by-external-id

Gets a group by its ID in your identity provider (IdP) and syncs its name and parent groups from your IdP. If the group isn't in the account that contains this workspace yet, it's added. Requires automatic identity management. If your account has group visibility filters, the group must match them.

API scopes: identity

Request body

external_idstringRequired

The ID of the group in your IdP.

Response

groupobject

The resolved group.

Show child attributesHide child attributes

namestringIDImmutable

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

• Account APIs: accounts/{account_id}/groups/{group_id}
• Workspace APIs: groups/{group_id}

parentstringOutput onlyImmutable

The resource name of the account that contains the group, in the format accounts/{account_id}. Workspace APIs return the same format.

account_idstringOutput onlyImmutable

The ID of the account that contains the group.

group_idstringOutput onlyImmutable

The Databricks ID of the group.

external_idstring

The ID of the group in your identity provider (IdP).

group_namestring

The name of the group.

View as Markdown

Request

{
  "external_id": "string"
}

Response

{
  "group": {
    "name": "string",
    "parent": "string",
    "account_id": "string",
    "group_id": "string",
    "external_id": "string",
    "group_name": "string"
  }
}