SCIM API 2.0 (Groups) for workspaces

Preview

This feature is in Public Preview.

This is a reference article for the workspace-level SCIM API for Groups.

You can use the SCIM (Groups) API to create workspace-local groups in Databricks workspaces, give them the proper level of access, remove access for groups (deprovision them), and add roles to and remove roles from groups. You can also use this API to list and read information about groups.

For information about using APIs to provision groups to your account instead, see SCIM API 2.0 (Accounts).

For information about when to use account-level or workspace-level SCIM provisioning, see Account-level and workspace-level SCIM provisioning.

For error codes, see SCIM API 2.0 Error Codes.

Requirements

Your Databricks account must have the Premium plan or above.

Note

  • A Databricks workspace administrator can invoke all SCIM API endpoints.

  • Non-admin users can invoke the Get groups endpoint to read group display names and IDs.

  • You can have no more than 10,000 users and 5,000 groups in a workspace.

Get groups

Endpoint

HTTP Method

2.0/preview/scim/v2/Groups

GET

Admin users: Retrieve a list of all groups in the Databricks workspace.

Non-admin users: Retrieve a list of all groups in the Databricks workspace, returning group display name and object ID only.

Examples

curl --netrc -X GET \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups \
| jq .

You can use filters to specify subsets of groups. For example, you can apply the sw (starts with) filter parameter to displayName to retrieve a specific group or set of groups. This example retrieves all groups with a displayName field that start with my-.

curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/scim/v2/Groups?filter=displayName+sw+my-" \
| jq .

Replace <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.

This example uses a .netrc file and jq.

Get group by ID

Endpoint

HTTP Method

2.0/preview/scim/v2/Groups/{id}

GET

Admin users: Retrieve a single group resource.

Example request

curl --netrc -X GET \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
| jq .

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.

  • <group-id> with the ID of the group in the Databricks workspace, for example 2345678901234567. To get the group ID, call Get groups.

This example uses a .netrc file and jq.

Create group

Endpoint

HTTP Method

2.0/preview/scim/v2/Groups

POST

Admin users: Create a workspace-local group in Databricks.

Request parameters follow the standard SCIM 2.0 protocol.

Requests must include the following attributes:

  • schemas set to urn:ietf:params:scim:schemas:core:2.0:Group

  • displayName

Members list is optional and can include users and other groups. You can also add members to a group using PATCH.

Example

curl --netrc -X POST \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups \
--header 'Content-type: application/scim+json' \
--data @create-group.json \
| jq .

create-group.json:

{
  "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ],
  "displayName": "<group-name>",
  "members": [
    {
      "value":"<user-id>"
    }
  ]
}

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.

  • <group-name> with the name of the group in the Databricks workspace, for example my-group.

  • <user-id> with the Databricks workspace ID of the user, for example 2345678901234567. To get the user ID, call Get users.

This example uses a .netrc file and jq.

Update group

Endpoint

HTTP Method

2.0/preview/scim/v2/Groups/{id}

PATCH

Admin users: Update a workspace-local group in a Databricks workspace by adding or removing members. Can add and remove individual members or groups within the group.

Request parameters follow the standard SCIM 2.0 protocol and depend on the value of the schemas attribute.

Note

Databricks does not support updating group names.

Example

curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
--header 'Content-type: application/scim+json' \
--data @update-group.json \
| jq .

Add to group

update-group.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op":"add",
      "value": {
        "members": [
          {
            "value":"<user-id>"
          }
        ]
      }
    }
  ]
}

Remove from group

update-group.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"<user-id>\"]"
    }
  ]
}

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.

  • <group-id> with the ID of the group in the Databricks workspace, for example 2345678901234567. To get the group ID, call Get groups.

  • <user-id> with the Databricks workspace ID of the user, for example 2345678901234567. To get the user ID, call Get users.

This example uses a .netrc file and jq.

Delete group

Endpoint

HTTP Method

2.0/preview/scim/v2/Groups/{id}

DELETE

Admin users: Remove a group from a Databricks workspace. Users in the group are not removed.

Example

curl --netrc -X DELETE \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id>

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.

  • <group-id> with the ID of the group in the Databricks workspace, for example 2345678901234567. To get the group ID, call Get groups.

This example uses a .netrc file.

You can also add roles to a group or remove roles from a group using the SCIM API.

Add role to a group by ID

Endpoint

HTTP Method

2.0/preview/scim/v2/Groups/{id}

PATCH

curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
--header 'Content-type: application/scim+json' \
--data @add-role-to-group.json \
| jq .

add-role-to-group.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "add",
      "path": "roles",
      "value": [
        {
          "value": "<role-arn>"
        }
      ]
    }
  ]
}

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.

  • <group-id> with the ID of the group in the Databricks workspace, for example 2345678901234567. To get the group ID, call Get groups.

  • <role-arn> with the Amazon Resource Name (ARN) of the role, for example arn:aws:iam::123456789012:role/my-role.

This example uses a .netrc file and jq.

Remove role from a group by ID

Endpoint

HTTP Method

2.0/preview/scim/v2/Groups/{id}

PATCH

curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
--header 'Content-type: application/scim+json' \
--data @remove-role-from-group.json \
| jq .

remove-role-from-group.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "remove",
      "path": "roles[value eq \"<role-arn>\"]"
    }
  ]
}

Replace:

  • <databricks-instance> with the Databricks workspace instance name, for example dbc-a1b2345c-d6e7.cloud.databricks.com.

  • <group-id> with the ID of the group in the Databricks workspace, for example 2345678901234567. To get the group ID, call Get groups.

  • <role-arn> with the Amazon Resource Name (ARN) of the role, for example arn:aws:iam::123456789012:role/my-role.

This example uses a .netrc file and jq.