SCIM API (Users)

Preview

This feature is in Public Preview.

Note

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

SCIM (Users) lets you 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 Databricks.

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.

Example request 

GET /api/2.0/preview/scim/v2/Users  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

You can use filters to specify subsets of users. For example, you can apply the eq (equals) filter parameter to userName to retrieve a specific user or subset of users:

GET /api/2.0/preview/scim/v2/Users?filter=userName+eq+example@databricks.com  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

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 

GET /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Example 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"
}

Create user

Endpoint HTTP Method
2.0/preview/scim/v2/Users POST

Admin users: Create a user in the Databricks workspace.

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 request 

POST /api/2.0/preview/scim/v2/Users HTTP/1.1
Host: <databricks-instance>
Authorization: Bearer dapi48…a6138b
Content-Type: application/scim+json

{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName":"example@databricks.com",
  "groups":[
    {
       "value":"123456"
    }
  ],
  "entitlements":[
    {
       "value":"allow-cluster-create"
    }
  ]
}

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 request 

PATCH /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <databricks-instance>
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b

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

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 request 

PUT /api/2.0/preview/scim/v2/Users/123456  HTTP/1.1
Host: example.cloud.databricks.com
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b

{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName":"example@databricks.com",
  "entitlements":[
    {
       "value":"allow-cluster-create"
    }
  ],
  "roles":[
    {
       "value":"arn:aws:iam::123456789:instance-profile/datascience-role"
    }
  ],
  "groups":[
    {
       "value":"100000"
    }
  ]
}

Add role to a user by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Users/{id} PATCH 
PATCH /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <databricks-instance>
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b

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

Remove role from a user by ID

Endpoint HTTP Method
2.0/preview/scim/v2/Users/{id} PATCH 
PATCH /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <databricks-instance>
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b

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

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.

Example request 

DELETE /api/2.0/preview/scim/v2/Users/100757  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Activate and deactivate user by ID

Preview

This feature is in Public Preview.

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 (PATCH)

Endpoint HTTP Method
2.0/preview/scim/v2/Users/{id} PATCH 
PATCH /api/2.0/preview/scim/v2/Users/100008  HTTP/1.1
Host: <databricks-instance>
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b

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

Example response 

{
  "emails": [
    {
      "type": "work",
      "value": "test.user@databricks.com",
      "primary": true
    }
  ],
  "displayName": "test 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": "test"
  },
  "active": false,
  "groups": [],
  "id": "100008",
  "userName": "test.user@databricks.com"
}

Example request (PUT)

Endpoint HTTP Method
2.0/preview/scim/v2/Users/{id} PUT 
PUT /api/2.0/preview/scim/v2/Users/100008  HTTP/1.1
Host: <databricks-instance>
Content-Type: application/scim+json
Authorization: Bearer dapi48…a6138b

{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName":"example@databricks.com",
  "entitlements":[
    {
      "value":"allow-cluster-create"
    }
  ],
  "roles":[
    {
      "value":"arn:aws:iam::123456789:instance-profile/datascience-role"
    }
  ],
  "groups":[
    {
      "value":"100000"
    }
  ],
  "active": false
}

Example response 

{
  "emails": [
    {
      "type": "work",
      "value": "example@databricks.com",
      "primary": true
    }
  ],
  "entitlements": [
    {
      "value": "allow-cluster-create"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:workspace:2.0:User"
  ],
  "active": false,
  "groups": [],
  "id": "100008",
  "userName": "example@databricks.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 request 

GET /api/2.0/preview/scim/v2/Usersfilter=active+eq+false HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

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 request 

PATCH /api/2.0/preview/workspace-conf HTTP/1.1
Host: <databricks-instance>
Content-Type: application/json
Authorization: Bearer dapi48…a6138b

{
  "maxUserInactiveDays": "90"
}

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 

GET /api/2.0/preview/workspace-conf?keys=maxUserInactiveDays HTTP/1.1
Host: <databricks-instance>
Accept: application/json
Authorization: Bearer dapi48…a6138b

Example response 

{
  "maxUserInactiveDays": "90",
}