Groups API 2.0 (legacy)
The Groups API (legacy) allows you to manage groups of users.
Note
The functionality provided by this API is also available in the SCIM API. Databricks recommends that you use that API instead.
You must be an Azure 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.
Note
You cannot use this call in identity federation workspaces. Use SCIM API 2.0 (Accounts) to manage account groups and SCIM (Groups) API to manage workspace-local groups. For more information, see Special considerations for groups.
Examples
To add a user to a group:
curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/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://adb-1234567890123456.7.azuredatabricks.net/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.
Note
You cannot use this call in identity federation workspaces. Use SCIM API 2.0 (Accounts) to create account groups and SCIM (Groups) API to create workspace-local groups. For more information, see Special considerations for groups.
Example
curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/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://adb-1234567890123456.7.azuredatabricks.net/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://adb-1234567890123456.7.azuredatabricks.net/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://adb-1234567890123456.7.azuredatabricks.net/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://adb-1234567890123456.7.azuredatabricks.net/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.
Note
You cannot use this call in identity federation workspaces. Use SCIM API 2.0 (Accounts) to manage account groups and SCIM (Groups) API to manage workspace-local groups. For more information, see Special considerations for groups.
Examples
To remove a user from a group:
curl --netrc -X POST \
https://adb-1234567890123456.7.azuredatabricks.net/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://adb-1234567890123456.7.azuredatabricks.net/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://adb-1234567890123456.7.azuredatabricks.net/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. |
Feedback
Submit and view feedback for