Uc Rfa

View as Markdown

Control access to Unity Catalog resources

Batch Create Access RequestsPOST /api/3.0/rfa/requests

Batch Create Access Requests Public Preview

POST /api/3.0/rfa/requests

Creates access requests for Unity Catalog permissions for a specified principal on a securable object. This Batch API can take in multiple principals, securable objects, and permissions as the input and returns the access request destinations for each. Principals must be unique across the API call.

The supported securable types are: "metastore", "catalog", "schema", "table", "external_location", "connection", "credential", "function", "registered_model", and "volume".

API scopes: unity-catalog

Request body

requestsarray of object

A list of individual access requests, where each request corresponds to a set of permissions being requested on a list of securables for a specified principal.

At most 30 requests per API call.

Show child attributesHide child attributes

behalf_ofobject

Optional. The principal this request is for. Empty behalf_of defaults to the requester's identity.

Principals must be unique across the API call.

Show child attributesHide child attributes

idstring

<Databricks> user, group or service principal ID.

principal_typestring

Values: PRINCIPAL_TYPE_UNSPECIFIED, USER_PRINCIPAL, GROUP_PRINCIPAL, SERVICE_PRINCIPAL

commentstring

Optional. Comment associated with the request.

At most 200 characters, can only contain lowercase/uppercase letters (a-z, A-Z), numbers (0-9), punctuation, and spaces.

securable_permissionsarray of object

List of securables and their corresponding requested UC privileges.

At most 30 securables can be requested for a principal per batched call. Each securable can only be requested once per principal.

Show child attributesHide child attributes

securableobject

The securable for which the access request destinations are being requested.

Show child attributesHide child attributes

typestring

Required. The type of securable (catalog/schema/table). Optional if resource_name is present.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

full_namestring

Required. The full name of the catalog/schema/table. Optional if resource_name is present.

provider_sharestring

Optional. The name of the Share object that contains the securable when the securable is getting shared in D2D Delta Sharing.

permissionsarray of string

List of requested Unity Catalog permissions.

Response

responsesarray of object

The access request destinations for each securable object the principal requested.

Show child attributesHide child attributes

behalf_ofobject

The principal the request was made on behalf of.

Show child attributesHide child attributes

idstring

<Databricks> user, group or service principal ID.

principal_typestring

Values: PRINCIPAL_TYPE_UNSPECIFIED, USER_PRINCIPAL, GROUP_PRINCIPAL, SERVICE_PRINCIPAL

request_destinationsarray of object

The access request destinations for all the securables the principal requested.

Show child attributesHide child attributes

destinationsarray of object

The access request destinations for the securable.

Show child attributesHide child attributes

destination_idstring

The identifier for the destination. This is the email address for EMAIL destinations, the URL for URL destinations, or the unique <Databricks> notification destination ID for all other external destinations.

Example: john.doe@databricks.com

destination_typestring

The type of the destination.

Values: DESTINATION_TYPE_UNSPECIFIED, EMAIL, SLACK, GENERIC_WEBHOOK, MICROSOFT_TEAMS, URL

Example: EMAIL

special_destinationstring

This field is used to denote whether the destination is the email of the owner of the securable object. The special destination cannot be assigned to a securable and only represents the default destination of the securable. The securable types that support default special destinations are: "catalog", "external_location", "connection", "credential", and "metastore". The destination_type of a special_destination is always EMAIL.

Values: SPECIAL_DESTINATION_UNSPECIFIED, SPECIAL_DESTINATION_CATALOG_OWNER, SPECIAL_DESTINATION_EXTERNAL_LOCATION_OWNER, SPECIAL_DESTINATION_CONNECTION_OWNER, SPECIAL_DESTINATION_CREDENTIAL_OWNER, SPECIAL_DESTINATION_METASTORE_OWNER, SPECIAL_DESTINATION_SCHEMA_OWNER, SPECIAL_DESTINATION_TABLE_OWNER, SPECIAL_DESTINATION_VOLUME_OWNER, SPECIAL_DESTINATION_FUNCTION_OWNER, SPECIAL_DESTINATION_REGISTERED_MODEL_OWNER

