SCIM API 2.0 (Users) for workspaces

Preview

This feature is in Public Preview.

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

You can use the SCIM (Users) API to create users in Databricks and give them the proper level of access, add roles to and remove roles from users, temporarily lock and unlock user accounts, and remove access for users (deprovision them) when they leave your organization or no longer need access to the Databricks workspace.

For information about using APIs to provision users directly 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

can invoke all SCIM API endpoints. Non-admin users can invoke the Get users endpoint to read user display names and IDs.

Note

Each workspace can have a maximum of 10,000 users and 5,000 groups. Service principals count toward the user maximum.

Get users

Endpoint

HTTP Method

2.0/preview/scim/v2/Users

GET

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

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

Examples

This example gets information about all users.

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

This example uses the eq (equals) filter query parameter with userName to get information about a specific user.

curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/scim/v2/Users?filter=userName+eq+<username>" \
| jq .

Replace:

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

  • <username> with the Databricks workspace username of the user, for example someone@example.com.

This example uses a .netrc file and jq.

Get user by ID

Endpoint

HTTP Method

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

GET

Admin users: Retrieve a single user resource from the Databricks workspace, given their Databricks ID.

Example

Request 

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

Replace:

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

  • <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.

Response 

{
  "entitlements":[
    {
      "value":"allow-cluster-create"
    }
  ],
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "roles": [
    {
      "value": "arn:aws:iam::123456789012:role/<role-name>"
    }
  ],
  "groups":[
    {
      "value":"123456"
    }
  ],
  "userName":"example@databricks.com"
}

For lists of available entitlements by Databricks identity type, see:

Create user

Endpoint

HTTP Method

2.0/preview/scim/v2/Users

POST

Admin users: Create a user in the Databricks workspace. The user will automatically be added to the account. See How does Databricks sync identities between workspaces and the account?.

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:User

  • userName

Example 

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

create-user.json:

{
  "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ],
  "userName": "<username>",
  "groups": [
    {
       "value":"123456"
    }
  ],
  "entitlements":[
    {
       "value":"allow-cluster-create"
    }
  ]
}

Replace:

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

  • <username> with the Databricks workspace username of the user, for example someone@example.com.

This example uses a .netrc file and jq.

For lists of available entitlements by Databricks identity type, see:

Update user by ID (PATCH)

Endpoint

HTTP Method

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

PATCH

Admin users: Update a user resource with operations on specific attributes, except those that are immutable (userName and userId). The PATCH method is recommended over the PUT method for setting or updating user entitlements.

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

Example

This example adds the allow-cluster-create entitlement to the specified user.

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

update-user.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "add",
      "path": "entitlements",
      "value": [
        {
           "value": "allow-cluster-create"
        }
      ]
    }
  ]
}

Replace:

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

  • <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.

For lists of available entitlements by Databricks identity type, see:

Update user by ID (PUT)

Endpoint

HTTP Method

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

PUT

Admin users: Overwrite the user resource across multiple attributes, except those that are immutable (userName and userId).

Request must include the schemas attribute, set to urn:ietf:params:scim:schemas:core:2.0:User.

Note

The PATCH method is recommended over the PUT method for setting or updating user entitlements.

Example

This example changes the specified user’s previous entitlements to now have only the allow-cluster-create entitlement.

curl --netrc -X PUT \
https://<databricks-instance>/api/2.0/preview/scim/v2/Users/<user-id> \
--header 'Content-type: application/scim+json' \
--data @overwrite-user.json \
| jq .

overwrite-user.json:

{
  "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ],
  "userName": "<username>",
  "entitlements": [
    {
      "value": "allow-cluster-create"
    }
  ]
}

Replace:

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

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

  • <username> with the Databricks workspace username of the user, for example someone@example.com. To get the username, call Get users.

This example uses a .netrc file and jq.

For lists of available entitlements by Databricks identity type, see:

Add role to a user by ID

Endpoint

HTTP Method

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

PATCH

Example 

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

add-role-to-user.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.

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

  • <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 user by ID

Endpoint

HTTP Method

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

PATCH

Example 

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

remove-role-from-user.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.

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

  • <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.

Delete user by ID

Endpoint

HTTP Method

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

DELETE

Admin users: Remove a user resource. A user that does not own or belong to a workspace in Databricks is automatically purged after 30 days.

Deleting a user from a workspace also removes objects associated with the user. For example, notebooks are archived, clusters are terminated, and jobs become ownerless.

The user’s home directory is not automatically deleted. Only an administrator can access or remove a deleted user’s home directory.

The access control list (ACL) configuration of a user is preserved even after that user is removed from a workspace.

Example request 

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

Replace:

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

  • <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.

Activate and deactivate user by ID

Preview

This feature is in Public Preview.

Endpoint

HTTP Method

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

PATCH

Admin users: Activate or deactivate a user. Deactivating a user removes all access to a workspace for that user but leaves permissions and objects associated with the user unchanged. Clusters associated with the user keep running, and notebooks remain in their original locations. The user’s tokens are retained but cannot be used to authenticate while the user is deactivated. Scheduled jobs, however, fail unless assigned to a new owner.

You can use the Get users and Get user by ID requests to view whether users are active or inactive.

Note

Allow at least five minutes for the cache to be cleared for deactivation to take effect.

Set the active value to false to deactivate a user and true to activate a user.

Example

Request 

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

toggle-user-activation.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": [
        {
          "value": "false"
        }
      ]
    }
  ]
}

Replace:

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

  • <user-id> with the Databricks workspace ID of the user, for example 2345678901234567.

This example uses a .netrc file and jq.

Response 

{
  "emails": [
    {
      "type": "work",
      "value": "someone@example.com",
      "primary": true
    }
  ],
  "displayName": "Someone User",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:workspace:2.0:User"
  ],
  "name": {
    "familyName": "User",
    "givenName": "Someone"
  },
  "active": false,
  "groups": [],
  "id": "123456",
  "userName": "someone@example.com"
}

Filter active and inactive users

Preview

This feature is in Public Preview.

Endpoint

HTTP Method

2.0/preview/scim/v2/Users

GET

Admin users: Retrieve a list of active or inactive users.

Example 

curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/scim/v2/Users?filter=active+eq+false" \
| 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.

Automatically deactivate users

Preview

This feature is in Public Preview.

Admin users: Deactivate users that have not logged in for a customizable period. Scheduled jobs owned by a user are also considered activity.

Endpoint

HTTP Method

2.0/preview/workspace-conf

PATCH

The request body is a key-value pair where the value is the time limit for how long a user can be inactive before being automatically deactivated.

Example 

curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/workspace-conf \
--data @deactivate-users.json \
| jq .

deactivate-users.json:

{
  "maxUserInactiveDays": "90"
}

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 the maximum user inactivity period of a workspace

Preview

This feature is in Public Preview.

Admin users: Retrieve the user inactivity limit defined for a workspace.

Endpoint

HTTP Method

2.0/preview/workspace-conf

GET

Example request 

curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/workspace-conf?keys=maxUserInactiveDays" \
| 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.

Example response 

{
  "maxUserInactiveDays": "90"
}