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.
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 tourn: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.
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.
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.
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 |