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

In this section:

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.