Skip to main content

Account Service Principal

View as Markdown

ServicePrincipal object​

A service principal in your Databricks account.

namestringIDImmutable

The resource name of the service principal, in one of these formats:

  • Account APIs: accounts/{account_id}/service-principals/{service_principal_id}
  • Workspace APIs: service-principals/{service_principal_id}
parentstringOutput onlyImmutable

The resource name of the account that contains the service principal, in the format accounts/{account_id}. Workspace APIs return the same format.

account_idstringOutput onlyImmutable

The ID of the account that contains the service principal.

service_principal_idstringOutput onlyImmutable

The Databricks ID of the service principal.

external_idstring

The ID of the service principal in your identity provider (IdP).

application_idstringImmutable

The service principal's application ID, a UUID. If you don't set it when you create the service principal, Databricks generates one. It must be unique in the account and can't be changed.

display_namestring

The service principal's display name.

account_sp_statusstring

Whether the service principal is active in the account.

Values:

  • ACTIVE
  • INACTIVE

Get a service principal in the account GA​

GET /api/2.0/identity/{name=accounts/*/service-principals/*}

Gets a service principal by its Databricks ID.

API scopes: identity

Parameters​

namestringRequiredpath

The resource name of the service principal, in the format accounts/{account_id}/service-principals/{service_principal_id}.

Response​

Returns the ServicePrincipal object.

List service principals in the account GA​

GET /api/2.0/identity/{parent=accounts/*}/service-principals

Lists the service principals in your account, sorted by Databricks ID. Service principals in your identity provider that haven't been added to Databricks aren't included.

API scopes: identity

Parameters​

parentstringRequiredpath

The resource name of the account to list service principals in, in the format accounts/{account_id}.

page_sizeint32query

The maximum number of service principals to return, up to 1000. The default is 1000. A page can contain fewer service principals.

page_tokenstringquery

The next_page_token from a previous response, to get the next page.

filterstringquery

Filters service principals by application_id or external_id, for example application_id eq "<application-id>". Put the value in quotes.

Response​

Returns a list of ServicePrincipal objects.

Create a service principal in the account GA​

POST /api/2.0/identity/{parent=accounts/*}/service-principals

Creates a local service principal, which is a service principal that isn't synced from your identity provider (IdP).

If automatic identity management is on, you can't set external_id. To add a service principal from your IdP, get it as an external service principal instead.

API scopes: identity

Parameters​

parentstringRequiredpath

The resource name of the account to create the service principal in, in the format accounts/{account_id}.

Request body​

The service principal to create.

namestringIDImmutable

The resource name of the service principal, in one of these formats:

  • Account APIs: accounts/{account_id}/service-principals/{service_principal_id}
  • Workspace APIs: service-principals/{service_principal_id}
external_idstring

The ID of the service principal in your identity provider (IdP).

application_idstringImmutable

The service principal's application ID, a UUID. If you don't set it when you create the service principal, Databricks generates one. It must be unique in the account and can't be changed.

display_namestringRequired

The service principal's display name.

account_sp_statusstringRequired

Whether the service principal is active in the account.

Values:

  • ACTIVE
  • INACTIVE

Response​

Returns the ServicePrincipal object.

Update a service principal in the account GA​

PATCH /api/2.0/identity/{name=accounts/*/service-principals/*}

Updates a service principal. Only the fields in update_mask change.

If automatic identity management is on and the service principal has an external_id, you can only update external_id. Its other fields come from your identity provider. A service principal can't deactivate itself, and you can't update service principals that Databricks manages.

API scopes: identity

Parameters​

namestringRequiredIDImmutablepath

The resource name of the service principal, in one of these formats:

  • Account APIs: accounts/{account_id}/service-principals/{service_principal_id}
  • Workspace APIs: service-principals/{service_principal_id}
update_maskstringRequiredquery

The fields to update, separated by commas. You can update display_name, account_sp_status, and external_id.

Request body​

The service principal to update. Its name identifies the service principal.

external_idstring

The ID of the service principal in your identity provider (IdP).

application_idstringImmutable

The service principal's application ID, a UUID. If you don't set it when you create the service principal, Databricks generates one. It must be unique in the account and can't be changed.

display_namestringRequired

The service principal's display name.

account_sp_statusstringRequired

Whether the service principal is active in the account.

Values:

  • ACTIVE
  • INACTIVE

Response​

Returns the ServicePrincipal object.

Delete a service principal in the account GA​

DELETE /api/2.0/identity/{name=accounts/*/service-principals/*}

Deletes a service principal from your account and removes it from the workspaces it's assigned to. You can't delete service principals that Databricks manages.

API scopes: identity

Parameters​

namestringRequiredpath

The resource name of the service principal, in the format accounts/{account_id}/service-principals/{service_principal_id}.

Resolve an external service principal in the Databricks account Beta​

POST /api/2.0/identity/accounts/{account_id}/service-principals/resolve-by-external-id

Gets a service principal by its ID in your identity provider (IdP) and syncs its details and group memberships from your IdP. If the service principal isn't in your account yet, it's added. Requires automatic identity management with Microsoft Entra ID as your IdP.

API scopes: identity

Parameters​

account_idstringRequiredpath

The ID of the account to resolve the service principal in.

Request body​

external_idstringRequired

The ID of the service principal in your IdP.

Response​

service_principalobject

The resolved service principal.

Show child attributesHide child attributes
namestringIDImmutable

The resource name of the service principal, in one of these formats:

  • Account APIs: accounts/{account_id}/service-principals/{service_principal_id}
  • Workspace APIs: service-principals/{service_principal_id}
parentstringOutput onlyImmutable

The resource name of the account that contains the service principal, in the format accounts/{account_id}. Workspace APIs return the same format.

account_idstringOutput onlyImmutable

The ID of the account that contains the service principal.

service_principal_idstringOutput onlyImmutable

The Databricks ID of the service principal.

external_idstring

The ID of the service principal in your identity provider (IdP).

application_idstringImmutable

The service principal's application ID, a UUID. If you don't set it when you create the service principal, Databricks generates one. It must be unique in the account and can't be changed.

display_namestringRequired

The service principal's display name.

account_sp_statusstringRequired

Whether the service principal is active in the account.

Values:

  • ACTIVE
  • INACTIVE