Account Identity Visibility Filter

View as Markdown

An account-level rule that controls which identity provider groups are discoverable in directory search and group pickers when automatic identity management is enabled. Filters apply across all workspaces in the account.

If no group filters are configured, all groups are visible. Otherwise, a group is visible if it or any of its transitive parent groups matches at least one rule. A group is also visible if it or any transitive parent group is already provisioned in the account. Local Databricks groups remain visible regardless of the filters.

Only group filters can be created. Filters do not change provisioning or sign-in for users and service principals. Filters are immutable: to change a rule, delete it and create a new one.

Get an identity-visibility filterGET /api/2.0/identity/{name=accounts/*/identity-visibility-filters/*}List the identity-visibility filters in the accountGET /api/2.0/identity/{parent=accounts/*}/identity-visibility-filtersCreate an identity-visibility filter in the accountPOST /api/2.0/identity/{parent=accounts/*}/identity-visibility-filtersDelete an identity-visibility filterDELETE /api/2.0/identity/{name=accounts/*/identity-visibility-filters/*}

IdentityVisibilityFilter object

An account-level rule that controls which identity provider groups are discoverable in directory search and group pickers when automatic identity management is enabled. Filters apply across all workspaces in the account.

If no group filters are configured, all groups are visible. Otherwise, a group is visible if it or any of its transitive parent groups matches at least one rule. A group is also visible if it or any transitive parent group is already provisioned in the account. Local Databricks groups remain visible regardless of the filters.

Only group filters can be created. Filters do not change provisioning or sign-in for users and service principals. Filters are immutable: to change a rule, delete it and create a new one.

namestringPublic PreviewOutput onlyIDImmutable

The resource name of the identity-visibility filter. Format: accounts/{account_id}/identity-visibility-filters/{identity_visibility_filter_id}

principal_typestringPublic PreviewImmutable

The type of principal this rule applies to. Set to GROUP when creating a filter. Other principal types are not supported for creation.

Values:

• USER
• SERVICE_PRINCIPAL
• GROUP

exactobjectPublic PreviewImmutable

Exact match on the group's external ID from the identity provider.

Show child attributesHide child attributes

external_idstringPublic PreviewImmutable

The identity provider's external ID for the group to match. This is not the Databricks group ID. The value must be non-empty and is matched exactly, including case.

prefixobjectPublic PreviewImmutable

Case-sensitive starts-with match on the group's display name.

Show child attributesHide child attributes

display_name_prefixstringPublic PreviewImmutable

The display-name prefix to match. Must contain at least one non-whitespace character. Leading and trailing whitespace are preserved, and matching is case-sensitive.

View as Markdown

The IdentityVisibilityFilter object

{
  "name": "string",
  "principal_type": "USER",
  "exact": {
    "external_id": "string"
  },
  "prefix": {
    "display_name_prefix": "string"
  }
}

Get an identity-visibility filter Public Preview

GET /api/2.0/identity/{name=accounts/*/identity-visibility-filters/*}

Gets a group visibility filter by its resource name. Requires account admin privileges. Returns the filter rule, not the groups matched by the rule.

API scopes: identity

Parameters

namestringRequiredpath

Required. The resource name of the filter. Format: accounts/{account_id}/identity-visibility-filters/{identity_visibility_filter_id}

Response

Returns the IdentityVisibilityFilter object.

View as Markdown

Response

{
  "name": "string",
  "principal_type": "USER",
  "exact": {
    "external_id": "string"
  },
  "prefix": {
    "display_name_prefix": "string"
  }
}

List the identity-visibility filters in the account Public Preview

GET /api/2.0/identity/{parent=accounts/*}/identity-visibility-filters

Lists group visibility filters in the account, returning one page per call. Requires account admin privileges. Returns filter rules, not the groups matched by those rules. To retrieve the next page, pass the response's next_page_token as page_token in the next request. If next_page_token is omitted, there are no more pages.

API scopes: identity

Parameters

parentstringRequiredpath

Required. The parent account. Format: accounts/{account_id}

page_sizeint32query

The maximum number of filters to return. The service may return fewer than this value. If omitted or non-positive, defaults to 100. Values above 1000 are reduced to 1000.

page_tokenstringquery

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

Response

Returns a list of IdentityVisibilityFilter objects.

View as Markdown

Response

{
  "identity_visibility_filters": [
    {
      "name": "string",
      "principal_type": "USER",
      "exact": {},
      "prefix": {}
    }
  ],
  "next_page_token": "string"
}

Create an identity-visibility filter in the account Public Preview

POST /api/2.0/identity/{parent=accounts/*}/identity-visibility-filters

Creates a group visibility filter in the account. Requires account admin privileges. Set principal_type to GROUP and specify exactly one of exact (external ID) or prefix (display-name starts with). The filter applies across all workspaces in the account. A duplicate filter ID or an existing rule with the same type and match value returns ALREADY_EXISTS. Filters are immutable; to change a rule, delete it and create a new one.

API scopes: identity

Parameters

parentstringRequiredpath

Required. The parent account. Format: accounts/{account_id}

identity_visibility_filter_idstringquery

Optional. The ID to use for the filter, which becomes the final component of its resource name. If not specified or empty, the server generates one. Must not contain /.

Request body

Required. The filter to create. Set principal_type to GROUP and specify exactly one of exact or prefix. The server assigns the resource name; any supplied name is ignored.

principal_typestringRequiredImmutable

The type of principal this rule applies to. Set to GROUP when creating a filter. Other principal types are not supported for creation.

Values:

• USER
• SERVICE_PRINCIPAL
• GROUP

exactobjectImmutable

Exact match on the group's external ID from the identity provider.

Show child attributesHide child attributes

external_idstringRequiredImmutable

The identity provider's external ID for the group to match. This is not the Databricks group ID. The value must be non-empty and is matched exactly, including case.

prefixobjectImmutable

Case-sensitive starts-with match on the group's display name.

Show child attributesHide child attributes

display_name_prefixstringRequiredImmutable

The display-name prefix to match. Must contain at least one non-whitespace character. Leading and trailing whitespace are preserved, and matching is case-sensitive.

Response

Returns the IdentityVisibilityFilter object.

View as Markdown

Request

{
  "principal_type": "USER",
  "exact": {
    "external_id": "string"
  },
  "prefix": {
    "display_name_prefix": "string"
  }
}

Response

{
  "name": "string",
  "principal_type": "USER",
  "exact": {
    "external_id": "string"
  },
  "prefix": {
    "display_name_prefix": "string"
  }
}

Delete an identity-visibility filter Public Preview

DELETE /api/2.0/identity/{name=accounts/*/identity-visibility-filters/*}

Deletes a group visibility filter by its resource name. Requires account admin privileges. Deleting a filter does not delete groups or revoke access. Groups covered only by this rule stop being discoverable unless they or a transitive parent are already provisioned in the account. If no group filters remain, all groups become visible again. Deleting a filter that does not exist succeeds without making any changes.

API scopes: identity

Parameters

namestringRequiredpath

Required. The resource name of the filter. Format: accounts/{account_id}/identity-visibility-filters/{identity_visibility_filter_id}

View as Markdown

Response

{}