Skip to main content

Account Group

View as Markdown

Group object​

A group in your Databricks account. To address a group, put its resource name in the URL: GET /api/2.0/identity/accounts/{account_id}/groups/{group_id} in account APIs, or GET /api/2.0/identity/groups/{group_id} in workspace APIs.

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}

Examples:

  • accounts/5d6c9a3e-2b4f-4e8a-9c1d-7f0b2a6e4c13/groups/8763426537429053 : Account APIs
  • groups/8763426537429053 : Workspace APIs
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. It is a numeric string that Databricks assigns when the group is created, and it is the {group_id} segment of name.

external_idstring

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

group_namestring

The display name of the group. It must be unique in the account, must not be blank, and must be shorter than 255 characters. Databricks trims surrounding whitespace. You can't use the name of a group that Databricks manages, such as admins or users.

Get a group in the account GA​

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

Gets a group by its Databricks ID.

API scopes: identity

Parameters​

namestringRequiredpath

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

Example: accounts/5d6c9a3e-2b4f-4e8a-9c1d-7f0b2a6e4c13/groups/8763426537429053

Response​

Returns the Group object.

List groups in the account GA​

GET /api/2.0/identity/{parent=accounts/*}/groups

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

API scopes: identity

Parameters​

parentstringRequiredpath

The resource name of the account to list groups in, in the format accounts/{account_id}.

Example: accounts/5d6c9a3e-2b4f-4e8a-9c1d-7f0b2a6e4c13

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.

Response​

Returns a list of Group objects.

Create a group in the account GA​

POST /api/2.0/identity/{parent=accounts/*}/groups

Creates a local group, which 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​

parentstringRequiredpath

The resource name of the account to create the group in, in the format accounts/{account_id}.

Example: accounts/5d6c9a3e-2b4f-4e8a-9c1d-7f0b2a6e4c13

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}

Examples:

  • accounts/5d6c9a3e-2b4f-4e8a-9c1d-7f0b2a6e4c13/groups/8763426537429053 : Account APIs
  • groups/8763426537429053 : Workspace APIs
external_idstring

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

group_namestring

The display name of the group. It must be unique in the account, must not be blank, and must be shorter than 255 characters. Databricks trims surrounding whitespace. You can't use the name of a group that Databricks manages, such as admins or users.

Response​

Returns the Group object.

Update a group in the account GA​

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

Updates a group. 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}

Examples:

  • accounts/5d6c9a3e-2b4f-4e8a-9c1d-7f0b2a6e4c13/groups/8763426537429053 : Account APIs
  • groups/8763426537429053 : Workspace APIs
update_maskstringRequiredquery

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

Example: 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 display name of the group. It must be unique in the account, must not be blank, and must be shorter than 255 characters. Databricks trims surrounding whitespace. You can't use the name of a group that Databricks manages, such as admins or users.

Response​

Returns the Group object.

Delete a group in the account GA​

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

Deletes a group from your account and removes it from the workspaces it's assigned to.

API scopes: identity

Parameters​

namestringRequiredpath

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

Example: accounts/5d6c9a3e-2b4f-4e8a-9c1d-7f0b2a6e4c13/groups/8763426537429053

Resolve an external group in the Databricks account Beta​

POST /api/2.0/identity/accounts/{account_id}/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 your account yet, it's added. Requires automatic identity management. If your account has group visibility filters, the group must match them.

API scopes: identity

Parameters​

account_idstringRequiredpath

The ID of the account to resolve the group in.

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}

Examples:

  • accounts/5d6c9a3e-2b4f-4e8a-9c1d-7f0b2a6e4c13/groups/8763426537429053 : Account APIs
  • groups/8763426537429053 : Workspace APIs
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. It is a numeric string that Databricks assigns when the group is created, and it is the {group_id} segment of name.

external_idstring

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

group_namestring

The display name of the group. It must be unique in the account, must not be blank, and must be shorter than 255 characters. Databricks trims surrounding whitespace. You can't use the name of a group that Databricks manages, such as admins or users.