Skip to main content

Service Principal

View as Markdown

AccountServicePrincipal object​

Represents a service principal in the Databricks account. Service principals are identities for jobs, automated tools and systems such as scripts, apps and CI/CD platforms.

activeboolean

Indicates whether the service principal is active. A deactivated service principal cannot authenticate or access Databricks APIs, but it keeps its permissions.

applicationIdstringuuid

Identifies the service principal when it authenticates to Databricks. Databricks generates the application ID, except on Azure, where it can be the application ID of a Microsoft Entra ID service principal.

displayNamestring

Identifies the service principal by a human-readable name.

Example: etl-service

externalIdstring<= 64 characters

Identifies the service principal in an external identity provider. Identity providers use it to match the service principals they manage to Databricks service principals.

idstringint64

Identifies the service principal within Databricks. Databricks generates the ID when the service principal is created.

rolesarray of object

Lists the account roles that are assigned to the service principal. The only supported role value is account_admin.

Show child attributesHide child attributes
displaystring

Provides a human-readable name for the value, such as the display name of a group member.

primaryboolean

Indicates whether this is the primary or preferred value of a multi-valued attribute. At most one value can be primary.

$refstring

References the resource that the value refers to by its URI, such as the user, service principal or group entry of a group member.

typestring

Indicates the function or kind of the value within a multi-valued attribute.

valuestring

Holds the value of the attribute. For references to other resources, such as group members, this is the ID of the referenced resource.

account_idstringuuid

Identifies the Databricks account that the service principal belongs to.

Get service principal details GA​

GET /api/2.0/accounts/{account_id}/scim/v2/ServicePrincipals/{id}

Gets the details for a single service principal in the <Databricks> account.

API scopes: scim

Parameters​

account_idstringuuidRequiredpath

Identifies the Databricks account.

idstringint64Requiredpath

Unique ID for a service principal in the <Databricks> account.

Response​

Returns the AccountServicePrincipal object.

List service principals GA​

GET /api/2.0/accounts/{account_id}/scim/v2/ServicePrincipals

Gets the set of service principals associated with a <Databricks> account.

API scopes: scim

Parameters​

account_idstringuuidRequiredpath

Identifies the Databricks account.

attributesstringquery

Comma-separated list of attributes to return in response.

countint64<= 100query

Desired number of results per page. Default is 10000.

excludedAttributesstringquery

Comma-separated list of attributes to exclude in response.

filterstringquery

Query by which the results have to be filtered. Supported operators are equals(eq), contains(co), starts with(sw) and not equals(ne). Additionally, simple expressions can be formed using logical operators - and and or. The SCIM RFC has more details but we currently only support simple expressions.

Examples:

  • displayName co "sp" and displayName co "foo" : Service principals whose displayName contains sp and displayName contains foo.
  • displayName co "bar" : Service principals whose displayName contains bar.
  • displayName eq "foo" : Service principals whose displayName equals foo.
  • displayName ne "qux" : Service principals whose displayName not equals qux.
  • displayName co "sp" or displayName co "foo" : Service principals whose displayName contains sp or displayName contains foo.
  • displayName sw "baz" : Service principals whose displayName starts with baz.
sortBystringquery

Attribute to sort the results.

sortOrderstringquery

The order to sort the results.

Values:

  • ascending
  • descending
startIndexint64query

Specifies the index of the first result. First item is number 1.

Response​

Returns a list of AccountServicePrincipal objects.

Create a service principal GA​

POST /api/2.0/accounts/{account_id}/scim/v2/ServicePrincipals

Creates a new service principal in the <Databricks> account.

API scopes: scim

Parameters​

account_idstringuuidRequiredpath

Identifies the Databricks account.

Request body​

activeboolean

Indicates whether the service principal is active. A deactivated service principal cannot authenticate or access Databricks APIs, but it keeps its permissions.

applicationIdstringuuid

Sets the application ID of a Microsoft Entra ID service principal. Only Azure accepts this field. On AWS and GCP, Databricks generates the application ID and rejects requests that set it.