Example: SPECIAL_DESTINATION_CATALOG_OWNER

securableobject

The securable for which the access request destinations are being modified or read.

Show child attributesHide child attributes

typestring

Required. The type of securable (catalog/schema/table). Optional if resource_name is present.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

full_namestring

Required. The full name of the catalog/schema/table. Optional if resource_name is present.

provider_sharestring

Optional. The name of the Share object that contains the securable when the securable is getting shared in D2D Delta Sharing.

are_any_destinations_hiddenboolean

Indicates whether any destinations are hidden from the caller due to a lack of permissions. This value is true if the caller does not have permission to see all destinations.

Example: false

destination_source_securableobject

The source securable from which the destinations are inherited. Either the same value as securable (if destination is set directly on the securable) or the nearest parent securable with destinations set.

Show child attributesHide child attributes

typestring

Required. The type of securable (catalog/schema/table). Optional if resource_name is present.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

full_namestring

Required. The full name of the catalog/schema/table. Optional if resource_name is present.

provider_sharestring

Optional. The name of the Share object that contains the securable when the securable is getting shared in D2D Delta Sharing.

securable_typestring

The type of the securable. Redundant with the type in the securable object, but necessary for Terraform integration

full_namestring

The full name of the securable. Redundant with the name in the securable object, but necessary for Terraform integration

View as Markdown

Request

{
  "requests": [
    {
      "behalf_of": {
        "id": "5617094356186623",
        "principal_type": "USER_PRINCIPAL"
      },
      "comment": "Requesting SELECT on main.customers.information table",
      "securable_permissions": [
        {
          "permissions": [
            "USE_CATALOG"
          ],
          "securable": {
            "full_name": "main",
            "type": "CATALOG"
          }
        },
        {
          "permissions": [
            "USE_SCHEMA"
          ],
          "securable": {
            "full_name": "main.customers",
            "type": "SCHEMA"
          }
        },
        {
          "permissions": [
            "SELECT",
            "MODIFY"
          ],
          "securable": {
            "full_name": "main.customers.information",
            "type": "TABLE"
          }
        }
      ]
    },
    {
      "securable_permissions": [
        {
          "permissions": [
            "USE_SCHEMA"
          ],
          "securable": {
            "full_name": "main.orders",
            "type": "SCHEMA"
          }
        }
      ]
    }
  ]
}

Response

{
  "responses": [
    {
      "behalf_of": {
        "id": "5617094356186623",
        "principal_type": "USER_PRINCIPAL"
      },
      "request_destinations": [
        {
          "are_any_destinations_hidden": false,
          "destination_source_securable": {
            "full_name": "main",
            "type": "CATALOG"
          },
          "destinations": [
            {
              "destination_id": "john.doe@databricks.com",
              "destination_type": "EMAIL"
            }
          ],
          "securable": {
            "full_name": "main",
            "type": "CATALOG"
          }
        },
        {
          "are_any_destinations_hidden": false,
          "destination_source_securable": {
            "full_name": "main.customers",
            "type": "SCHEMA"
          },
          "destinations": [
            {
              "destination_id": "456e7890-e89b-12d3-a456-426614174001",
              "destination_type": "SLACK"
            }
          ],
          "securable": {
            "full_name": "main.customers",
            "type": "SCHEMA"
          }
        },
        {
          "are_any_destinations_hidden": false,
          "destination_source_securable": {
            "full_name": "main.customers",
            "type": "SCHEMA"
          },
          "destinations": [
            {
              "destination_id": "abcde123-e89b-12d3-a456-426614174003",
              "destination_type": "GENERIC_WEBHOOK"
            }
          ],
          "securable": {
            "full_name": "main.customers.information",
            "type": "TABLE"
          }
        }
      ]
    },
    {
      "behalf_of": {
        "id": "7246801356408068",
        "principal_type": "USER_PRINCIPAL"
      }
    }
  ]
}