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
Your Databricks account must have the Premium plan and above.
A Databricks workspace admin
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 |
---|---|
|
|
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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<username>
with the Databricks workspace username of the user, for examplesomeone@example.com
.
Get user by ID
Endpoint |
HTTP Method |
---|---|
|
|
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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<user-id>
with the Databricks workspace ID of the user, for example2345678901234567
. To get the user ID, call Get users.
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 |
---|---|
|
|
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 tourn: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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<username>
with the Databricks workspace username of the user, for examplesomeone@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 |
---|---|
|
|
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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<user-id>
with the Databricks workspace ID of the user, for example2345678901234567
. 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 |
---|---|
|
|
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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<user-id>
with the Databricks workspace ID of the user, for example2345678901234567
. To get the user ID, call Get users.<username>
with the Databricks workspace username of the user, for examplesomeone@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 |
---|---|
|
|
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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<user-id>
with the Databricks workspace ID of the user, for example2345678901234567
. To get the user ID, call Get users.<role-arn>
with the Amazon Resource Name (ARN) of the role, for examplearn:aws:iam::123456789012:role/my-role
.
Remove role from a user by ID
Endpoint |
HTTP Method |
---|---|
|
|
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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<user-id>
with the Databricks workspace ID of the user, for example2345678901234567
. To get the user ID, call Get users.<role-arn>
with the Amazon Resource Name (ARN) of the role, for examplearn:aws:iam::123456789012:role/my-role
.
Delete user by ID
Endpoint |
HTTP Method |
---|---|
|
|
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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<user-id>
with the Databricks workspace ID of the user, for example2345678901234567
. 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 |
---|---|
|
|
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 exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<user-id>
with the Databricks workspace ID of the user, for example2345678901234567
.
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 |
---|---|
|
|
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
.
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 |
---|---|
|
|
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
.
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 |
---|---|
|
|
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
.