displayNamestring

Sets the human-readable name of the service principal. The name is required unless the request sets applicationId.

Example: etl-service

externalIdstring

Sets the identifier of the service principal in an external identity provider.

idstringint64

Identifies the service principal within Databricks.

rolesarray of object

Lists the account roles that are assigned to the service principal. The only supported role value is account_admin.

Show child attributesHide child attributes
displaystring

Provides a human-readable name for the value, such as the display name of a group member.

primaryboolean

Indicates whether this is the primary or preferred value of a multi-valued attribute. At most one value can be primary.

$refstring

References the resource that the value refers to by its URI, such as the user, service principal or group entry of a group member.

typestring

Indicates the function or kind of the value within a multi-valued attribute.

valuestring

Holds the value of the attribute. For references to other resources, such as group members, this is the ID of the referenced resource.

Response​

Returns the AccountServicePrincipal object.

Replace service principal GA​

PUT /api/2.0/accounts/{account_id}/scim/v2/ServicePrincipals/{id}

Updates the details of a single service principal.

This action replaces the existing service principal that has the given ID.

API scopes: scim

Parameters​

account_idstringuuidRequiredpath

Identifies the Databricks account.

idstringint64Requiredpath

Identifies the service principal within Databricks.

Request body​

activeboolean

Indicates whether the service principal is active. A deactivated service principal cannot authenticate or access Databricks APIs, but it keeps its permissions.

applicationIdstringuuid

Sets the application ID of a Microsoft Entra ID service principal. Only Azure accepts this field. On AWS and GCP, Databricks generates the application ID and rejects requests that set it.

displayNamestring

Sets the human-readable name of the service principal. The name is required unless the request sets applicationId.

Example: etl-service

externalIdstring

Sets the identifier of the service principal in an external identity provider.

rolesarray of object

Lists the account roles that are assigned to the service principal. The only supported role value is account_admin.

Show child attributesHide child attributes
displaystring

Provides a human-readable name for the value, such as the display name of a group member.

primaryboolean

Indicates whether this is the primary or preferred value of a multi-valued attribute. At most one value can be primary.

$refstring

References the resource that the value refers to by its URI, such as the user, service principal or group entry of a group member.

typestring

Indicates the function or kind of the value within a multi-valued attribute.

valuestring

Holds the value of the attribute. For references to other resources, such as group members, this is the ID of the referenced resource.

Delete a service principal GA​

DELETE /api/2.0/accounts/{account_id}/scim/v2/ServicePrincipals/{id}

Deletes a single service principal from the <Databricks> account.

API scopes: scim

Parameters​

account_idstringuuidRequiredpath

Identifies the Databricks account.

idstringint64Requiredpath

Unique ID for a service principal in the <Databricks> account.

Update service principal details GA​

PATCH /api/2.0/accounts/{account_id}/scim/v2/ServicePrincipals/{id}

Partially updates the details of a single service principal in the <Databricks> account.

API scopes: scim

Parameters​

account_idstringuuidRequiredpath

Identifies the Databricks account.

idstringint64Requiredpath

Unique ID for a service principal in the Databricks account.

Request body​

Operationsarray of object

Lists the patch operations to apply to the service principal.

Show child attributesHide child attributes
opstring

Type of patch operation.

Values:

  • add
  • remove
  • replace
pathstring

Specifies the attribute that the operation targets, optionally with a filter that selects one value of a multi-valued attribute. The path is required for remove operations. When it is omitted, the operation applies to the resource itself and the value holds the attributes to add or replace.

valueobject

Holds the value that the operation adds or sets. Depending on the target, it is a single value, a list of entries for a multi-valued attribute, or an object with the attributes to change when the path is omitted. Remove operations do not need a value.

schemasarray of string

The schema of the patch request. Must be ["urn:ietf:params:scim:api:messages:2.0:PatchOp"].

Values:

  • urn:ietf:params:scim:api:messages:2.0:PatchOp