Groups API 2.0

The Groups API allows you to manage groups of users.

Note

You must be a Databricks administrator to invoke this API.

Important

To access Databricks REST APIs, you must authenticate.

Add member

Endpoint	HTTP Method
2.0/groups/add-member	POST

Add a user or group to a group. This call returns the error RESOURCE_DOES_NOT_EXIST if a user or group with the given name does not exist, or if a group with the given parent name does not exist.

Examples

To add a user to a group:

curl --netrc -X POST \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/add-member \
--data '{ "user_name": "someone@example.com", "parent_name": "reporting-department" }'

{}

To add a group to another group:

curl --netrc -X POST \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/add-member \
--data '{ "group_name": "reporting-department", "parent_name": "data-ops-read-only" }'

{}

Request structure

Field Name	Type	Description
user_name OR group_name	STRING OR STRING	If user_name, the user name. If group_name, the group name.
parent_name	STRING	Name of the parent group to which the new member will be added. This field is required.

Create

Endpoint	HTTP Method
2.0/groups/create	POST

Create a new group with the given name. This call returns an error RESOURCE_ALREADY_EXISTS if a group with the given name already exists.

Example

curl --netrc -X POST \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/create \
--data '{ "group_name": "reporting-department" }'

{ "group_name": "reporting-department" }

Request structure

Field Name	Type	Description
group_name	STRING	Name for the group; must be unique among groups owned by this organization. This field is required.

Response structure

Field Name	Type	Description
group_name	STRING	The group name.

List members

Endpoint	HTTP Method
2.0/groups/list-members	GET

Return all of the members of a particular group. This call returns the error RESOURCE_DOES_NOT_EXIST if a group with the given name does not exist. This method is non-recursive; it returns all groups that belong to the given group but not the principals that belong to those child groups.

Example

curl --netrc -X GET \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/list-members \
--data '{ "group_name": "reporting-department" }' \
| jq .

{
  "members": [
    {
      "user_name": "someone@example.com"
    }
  ]
}

Request structure

Field Name	Type	Description
group_name	STRING	The group whose members we want to retrieve. This field is required.

Response structure

Field Name	Type	Description
members	An array of PrincipalName	The users and groups that belong to the given group.

List

Endpoint	HTTP Method
2.0/groups/list	GET

Return all of the groups in an organization.

Example

curl --netrc -X GET \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/list \
| jq .

{
  "group_names": [
    "reporting-department",
    "data-ops-read-only",
    "admins"
  ]
}

Response structure

Field Name	Type	Description
group_names	An array of STRING	The groups in this organization.

List parents

Endpoint	HTTP Method
2.0/groups/list-parents	GET

Retrieve all groups in which a given user or group is a member. This method is non-recursive; it returns all groups in which the given user or group is a member but not the groups in which those groups are members. This call returns the error RESOURCE_DOES_NOT_EXIST if a user or group with the given name does not exist.

Examples

To list groups for a user:

curl --netrc -X GET \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/list-parents \
--data '{ "user_name": "someone@example.com" }' \
| jq .

{
  "group_names": [
    "reporting-department"
  ]
}

To list parent groups for a group:

curl --netrc -X GET \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/list-parents \
--data '{ "group_name": "reporting-department" }' \
| jq .

{
  "group_names": [
    "data-ops-read-only"
  ]
}

Request structure

Field Name	Type	Description
user_name OR group_name	STRING OR STRING	If user_name, the user name. If group_name, the group name.

Response structure

Field Name	Type	Description
group_names	An array of STRING	The groups in which the given user or group is a member.

Remove member

Endpoint	HTTP Method
2.0/groups/remove-member	POST

Remove a user or group from a group. This call returns the error RESOURCE_DOES_NOT_EXIST if a user or group with the given name does not exist or if a group with the given parent name does not exist.

Examples

To remove a user from a group:

curl --netrc -X POST \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/remove-member \
--data '{ "user_name": "someone@example.com", "parent_name": "reporting-department" }'

{}

To remove a group from another group:

curl --netrc -X POST \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/remove-member \
--data '{ "group_name": "reporting-department", "parent_name": "data-ops-read-only" }'

{}

Request structure

Field Name	Type	Description
user_name OR group_name	STRING OR STRING	If user_name, the user name. If group_name, the group name.
parent_name	STRING	Name of the parent group from which the member will be removed. This field is required.

Delete

Endpoint	HTTP Method
2.0/groups/delete	POST

Remove a group from this organization. This call returns the error RESOURCE_DOES_NOT_EXIST if a group with the given name does not exist.

Example

curl --netrc -X POST \
https://1234567890123456.7.gcp.databricks.com/api/2.0/groups/delete \
--data '{ "group_name": "reporting-department" }'

{}

Request structure

Field Name	Type	Description
group_name	STRING	The group to remove. This field is required.

Data structures

PrincipalName

Container type for a name that is either a user name or a group name.

Field Name	Type	Description
user_name OR group_name	STRING OR STRING	If user_name, the user name. If group_name, the group name.