SCIM API 2.0 (ServicePrincipals) for workspaces
Important
This article’s content has been retired and might not be updated. See Service Principals in the Databricks REST API Reference.
Preview
This feature is in Public Preview.
This is a reference article for the workspace-level SCIM API for Service Principals.
You can use the SCIM (ServicePrincipals) to create, read, update, and delete Databricks service principals. A workspace admin can also create or revoke a personal access token on behalf of a service principal. You can also use this API to list and read information about service principals.
For information about using APIs to provision service principals 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 _.
For error codes, see _.
For more examples, see Service principals for Databricks automation.
Requirements
Your Databricks account must have the Premium plan or above.
To provision and manage service principals, your Databricks workspace must be on the E2 version of the Databricks platform. For information about creating E2 workspaces, see Create a workspace using the account console. All new Databricks accounts and most existing accounts are now E2. If you are not sure which account type you have, contact your Databricks representative.
Get service principals
Endpoint |
HTTP Method |
---|---|
|
|
Retrieve a list of all service principals in the Databricks workspace.
When invoked by a non-admin user, only the username, user display name, and object are returned.
Examples
curl --netrc -X GET \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals \
| jq .
You can use filters to specify subsets of service principals. For example, you can apply the eq
(equals) filter parameter to applicationId
to retrieve a specific service principal:
curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals?filter=applicationId+eq+<application-id>" \
| jq .
In workspaces with a large number of service principals, you can exclude attributes from the request to improve performance.
curl --netrc -X GET \
"https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals?excludedAttributes=entitlements,groups" \
| jq .
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<application-id>
with theapplicationId
value of the service principal, for example12345a67-8b9c-0d1e-23fa-4567b89cde01
.
Get service principal by ID
Endpoint |
HTTP Method |
---|---|
|
|
Retrieve a single service principal resource from the Databricks workspace, given a service principal ID.
Example
curl --netrc -X GET \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
| jq .
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.
Create service principal
Endpoint |
HTTP Method |
---|---|
|
|
Create a service principal in the Databricks workspace. The service principal will automatically be added to the account. See How does Databricks sync identities between workspaces and the account?. Service principals count toward the limit of 10000 users per workspace.
Request parameters follow the standard SCIM 2.0 protocol.
Note
The applicationId
is randomly generated. In an identity federated workspace, you can specify the applicationId
of an account-level service principal to assign that service principal to your workspace.
Each service principal has a unique applicationId
. However, multiple service principals can have the same display name.
Example
curl --netrc -X POST \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals \
--header 'Content-type: application/scim+json' \
--data @create-service-principal.json \
| jq .
create-service-principal.json
:
{
"displayName": "<display-name>",
"entitlements": [
{
"value": "allow-cluster-create"
}
],
"groups": [
{
"value": "<group-id>"
}
],
"schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal" ],
"active": true
}
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<display-name>
with the display name of the service principal, for examplesomeone@example.com
.<group-id>
with the ID of the group in the Databricks workspace, for example2345678901234567
. To get the group ID, call Get groups.
This example uses a .netrc file and jq.
For lists of available entitlements by Databricks identity type, see:
Update service principal by ID (PATCH)
Endpoint |
HTTP Method |
---|---|
|
|
Update a service principal resource with operations on specific attributes,
except for displayName
, applicationId
, and id
, which are immutable.
Use the PATCH
method to add, update, or remove individual attributes.
Use the PUT method to overwrite the
entire service principal in a single operation.
Request parameters follow the standard SCIM 2.0 protocol and depend on the value
of the schemas
attribute.
Add entitlements
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @change-service-principal.json \
| jq .
change-service-principal.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
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.
This example uses a .netrc file and jq.
For lists of available entitlements by Databricks identity type, see:
Remove entitlements
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @change-service-principal.json \
| jq .
change-service-principal.json
:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "remove",
"path": "entitlements",
"value": [
{
"value": "allow-cluster-create"
}
]
}
]
}
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.
This example uses a .netrc file and jq.
For lists of available entitlements by Databricks identity type, see:
Add to a group
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @change-service-principal.json \
| jq .
change-service-principal.json
:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "add",
"path": "groups",
"value": [
{
"value": "<group-id>"
}
]
}
]
}
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.<group-id>
with the ID of the group in the Databricks workspace, for example2345678901234567
. To get the group ID, call Get groups.
Remove from a group
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/Groups/<group-id> \
--header 'Content-type: application/scim+json' \
--data @remove-from-group.json \
| jq .
remove-from-group.json
:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "remove",
"path": "members[value eq \"<service-principal-id>\"]"
}
]
}
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<group-id>
with the ID of the group in the Databricks workspace, for example2345678901234567
. To get the group ID, call Get groups.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.
Deactivate service principal by ID
To deactivate a service principal, set its active
attribute to false
. Deactivated service principals are not automatically purged.
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @deactivate-service-principal.json \
| jq .
deactivate-service-principal.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
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.
Update service principal by ID (PUT)
Endpoint |
HTTP Method |
---|---|
|
|
Overwrite the entire service principal resource, except for displayName
, applicationId
, and id
, which are immutable.
Use the PATCH method to add, update, or remove individual attributes.
Important
You must include the schemas
attribute in the request, with the exact
value urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal
.
Examples
Add an entitlement
curl --netrc -X PUT \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @update-service-principal.json \
| jq .
update-service-principal.json
:
{
"schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal" ],
"applicationId": "<applicationId-id>",
"displayName": "<display-name>",
"groups": [
{
"value": "<group-id>"
}
],
"entitlements": [
{
"value":"allow-cluster-create"
}
]
}
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.<application-id>
with theapplicationId
value of the service principal, for example12345a67-8b9c-0d1e-23fa-4567b89cde01
.<display-name>
with the display name of the service principal, for examplesomeone@example.com
.<group-id>
with the ID of the group in the Databricks workspace, for example2345678901234567
. To get the group ID, call Get groups.
This example uses a .netrc file and jq.
For lists of available entitlements by Databricks identity type, see:
Remove all entitlements and groups
Removing all entitlements and groups is a reversible alternative to deleting the service principal.
Use the PUT
method to avoid the need to check the existing entitlements and
group memberships first.
curl --netrc -X PUT \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @update-service-principal.json \
| jq .
update-service-principal.json
:
{
"schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal" ],
"applicationId": "<application-id>",
"displayName": "<display-name>",
"groups": [],
"entitlements": []
}
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.<application-id>
with theapplicationId
value of the service principal, for example12345a67-8b9c-0d1e-23fa-4567b89cde01
.<display-name>
with the display name of the service principal, for examplesomeone@example.com
.
This example uses a .netrc file and jq.
Add role to a service principal by ID
Endpoint |
HTTP Method |
---|---|
|
|
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id> \
--header 'Content-type: application/scim+json' \
--data @add-role-to-service-principal.json \
| jq .
add-role-to-service-principal.json
:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "add",
"path": "roles",
"value": [
{
"value": "<role-arn> or <instance-profile-role-arn>"
}
]
}
]
}
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.<role-arn>
with the Amazon Resource Name (ARN) of the role, for examplearn:aws:iam::123456789012:role/my-role
.<instance-profile-role-arn>
with the Amazon Resource Name (ARN) of the instance profile role, for examplearn:aws:iam::123456789012:instance-profile/my-role
.
Remove role from a service principal by ID
Endpoint |
HTTP Method |
---|---|
|
|
Example
curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<user-id> \
--header 'Content-type: application/scim+json' \
--data @remove-role-from-service-principal.json \
| jq .
remove-role-from-service-principal.json
:
{
"schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
"Operations": [
{
"op": "remove",
"path": "roles[value eq \"<role-arn> or <instance-profile-role-arn>\"]"
}
]
}
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.<role-arn>
with the Amazon Resource Name (ARN) of the role, for examplearn:aws:iam::123456789012:role/my-role
.<instance-profile-role-arn>
with the Amazon Resource Name (ARN) of the instance profile role, for examplearn:aws:iam::123456789012:instance-profile/my-role
.
Delete service principal by ID
Endpoint |
HTTP Method |
---|---|
|
|
Delete a service principal resource. This operation isn’t reversible.
Example
curl --netrc -X DELETE \
https://<databricks-instance>/api/2.0/preview/scim/v2/ServicePrincipals/<service-principal-id>
Replace:
<databricks-instance>
with the Databricks workspace instance name, for exampledbc-a1b2345c-d6e7.cloud.databricks.com
.<service-principal-id>
with the ID of the service principal, for example2345678901234567
. To get the service principal ID, call Get service principals.
This example uses a .netrc file.
As a reversible alternative, you can remove all of its entitlements and groups instead of deleting the service principal.