SCIM API (ServicePrincipals)

Preview

This feature is in Public Preview.

SCIM (ServicePrincipals) lets you manage Databricks service principals. An admin user can also create or revoke a personal access token on behalf of a service principal.

Requirements

Get service principals

Endpoint HTTP Method
2.0/preview/scim/v2/ServicePrincipals GET

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.

Example request

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

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:

GET /api/2.0/preview/scim/v2/ServicePrincipals?filter=applicationId+eq+b4647a57-063a-43e3-a6b4-c9a4e9f9f0b7  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

In workspaces with a large number of service principals, you can exclude attributes from the request to improve performance.

GET /api/2.0/preview/scim/v2/ServicePrincipals?excludedAttributes=entitlements,groups  HTTP/1.1
Host: <databricks-instance>
Accept: application/scim+json
Authorization: Bearer dapi48…a6138b

Get service principal by ID

Endpoint HTTP Method
2.0/preview/scim/v2/ServicePrincipals/{id} GET

Retrieve a single service principal resource from the Databricks workspace, given a Databricks ID.

Example request

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

Create service principal

Create a service principal in the Databricks workspace. Service principals count toward the limit of 10000 users per workspace.

Request parameters follow the standard SCIM 2.0 protocol.

Note

Do not specify applicationId; it is randomly generated.

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

Example request

POST /api/2.0/preview/scim/v2/ServicePrincipals HTTP/1.1
Host: <databricks-instance>
Authorization: Bearer dapi48…a6138b
Content-Type: application/scim+json
{
  "displayName": "Example Service Principal",
  "entitlements": [
       {
           "value": "allow-cluster-create"
       }
   ],
   "groups": [
       {
           "value": "1441065999988368"
       }
   ],
   "schemas": [
       "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal"
    ],
   "active": true
}

Update service principal by ID (PATCH)

Endpoint HTTP Method
2.0/preview/scim/v2/ServicePrincipals/{id} PATCH

Update a service principal resource with operations on specific attributes, except for 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 request

PATCH /api/2.0/preview/scim/v2/ServicePrincipals/654321  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"
        }
      ]
    }
  ]
}

Remove entitlements

Example request

PATCH /api/2.0/preview/scim/v2/ServicePrincipals/654321  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":"entitlements",
      "value":[
        {
           "value":"allow-cluster-create"
        }
      ]
    }
  ]
}

Add to a group

Example request

PATCH /api/2.0/preview/scim/v2/ServicePrincipals/654321  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":"groups",
      "value":[
        {
           "value":"123456"
        }
      ]
    }
  ]
}

Remove from a group

Example request

PATCH /api/2.0/preview/scim/v2/Groups/<group_id>  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":"members[value eq \"<service_principal_id>\"]"
    }
  ]
}

Deactivate service principal by ID

To deactivate a service principal, set its active attribute to false. Deactivated service principals are not automatically purged.

PATCH /api/2.0/preview/scim/v2/ServicePrincipals/654321  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"
        }
      ]
    }
  ]
}

Update service principal by ID (PUT)

Endpoint HTTP Method
2.0/preview/scim/v2/ServicePrincipals/{id} PUT

Overwrite the entire service principal resource, except for 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.

Example request

Add an entitlement

PUT /api/2.0/preview/scim/v2/ServicePrincipals/654321 HTTP/1.1
Host: <databricks-instance>
Authorization: Bearer dapi48…a6138b
Content-Type: application/scim+json
{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal"
  ],
  "applicationId":"b4647a57-063a-43e3-a6b4-c9a4e9f9f0b7",
  "displayName":"test-service-principal",
  "groups":[
    {
       "value":"123456"
    }
  ],
  "entitlements":[
    {
       "value":"allow-cluster-create"
    }
  ]
}

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.

PUT /api/2.0/preview/scim/v2/ServicePrincipals/654321 HTTP/1.1
Host: <databricks-instance>
Authorization: Bearer dapi48…a6138b
Content-Type: application/scim+json
{
  "schemas":[
    "urn:ietf:params:scim:schemas:core:2.0:ServicePrincipal"
  ],
  "applicationId":"b4647a57-063a-43e3-a6b4-c9a4e9f9f0b7",
  "displayName":"test-service-principal",
  "groups":[],
  "entitlements":[]
}

Delete service principal by ID

Endpoint HTTP Method
2.0/preview/scim/v2/ServicePrincipals/{id} DELETE

Delete a service principal resource. This operation isn’t reversible.

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

As a reversible alternative, you can remove all of its entitlements and groups instead of deleting the service principal.