Workspace Service Principal

View as Markdown

The details of a ServicePrincipal resource.

Get a service principal in the accountGET /api/2.0/identity/{name=service-principals/*}List service principals in the accountGET /api/2.0/identity/service-principalsCreate a service principal in the accountPOST /api/2.0/identity/service-principalsUpdate a service principal in the accountPATCH /api/2.0/identity/{name=service-principals/*}Delete a service principal in the accountDELETE /api/2.0/identity/{name=service-principals/*}Resolve an external service principal in the Databricks accountPOST /api/2.0/identity/service-principals/resolve-by-external-id

ServicePrincipal object

The details of a ServicePrincipal resource.

namestringBetaIDImmutable

The resource name of the service principal. The format depends on the API that returned it:

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

parentstringBetaOutput onlyImmutable

The resource name of the account that contains the service principal, accounts/{account_id}. Both the account-scoped and workspace-scoped APIs return it.

account_idstringBetaOutput onlyImmutable

The parent account ID for the service principal in Databricks.

service_principal_idstringBetaOutput onlyImmutable

Internal service principal ID of the service principal in Databricks.

external_idstringBeta

ExternalId of the service principal in the customer's IdP.

application_idstringBetaImmutable

Application ID of the service principal. Set at creation time and cannot be changed afterwards; when omitted, the server generates one.

display_namestringBeta

Display name of the service principal.

account_sp_statusstringBeta

The activity status of a service principal in a Databricks account.

Values:

• ACTIVE
• INACTIVE

View as Markdown

The ServicePrincipal object

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "service_principal_id": "string",
  "external_id": "string",
  "application_id": "string",
  "display_name": "string",
  "account_sp_status": "ACTIVE"
}

Get a service principal in the account Beta

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

Fetches a service principal by its internal ID from the Databricks account that parents the calling workspace.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the service principal. Format: service-principals/{service_principal_id}

Response

Returns the ServicePrincipal object.

View as Markdown

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "service_principal_id": "string",
  "external_id": "string",
  "application_id": "string",
  "display_name": "string",
  "account_sp_status": "ACTIVE"
}

List service principals in the account Beta

GET /api/2.0/identity/service-principals

Lists the service principals in the Databricks account that parents the calling workspace, returning one page per call. Supports filtering by application ID or external ID.

API scopes: identity

Parameters

page_sizeint32query

The maximum number of SPs to return. The service may return fewer than this value. If not provided, defaults to 1000, which is also the maximum allowed. Requests for more than the maximum are clamped to 1000.

page_tokenstringquery

A page token, received from a previous ListServicePrincipals call. Provide this to retrieve the subsequent page.

filterstringquery

Optional. Allows filtering service principals by application id or external id.

parentstringquery

The resource name of the account to list service principals in, accounts/{account_id}. Optional: defaults to the account of the calling workspace, and any other account is rejected.

Response

Returns a list of ServicePrincipal objects.

View as Markdown

Response

{
  "service_principals": [
    {
      "name": "string",
      "parent": "string",
      "account_id": "string",
      "service_principal_id": "string",
      "external_id": "string",
      "application_id": "string",
      "display_name": "string",
      "account_sp_status": "ACTIVE"
    }
  ],
  "next_page_token": "string"
}

Create a service principal in the account Beta

POST /api/2.0/identity/service-principals

Creates a local service principal in the Databricks account that parents the calling workspace and returns the created service principal. A local service principal is one that is not synced from the customer's identity provider, and can be created whether or not Account Identity Management (AIM) is enabled.

When AIM is enabled, supplying an external ID returns an error. To provision the identity from your identity provider, resolve it by its external ID with ResolveServicePrincipal; to read an existing external identity, use the ExternalServicePrincipal resource.

API scopes: identity

Parameters

parentstringquery

The resource name of the account to create the service principal in, accounts/{account_id}. Optional: defaults to the account of the calling workspace, and any other account is rejected.

Request body

Required. Service principal to be created in Databricks

namestringIDImmutable

The resource name of the service principal. The format depends on the API that returned it:

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

external_idstring

ExternalId of the service principal in the customer's IdP.

application_idstringImmutable

Application ID of the service principal. Set at creation time and cannot be changed afterwards; when omitted, the server generates one.

display_namestringRequired

Display name of the service principal.

account_sp_statusstringRequired

The activity status of a service principal in a Databricks account.

Values:

• ACTIVE
• INACTIVE

Response

Returns the ServicePrincipal object.

View as Markdown

Request

{
  "name": "string",
  "external_id": "string",
  "application_id": "string",
  "display_name": "string",
  "account_sp_status": "ACTIVE"
}

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "service_principal_id": "string",
  "external_id": "string",
  "application_id": "string",
  "display_name": "string",
  "account_sp_status": "ACTIVE"
}

Update a service principal in the account Beta

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

Updates an existing service principal in the Databricks account that parents the calling workspace. Only the fields named in the update mask are modified. Returns the updated ServicePrincipal resource.

To change is_agent on a locally managed service principal, set it to true or false. Naming is_agent in the update mask without a value leaves it unchanged.

When AIM is enabled and the service principal is an external identity (its external_id is set), only external_id can be updated; its other fields are sourced from your identity provider.

API scopes: identity

Parameters

namestringRequiredIDImmutablepath

The resource name of the service principal. The format depends on the API that returned it:

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

update_maskstringRequiredquery

Required. The list of fields to update.

Request body

Required. Service principal to be updated in Databricks

external_idstring

ExternalId of the service principal in the customer's IdP.

application_idstringImmutable

Application ID of the service principal. Set at creation time and cannot be changed afterwards; when omitted, the server generates one.

display_namestringRequired

Display name of the service principal.

account_sp_statusstringRequired

The activity status of a service principal in a Databricks account.

Values:

• ACTIVE
• INACTIVE

Response

Returns the ServicePrincipal object.

View as Markdown

Request

{
  "external_id": "string",
  "application_id": "string",
  "display_name": "string",
  "account_sp_status": "ACTIVE"
}

Response

{
  "name": "string",
  "parent": "string",
  "account_id": "string",
  "service_principal_id": "string",
  "external_id": "string",
  "application_id": "string",
  "display_name": "string",
  "account_sp_status": "ACTIVE"
}

Delete a service principal in the account Beta

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

Deletes a service principal by its internal ID from the Databricks account that parents the calling workspace.

API scopes: identity

Parameters

namestringRequiredpath

The resource name of the service principal. Format: service-principals/{service_principal_id}

View as Markdown

Response

{}

Resolve an external service principal in the Databricks account Beta

POST /api/2.0/identity/service-principals/resolve-by-external-id

Resolves a service principal with the given external ID from the customer's IdP. If the service principal does not exist, it will be created. If the customer is not onboarded onto Automatic Identity Management (AIM), this will return an error.

API scopes: identity

Request body

external_idstringRequired

Required. The external ID of the service principal in the customer's IdP.

Response

service_principalobject

The service principal that was resolved.

Show child attributesHide child attributes

namestringIDImmutable

The resource name of the service principal. The format depends on the API that returned it:

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

parentstringOutput onlyImmutable

The resource name of the account that contains the service principal, accounts/{account_id}. Both the account-scoped and workspace-scoped APIs return it.

account_idstringOutput onlyImmutable

The parent account ID for the service principal in Databricks.

service_principal_idstringOutput onlyImmutable

Internal service principal ID of the service principal in Databricks.

external_idstring

ExternalId of the service principal in the customer's IdP.

application_idstringImmutable

Application ID of the service principal. Set at creation time and cannot be changed afterwards; when omitted, the server generates one.

display_namestringRequired

Display name of the service principal.

account_sp_statusstringRequired

The activity status of a service principal in a Databricks account.

Values:

• ACTIVE
• INACTIVE

View as Markdown

Request

{
  "external_id": "string"
}

Response

{
  "service_principal": {
    "name": "string",
    "parent": "string",
    "account_id": "string",
    "service_principal_id": "string",
    "external_id": "string",
    "application_id": "string",
    "display_name": "string",
    "account_sp_status": "ACTIVE"
  }
}